i18n

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

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

目录结构

标准目录

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

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

支持的文件类型

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

文件类型	作用域	服务对象	示例路径
*.json	主题	客户端	i18n/en.json
*.schema.json	控件（可视化编辑器）	商家端	i18n/en.schema.json

文件命名规范

多语言文件的命名遵循 IETF BCP 47 标准，以下为中文简体和英文语种文件的命名示例：

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

主题多语言文件

结构规范

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

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

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

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

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

结构示例

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

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

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

引用方式

在组件代码中，你可以通过 t filter 实现对上述 search.results_count 键名的引用，以下是在组件 sections/main-search/main-search.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}}

变量插值

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

模版调用

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

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

渲染结果

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

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

控件多语言文件

如下是主题博客组件 schema 内容示例，展示关联的控件多语言文件的结构规范与配置。其中 name（组件名）和 label（控件标签描述）都是需要支持多语言的：

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

文件结构示例

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

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

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

多语言键名命名规范

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

组件名示例

在如上多语言 JSON 文件示例中，组件名键名 sections.blog.name 的命名方式如下：

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

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

组件名在多语言文件中的完整示例

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

控件标签描述示例

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

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

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

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

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

应用多语言配置

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

注意：键名前面需添加 t: 前缀标识，用于告诉可视化编辑器，这是一个多语言 key。

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