Storefront 本地化文件

店面本地化文件是带有 .json 扩展名的 JSON 文件。它们保存了主题在店面中显示内容所需的翻译字符串。商家可以通过 Shopify Language Editor 来访问这些翻译内容。

注意

Shopify 通过 Shopify Language Editor 提供了 结账和系统消息的翻译。不过，这些数据是由 Shopify 存储在店面本地化文件之外的。

主题的布局、模板、代码片段和 Liquid 资源 不使用硬编码的字符串，而是可以通过 Liquid 的 translation filter（t 过滤器）引用这些翻译。这会从本地化文件中返回当前 启用语言 的翻译字符串。

使用 t 过滤器时，你可以进行 插值、复数处理，以及 本地化任何日期和时间。

位置

店面本地化文件位于主题的 locales 目录中：

  1. └── theme
  2.     ...
  3.     ├── config
  4.     └── locales
  5.       ├── en.default.json
  6.       ...

架构

店面本地化文件需要遵循特定的 命名结构。它们还遵循一个基本的组织结构：

  • Category：翻译的顶层分类。
  • Group：分类下的第二层分组。
  • Description：第三层，表示具体的翻译内容。
  1. {
  2.   "my_category": {
  3.     "my_group": {
  4.       "my_description": "translation text",
  5.       ...
  6.     },
  7.     ...
  8.   },
  9.   ...
  10. }

小贴士

为翻译描述命名时，尽量清晰地表达上下文。例如，blogs.article_comment.submit_button_text 比 blogs.article_comment.submit 更有语境。

命名结构

本地化文件名必须遵循标准的 IETF 语言标签命名法，其中第一个小写字母代码代表语言，第二个大写字母代码代表地区。

例如：

语言 格式
英语 - 英国 en-GB.json
西班牙语 - 西班牙 es-ES.json
法语 - 加拿大 fr-CA.json

如果某个语言不区分地区，你可以只使用 2 个小写字母的语言代码。

例如：

语言 格式
芬兰语 - 所有地区 fi.json

此外，你必须指定一个 默认的本地化文件。

默认本地化文件

你必须指定一个格式为 *.default.json 的默认本地化文件，其中 * 是你选择的语言。该文件包含主题的默认语言翻译。只能有一个默认文件。

大多数主题使用 en.default.json，即设置主题默认语言为英语。

内容

为了确保翻译能够正确映射，并尽可能简化商家的操作，你应该将 key 的结构组织得尽量贴合主题的结构。

例如，前两级结构可能如下：

第一级 第二级
general 404、面包屑导航、搜索（结果页和空白页）、分页
blogs 文章、评论、侧边栏
cart 购物车内容、更新、备注、跳转结账链接
collection 商品集合、集合循环
products 商品、商品循环、相关商品
layout 通用字段标题和标识
customer 账户、订单（列表和详情）、激活账户、地址、登录、密码、注册
contact 联系表单、表单错误
home_page 空白页、特色内容、帮助
gift_cards 标题、使用条款

注意

如果你在代码片段中使用翻译，那么应该将它们归类到与该片段角色最相关的分类中。例如，如果你有一个 related-products.liquid 片段，那么相关翻译就应放在 products 分类下。

使用方式

在处理店面本地化文件时，请注意以下内容：

引用店面翻译

要引用当前主题 启用语言 的本地化翻译，可以使用翻译 key 和 Liquid 的 translation filter（t 过滤器）。

例如，假设你有英文、法文和西班牙文的本地化文件，那么可以在每个文件中这样写：

/locales/en.default.json (英文)

  1. {
  2.   "blog": {
  3.     "comment": {
  4.       "email": "Your email"
  5.     }
  6.   }
  7. }

/locales/fr.json (法文)

  1. {
  2.   "blog": {
  3.     "comment": {
  4.       "email": "Votre adresse courriel"
  5.     }
  6.   }
  7. }

引用方式如下：

  1. <span>{{ "blog.comment.email" | t }}</span>

小贴士

在 Liquid 中引用翻译 key 时，必须用单引号包裹（'）。

输出结果会根据当前本地化文件设置而变化：

  1. // 英文
  2. <span>Your email</span>
  4. // 法文
  5. <span>Votre adresse courriel</span>
  7. // 西班牙文
  8. <span>Su correo electrónico</span>

插值

翻译字符串支持插值，也就是说可以在字符串中包含变量，并在被引用时动态填充。例如，本地化文件中这样写：

  1. {
  2.   "layout": {
  3.     "header": {
  4.       "hello_user": "Hello {{ name }}!"
  5.     }
  6.   }
  7. }

