主题国际化

摘要

13 主题国际化

2026年8月11日|Shopi8

1 分钟阅读

Shopify Shopify教程

先判断问题出现在哪里

如果你的主题里写死了 <button>Add to Cart</button>，当一个法国商家使用你的主题时，他会绝望地发现这个按钮无法变成法语。

核心逻辑是：代码中绝对不能出现硬编码（Hardcoded）的静态文本。

所有的文本必须被提取为“翻译键（Translation Keys）”，存放在 locales/ 目录下的 JSON 文件中。在前端，通过 Liquid 的 t 过滤器（Translate Filter）动态调用。Shopify 会根据当前用户选择的语言环境，自动去对应的 JSON 文件中寻找翻译并渲染。

实战步骤

步骤 1：建立 `locales/` 目录结构

操作路径：在主题根目录的 locales 文件夹中创建 JSON

创建默认语言文件：en.default.json（英语）。
创建其他语言文件：fr.json（法语）、zh-CN.json（简体中文）。

JSON 结构规范：按页面或组件进行层级嵌套。

// en.default.json
{
  "products": {
    "product": {
      "add_to_cart": "Add to cart",
      "sold_out": "Sold out"
    }
  }
}

步骤 2：在 Liquid 中使用 `t` 过滤器

操作路径：替换所有硬编码的文本

基础调用：
<button>{{ 'products.product.add_to_cart' | t }}</button>
带变量的动态翻译：
JSON 中："cart_count": "You have {{ count }} items in your cart"
Liquid 中：{{ 'cart.general.cart_count' | t: count: cart.item_count }}

步骤 3：翻译 Schema 中的后台配置项

操作路径：在 {% schema %} 中使用 t 标签

不仅前台要翻译，后台给商家看的设置面板也要翻译！

在 Schema 中，不能使用 {{ 'key' | t }}，必须使用 t: 前缀。

"settings": [
  {
    "type": "text",
    "id": "title",
    "label": "t:sections.featured_collection.settings.title.label"
  }
]

步骤 4：实现多货币与多语言切换器 (Localization Form)

操作路径：在 Header 或 Footer 中添加切换表单

使用 Shopify 原生的 {% form 'localization' %}。

{% form 'localization', id: 'FooterLanguageForm' %}
  <select name="locale_code" onchange="this.form.submit()">
    {% for language in localization.available_languages %}
      <option value="{{ language.iso_code }}" {% if language.iso_code == localization.language.iso_code %}selected{% endif %}>
        {{ language.endonym_name }}
      </option>
    {% endfor %}
  </select>
{% endform %}

当用户选择新语言并提交表单时，Shopify 会自动刷新页面并切换到对应的语言环境。

常见误区与处理方法

误区一：在 JavaScript 文件中直接使用 `t` 过滤器

规避方法：这是前端新手最容易犯的错误。你写了一个 theme.js，在里面写了 alert("{{ 'general.success' | t }}");。结果浏览器直接报错，因为 .js 文件不会经过 Shopify 服务器的 Liquid 引擎解析，它只是一堆静态的文本！在外部 JS 文件中，绝对不能写 Liquid 代码。正确的做法是：在 theme.liquid 的 <head> 中，定义一个全局的 JavaScript 对象，将需要的翻译文本注入进去：

<script>
  window.themeStrings = {
    successMessage: {{ 'general.success' | t | json }}
  };
</script>

然后在你的 theme.js 中调用 alert(window.themeStrings.successMessage);。

误区二：JSON 翻译文件缺少键值导致页面大面积报错

规避方法：你在 en.default.json 里加了一个新的翻译键 "new_feature": "New"，但在 fr.json 里忘记加了。当法语用户访问时，页面上原本该显示文字的地方，会直接暴露出一长串丑陋的错误代码：Translation missing: fr.products.new_feature。这会让网站显得极其不专业。在发布主题前，必须使用 Shopify Theme Check 工具扫描代码。它会自动对比所有 locales/ 下的 JSON 文件，揪出所有缺失的翻译键。

误区三：多货币切换后，Ajax 购物车里的价格没有更新

规避方法：用户在页脚把货币从 USD 切换到了 EUR。页面刷新了，产品页的价格变成了欧元。但当用户点击“加入购物车”弹出 Ajax 抽屉时，里面的价格居然还是美元！这是因为你的 Ajax 购物车是通过 JS 渲染的，而 JS 里缓存了旧的货币格式。在处理多货币时，前端 JS 必须监听货币切换事件，或者在每次 Ajax 请求购物车数据时，强制要求 Shopify 返回带 HTML 货币符号的格式化价格（Formatted Price），而不是自己用 JS 去拼接数字。

FAQ