---
title: "i18n"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/i-18-n'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/i-18-n.md'
---
# i18n

`i18n` 目录包含了主题的多语言 JSON 文件，用于以客户或商家的当地语言向其呈现信息，提升不同地区商家和客户的访问体验。多语言文件支持以下两种场景的配置：

-   **主题多语言**：面向客户端显示的多语言文本
    
-   **控件多语言**：面向商家端（主要指主题编辑器配置控件）显示的多语言文本
    

* * *

## 目录结构{#m3Hpw}

### 标准目录{#LlypP}

以下是标准主题中截取的部分目录示例：

```bash
i18n                        # 多语言根目录
├── en.json                 # 英语主题文本
├── en.schema.json          # 英语编辑器文本
├── zh-hans-cn.json         # 简体中文主题文本
├── zh-hans-cn.schema.json  # 简体中文编辑器文本
├── th.json                 # 泰语主题文本
└── th.schema.json          # 泰语编辑器文本
```

### 支持的文件类型{#n3rQX}

多语言文件包含两种后缀名，分别服务于不同场景，详细说明如下：

<table>
  <colgroup>
    <col/>
    <col/>
    <col/>
    <col/>
  </colgroup>
  <tbody>
    <tr>
      <th>
        <p><strong>文件类型</strong></p>
      </th>
      <th>
        <p><strong>作用域</strong></p>
      </th>
      <th>
        <p><strong>服务对象</strong></p>
      </th>
      <th>
        <p><strong>示例路径</strong></p>
      </th>
    </tr>
    <tr>
      <td colSpan="1" rowSpan="1">
        \*.json
      </td>
      <td colSpan="1" rowSpan="1">
        主题
      </td>
      <td colSpan="1" rowSpan="1">
        客户端
      </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">
        控件（主题编辑器）
      </td>
      <td colSpan="1" rowSpan="1">
        商家端
      </td>
      <td colSpan="1" rowSpan="1">
        i18n/en.schema.json
      </td>
    </tr>
  </tbody>
</table>

### 文件命名规范{#wK3Kd}

多语言文件的命名遵循 [IETF BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) 标准，以下为中文简体和英文语种文件的命名示例：

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

* * *

## 主题多语言文件{#fGlzS}

### 结构规范{#C6hp9}

我们建议多语言 JSON 需要保持整洁，这有利于后续的理解和维护。以下是一个多语言结构块的规范建议：

```json
{
  "<FirstLevel>": {
    "<Description>": "翻译文本"
    "<SecondLevel>": {
      "<Description>": "翻译文本"
    }
  }
}
```

如上规范结构中的字段说明如下：

<table>
  <thead>
    <tr>
      <th>字段</th>
      <th>类型</th>
      <th>描述</th>
      <th>示例</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>FirstLevel</td>
      <td>一级分类</td>
      <td>页面或通用类型（如商品、订单、搜索）</td>
      <td>search</td>
    </tr>
    <tr>
      <td>SecondLevel</td>
      <td>二级模块</td>
      <td>页面中的模块（如列表、详情）</td>
      <td>product_list</td>
    </tr>
    <tr>
      <td>Description</td>
      <td>元素描述</td>
      <td>对具体的元素（如按钮、标题）进行详细描述</td>
      <td>title</td>
    </tr>
  </tbody>
</table>

> **提示**
>
> 你可以自定义主题多语言文件结构，但请确保层级结构清晰。

### 结构示例{#d3R18}

以下是搜索页面展示搜索结果数量多语言的 JSON 文件结构：

```json
// i18n/en.json

{
  "search": {                               // 一级分类
    "count_results": "{{count}} Results",   // 元素描述：“搜索结果数量”
    "product_list": {                       // 二级模块
      "title": "Products"                   // 元素描述
    }
  }
}
```

