---
title: "i18n"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/i-18-n'
  md: 'https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/i-18-n.md'
---
# 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 accessibility and user experience across 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{#JVfaW}

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

```latex
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{#Oh4l3}

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

<table>
  <colgroup>
    <col/>
    <col/>
    <col/>
    <col/>
  </colgroup>
  <tbody>
    <tr>
      <th>
        <p><strong>File type</strong></p>
      </th>
      <th>
        <p><strong>Application scope</strong></p>
      </th>
      <th>
        <p><strong>Targeted audience</strong></p>
      </th>
      <th>
        <p><strong>Example path</strong></p>
      </th>
    </tr>
    <tr>
      <td colSpan="1" rowSpan="1">
        \*.json
      </td>
      <td colSpan="1" rowSpan="1">
        Theme
      </td>
      <td colSpan="1" rowSpan="1">
        Customers
      </td>
      <td colSpan="1" rowSpan="1">
        i18n/en.json
      </td>
    </tr>
    <tr>
      <td colSpan="1" rowSpan="1">
        \*.schema.json
      </td>
      <td colSpan="1" rowSpan="1">
        Theme editor controls
      </td>
      <td colSpan="1" rowSpan="1">
        Merchants
      </td>
      <td colSpan="1" rowSpan="1">
        i18n/en.schema.json
      </td>
    </tr>
  </tbody>
</table>

### File naming convention{#NBzLq}

The naming of multilingual files follows the [IETF BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) 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{#a99Tu}

### File structure specification{#RHfVv}

It is recommended to keep multilingual JSON files well-organized to simplify long-term maintenance. The following example demonstrates a recommended structure for a language file:

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

The field explanation in the above structure is as follows:

<table>
  <colgroup>
    <col/>
    <col/>
    <col/>
    <col/>
  </colgroup>
  <tbody>
    <tr>
      <th>
        <p><strong>Field</strong></p>
      </th>
      <th>
        <p><strong>Type</strong></p>
      </th>
      <th>
        <p><strong>Description</strong></p>
      </th>
      <th>
        <p><strong>Example</strong></p>
      </th>
    </tr>
    <tr>
      <td>FirstLevel</td>
      <td>First-level category</td>
      <td>Page or general type, such as products, orders, and search</td>
      <td>search</td>
    </tr>
    <tr>
      <td>SecondLevel</td>
      <td>Second-level module</td>
      <td>The module on a page, such as a list and details</td>
      <td>product_list</td>
    </tr>
    <tr>
      <td>Description</td>
      <td>Element description</td>
      <td>Detailed description of a specific element, such as a button or title</td>
      <td>title</td>
    </tr>
  </tbody>
</table>

> **tip**
>
> You can customize the structure of theme multilingual files, but make sure that the hierarchical structure is clear.


### File structure example{#wDjZu}

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

```latex
// 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](#fhAnn) for more about how to dynamically insert variables.

### Reference multilingual text{#tZsLi}

In the search section, you can reference the key `search.results_count` using the [t](https://developer.shopline.com/docs/sline/filter/t.md) filter. The following is an example of how the key is referenced in the `sections/main-search/main-search.html` section file.

```latex
<!-- 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{#fhAnn}

In the [structure example](#wDjZu) 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:

#### 1\. Invoke the template{#ZETQj}

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

```latex
<!-- 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}}
```

#### 2\. Render result{#zfCYa}

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

```latex
<!-- 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{#OlSrr}

The following is an example from the Blog [section schema](https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/sections.md?lang=en#Fc76g) 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.

```latex
// sections/blog/blog.html

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

### File structure example{#e0pa7}

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

```latex
// 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{#oZbFS}

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{#OHHSn}

In the [multilingual JSON file](#e0pa7) 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:

```json
// 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{#WZrtr}

In the [multilingual JSON file](#e0pa7) 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](#OlSrr). 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:

```json
// 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{#U99SY}

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

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

```latex
<!-- 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}}
```