i18n

The i18n directory contains multilingual JSON files for themes. These files are used to present information in the local language of customers or merchants, enhancing the access experience for customers and merchants in different regions. Multilingual files support text configuration in the following two scenarios:

Theme multilingual text: Multilingual text displayed to the customer.
Control multilingual text: Multilingual text displayed to the merchant, mainly referring to text on the theme editor configuration controls.

Directory structure

The following is an example of the i18n directory extracted from a theme.

i18n                       	# Multilingual root directory
├── en.json                 # English theme text
├── en.schema.json          # English editor text
├── zh-hans-cn.json         # Simplified Chinese theme text
├── zh-hans-cn.schema.json  # Simplified Chinese editor text
├── th.json                 # Thai theme text
└── th.schema.json          # Thai editor text

Supported file types

Multilingual files support two file extension types, serving different scenarios, with detailed explanations as follows:

File type	Application scope	Targeted audience	Example path
*.json	Theme	Customers	i18n/en.json
*.schema.json	Theme editor controls	Merchants	i18n/en.schema.json

File naming convention

The naming of multilingual files follows the IETF BCP 47 standard. The following are naming examples for Simplified Chinese and English language files:

zh-hans-cn.json
zh-hans-cn.schema.json
en.json
en.schema.json

Theme multilingual files

File structure specification

It is recommended that multilingual JSON files be kept tidy, which aids in subsequent understanding and maintenance. The following example demonstrates a recommended structure for a language file:

{
  "<FirstLevel>": {
    "<Description>": "Translated text"
    "<SecondLevel>": {
      "<Description>": "Translated text"
    }
  }
}

The field explanation in the above structure is as follows:

Field	Type	Description	Example
<FirstLevel>	First-level category	Page or general type, such as products, orders, and research	search
<SecondLevel>	Second-level module	The module on a page, such as a list and details	product_list
<Description>	Element description	Detailed description of a specific element, such as a button or title	title

Tip: You can customize the structure of theme multilingual files, but make sure that the hierarchical structure is clear.

File structure example

The following is the JSON file structure of the search page displaying the number of search results in English.

// i18n/en.json
{
  "search": {															// First-level category
    "count_results": "{{count}} Results", // Element description: Number of search results
    "product_list": {											// Second-level module
      "title": "Products"									// Element description
    }
  }
}

In the above example, the variable count is inserted into {{count}} Results. You can refer to Interpolate variables for more about how to dynamically insert variables.

Reference multilingual text

In the search section, you can reference the key search.results_count using the t filter. The following is an example of how the key is referenced in the sections/main-search/main-search.html section file.

<!-- sections/main-search/main-search.html -->
{{#if search.performed}}
  <div class="main-search__count">
    <!-- Reference multilingual text key name -->
    <h4 class="title-font-bold">{{"search.count_results" | t(count=search.results_count)}}</h4>
    ...
  </div>
{{/if}}

Interpolate variables

In the structure example above, the multilingual text for the number of search results {{count}} Results includes a variable count referenced through {{ }}. This is a method for dynamically injecting data into multilingual text. Here is a detailed explanation:

Invoke the template

In the section, you can achieve variable substitution by passing the count parameter to the t filter:

<!-- sections/main-search/main-search.html -->
{{#if search.performed}}
  <div class="main-search__count">
    <!-- Pass the variable count -->
    <h4 class="title-font-bold">{{"search.count_results" | t(count=search.results_count)}}</h4>
    ...
  </div>
{{/if}}

Render result

When search.results_count=5, the rendered HTML is as follows:

<!-- sections/main-search/main-search.html -->
<div class="main-search__count">
  <!-- Pass the variable count -->
  <h4 class="title-font-bold">5 Results</h4>
  ...
</div>

Control multilingual files

The following is an example from the Blog section schema within a theme. Both name and label contain multilingual texts. The following parts use this example to demonstrate the structure standards and configuration of the associated control multilingual file.

// sections/blog/blog.html
{{#schema}}
{
  "name": "Blogs Name", 		// Section name to be translated
  "settings": [
    {
      "type": "blog", 			// Control type
      "id": "blog",         // Control ID
      "label": "Blogs List" // Control label to be translated
    }
  ]
}
{{/schema}}

File structure example

The following example shows the multilingual JSON file structure of the blog section.

// i18n/en.json
{
  "sections": {                      // First-level section directory name
    "blog": {                        // Section file name
      "name": "Blogs Name New",      // Section name
      "settings": {
        "blog_id": {                 // Control ID
          "label": "Blogs List New"  // Control label description
        }
      }
    }
  }
}

Tip: You can customize the structure of theme multilingual files, but make sure that the hierarchical structure is clear.

Multilingual key naming convention

When defining the key names in the multilingual JSON structure, it is recommended to adopt a nested combination of "theme module file directory" and "theme module file schema structure" to generate a unique key name.

Example of the section key name

In the multilingual JSON file example mentioned above, the naming method for the section key name sections.blog.name is as follows:

Section file directory: Extract the top-level directory name and section file name from the section file directory sections/blog/blog.html as sections.blog.
Section file schema structure: The structure of the section name that needs to be translated, "name": "Blogs Name", is at the first level of the schema. Directly extract the field name name.

After the combination, the final section key name sections.blog.name is obtained.

The complete example of the section key name in the multilingual file is as follows:

// i18n/en.json
{
  "sections": {             				// First-level section directory name
    "blog": {               				// Section file name
      "name": "Blogs Name New"			// Section name
      }
    }
  }
}

Example of the control label key name

In the multilingual JSON file example mentioned above, the naming method for the control label key name sections.blog.settings.block_id.label is as follows:

Section file directory: Extract the top-level directory name and section file name from the section file directory sections/blog/blog.html as sections.blog.
Section file schema structure: For the structure of the control label that needs to be translated, refer to the theme blog schema example in the introduction of the control multilingual file. Extract the control label field settings.label.

However, because section settings may contain multiple labels, to ensure the uniqueness of the key name, the control ID is added before the control label name to prevent naming duplication.

After the combination, the final control label key name sections.blog.settings.block_id.label is obtained.

The complete example of the control label key name in the multilingual file is as follows:

// i18n/en.json
{
  "sections": {             				// First-level section directory name
    "blog": {               				// Section file name
      "settings": {
        "blog_id": {								// Control ID
          "label": "Blogs List New"	// Control label description
        }
      }
    }
  }
}

Multilingual configuration

In the section file, replace the schema text with the corresponding unique key names.

Note: A t: prefix is required before the key name, signaling to the visual editor that this is a multilingual key.

<!-- sections/blog/blog.html -->
{{#schema}}
{
  "name": "t:sections.blog.name", 										// Replaced key name
  "settings": [
    {
      "type": "blog", 																// Control type
      "id": "blog_id",
      "label": "t:sections.blog.settings.blog.label"	// Replaced key name
    }
  ]
}
{{/schema}}