然后在主题中引用该翻译，并为 name 变量赋值：

  1. {% if customer %}
  2.   <h1>{{ 'layout.header.hello_user' | t: name: customer.first_name }}</h1>
  3. {% endif %}

如果顾客名为 “Jane”，最终输出：

  1. <h1>Hello Jane!</h1>

传递多个参数

使用插值时，可以通过逗号（,）传递多个参数。例如，若想同时展示顾客的名字和姓氏，则可按如下方式调整：

  1. {
  2.   "layout": {
  3.     "header": {
  4.       "hello_user": "Hello {{ first_name }} {{ last_name }}!"
  5.     }
  6.   }
  7. }
  1. {% if customer %}
  2.   <h1>
  3.     {{ 'layout.header.hello_user' | t: first_name: customer.first_name, last_name: customer.last_name }}
  4.   </h1>
  5. {% endif %}

顾客名为 “Jane Doe” 时，输出：

  1. <h1>Hello Jane Doe!</h1>

防止翻译内容被转义

翻译内容默认会被转义，即所有 HTML 字符会被转换为实体格式。

你可以在翻译 key 的描述层级加上 _html 后缀，以阻止内容被转义。例如，以下翻译中的 <strong> 标签会被转义为普通文本：

  1. {
  2.   "layout": {
  3.     "header": {
  4.       "announcement_bar_text": "Spend $50 and get <strong>FREE</strong> shipping",
  5.     }
  6.   }
  7. }

加上 _html 后缀后，输出内容将保持 HTML 格式：

  1. {
  2.   "layout": {
  3.     "header": {
  4.       "announcement_bar_text_html": "Spend $50 and get <strong>FREE</strong> shipping",
  5.     }
  6.   }
  7. }

小贴士

_html 后缀适用于翻译内容中含有 HTML 字符，或在 <script> 标签或 js.liquid 资源文件中使用翻译的场景。

复数处理

你可以通过给 translation filter（t 过滤器）传入 count 属性，实现本地化的复数处理。

支持以下由 Unicode Consortium 的 CLDR 定义的复数 key：

  • few
  • many
  • one
  • other
  • two
  • zero

例如：

  1. {
  2.   "customers": {
  3.     "orders": {
  4.       "order_count": {
  5.         "one": "You've made {{ count }} order with us",
  6.         "other": "You've made {{ count }} orders with us"
  7.       }
  8.     }
  9.   }
  10. }
  1. {% if customer %}
  2.   <h1>{{ 'customers.order.order_count' | t: count: customer.orders_count }}</h1>
  3. {% endif %}

输出：

  1. // count == 1
  2. <h1>You've made 1 order with us</h1>
  4. // count == 12
  5. <h1>You've made 12 orders with us</h1>

想了解不同语言的复数规则，请参考 Unicode 语言复数规则。

日期和时间本地化

可以通过 date 和 time_tag Liquid 过滤器渲染日期和时间。它们具有默认的格式选项，会根据商店的 当前语言 显示对应格式：

例如：

  1. {{ order.created_at | date: format: 'abbreviated_date' }}

输出：

  1. Dec 31, 2018

自定义格式

你可以在本地化文件中通过添加 date_formats 对象来自定义格式：

  1. {
  2.   "date_formats": {
  3.     "month_and_year": "%B %Y"
  4.   }
  5. }

这些格式必须使用 Ruby 的 strftime 方法的参数。你可以查阅 Ruby 文档，或者使用 strfti.me 网站。

注意

必须确保所有本地化文件中都包含自定义格式。如果当前语言的本地化文件缺少该格式，会导致 Liquid 报错。

使用上面的格式：

  1. {{ order.created_at | date: format: 'month_and_year' }}

输出：

  1. December 2018

结账与系统消息

Shopify 提供以下语言的结账和系统消息：

  • 保加利亚语（保加利亚）
  • 中文（简体）
  • 中文（繁体）
  • 克罗地亚语（克罗地亚）
  • 捷克语
  • 丹麦语
  • 荷兰语
  • 英语
  • 芬兰语
  • 法语
  • 德语
  • 希腊语
  • 印地语
  • 匈牙利语
  • 印度尼西亚语
  • 意大利语
  • 日语
  • 韩语
  • 立陶宛语（立陶宛）
  • 马来语
  • 挪威语（Bokmål）
  • 波兰语
  • 葡萄牙语（巴西）
  • 葡萄牙语（葡萄牙）
  • 罗马尼亚语
  • 俄语
  • 斯洛伐克语
  • 斯洛文尼亚语
  • 西班牙语
  • 瑞典语
  • 泰语
  • 土耳其语

注意

如果你使用的语言不在上述列表中，则需要通过 Shopify Language Editor 手动添加结账和系统消息的翻译。