其中，`{{count}} Results` 中插入了变量 `count`，你可以参考 [变量插值](#EclGx) 查看更多关于如何动态插入变量。

### 引用方式{#WwpLn}

在组件代码中，你可以通过 [t](https://developer.shopline.com/zh-hans-cn/docs/sline/filter/t.md) filter 实现对上述 `search.results_count` 键名的引用，以下是在组件 `sections/main-search/main-search.html` 文件中的引用示例：

```html
<!-- sections/main-search/main-search.html -->

{{#if search.performed}}
  <div class="main-search__count">
    <!-- 引用对应键名 -->
    <h4 class="title-font-bold">{{"search.count_results" | t(count=search.results_count)}}</h4>
    ...
  </div>
{{/if}}
```

### 变量插值{#EclGx}

在如上 [结构示例](#d3R18) 中，搜索结果数量的多语言文本 `{{count}} Results` 包含了通过 `{{ }}` 引用的变量 `count`，这是实现对多语言文本的动态数据注入的方法。以下是具体示例：

#### 1\. 模版调用{#MahaQ}

在模板中，我们可以通过给 t filter 传递 `count` 参数，以达到变量替换的效果：

```html
<!-- sections/main-search/main-search.html -->

{{#if search.performed}}
  <div class="main-search__count">
    <!-- count 变量传递 -->
    <h4 class="title-font-bold">{{"search.count_results" | t(count=search.results_count)}}</h4>
    ...
  </div>
{{/if}}
```

#### 2\. 渲染结果{#QZFse}

当 `search.results_count=5` 时，渲染的 HTML 如下所示：

```html
<!-- sections/main-search/main-search.html -->

<div class="main-search__count">
  <!-- count 变量传递 -->
  <h4 class="title-font-bold">5 Results</h4>
  ...
</div>

```

* * *

## 控件多语言文件{#fljtk}

如下是主题博客组件 [schema](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/sections.md#HWiNw) 内容示例，展示关联的控件多语言文件的结构规范与配置。其中 `name`（组件名） 和 `label`（控件标签描述） 都是需要支持多语言的：

```json
// sections/blog/blog.html

{{#schema}}
{
  "name": "Blogs Name",           // 需要翻译的组件名
  "settings": [
    {
      "type": "blog",             // 控件类型
      "id": "blog_id",            // 控件 ID
      "label": "Blogs List"       // 需要翻译的控件标签描述
    }
  ]
}
{{/schema}}
```

### 文件结构示例{#EwmE2}

多语言 JSON 文件结构示例如下：

```json
// i18n/en.json

{
  "sections": {                          // 一级目录名称
    "blog": {                            // 组件文件名
      "name": "Blogs Name New",          // 组件名
      "settings": {
        "blog_id": {                     // 控件 ID
          "label": "Blogs List New"      // 控件标签描述
        }
      }
    }
  }
}
```

> **提示**
>
> 你可以自定义控件多语言文件结构，但请确保层级结构清晰。

### 多语言键名命名规范{#oZbFS}

在定义多语言 JSON 结构的键名时，建议采用 "主题模块文件目录" 加 "主题模块文件 schema 结构" 的嵌套组合方式，以生成唯一键名。

#### 组件名示例{#OHHSn}

在如上 [多语言 JSON 文件示例](#EwmE2) 中，组件名键名 `sections.blog.name` 的命名方式如下：

-   **组件文件目录**：提取组件文件目录 `sections/blog/blog.html` 的一级目录名及组件文件名 `sections.blog`。
    
-   **组件文件 schema 结构**：需要被翻译的组件名的结构 `"name": "Blogs Name"` 在 schema 的第一层级，直接提取字段名 `name`。
    

通过组合后，得到最终组件的键名 `sections.blog.name`。

##### 组件名在多语言文件中的完整示例{#JLwwe}

```json
// i18n/en.json

{
  "sections": {                  // 一级目录名称
    "blog": {                    // 组件文件名
      "name": "Blogs Name New"   // 组件名
      }
    }
  }
}
```

#### 控件标签描述示例{#WZrtr}

在如上 [多语言 JSON 文件示例](#EwmE2) 中，控件标签键名 `sections.blog.settings.block_id.label` 的命名方式如下：

-   **组件文件目录**：提取组件文件目录 `sections/blog/blog.html` 的一级目录名及组件文件名 `sections.blog`。
    
-   **组件文件 schema 结构**：需要被翻译的控件标签结构具体见 [控件多语言文件](#fljtk) 介绍中的主题博客 schema 示例，提取要被翻译的控件标签字段 `settings.label`。
    

但是，由于在一个组件配置中可能会有多个 label，为保证键名的唯一性，在控件标签名前增加控件 ID 防止命名重复。通过组合后，得到最终控件标签的键名 `sections.blog.settings.block_id.label`。

##### 控件标签描述在多语言文件中的完整示例{#coVvj}

```json
// i18n/en.json

{
  "sections": {                        // 一级目录名称
    "blog": {                          // 组件文件名
      "settings": {
        "blog_id": {                   // 控件 ID
          "label": "Blogs List New"    // 控件标签描述
        }
      }
    }
  }
}
```

### 应用多语言配置{#iOCTd}

在组件文件中，把 `schema` 里对应的文案替换成唯一键名即可。

> **注意**
>
> 键名前面需添加 `t:` 前缀标识，用于告诉主题编辑器，这是一个多语言 key。

```json
<!-- sections/blog/blog.html -->

{{#schema}}
{
  "name": "t:sections.blog.name",                        // 替换后的键名
  "settings": [
    {
      "type": "blog",                                    // 控件类型
      "id": "blog_id",
      "label": "t:sections.blog.settings.blog_id.label"	 // 替换后的键名
    }
  ]
}
{{/schema}}
```