Shopify 主题翻译：locales、t 过滤器与缺失键排查
做 Shopify 主题翻译时，我会先确认改的是哪一层：顾客看到的按钮和提示文字，通常放在 storefront locale 文件中，由 Liquid 的 t 过滤器读取；主题编辑器里的 Section 名称和设置标签，则属于 schema locale。两者文件名很像，写错位置就可能出现“翻译明明加了，检查还是提示缺键”的情况。
这篇用一个独立的最小主题，实际复现默认语言缺键、第二语言漏键和补齐后通过检查的过程。实测工具为 Shopify CLI 4.8.0，日期为 2026 年 9 月 12 日。这里验证的是本地 Theme Check，不是店铺前台语言切换；没有上传或修改在线主题。
Shopify 主题翻译先分清两类 locales 文件
locales/en.default.json 是默认英语的店面语言文件，locales/fr.json 是法语的对应文件。这里保存的是主题使用的文本键和值，例如发货提示。locales/en.default.schema.json 则供主题编辑器使用，例如 Section 在添加面板里的名称。同一种类型只应有一个默认文件，不要为了增加语言再建一个 fr.default.json。
t 是 translate 的别名，作用是按键查找翻译，不会把你写进去的英语自动翻成法语。本文只讨论主题的全局语言文件；Section 自身也可以定义局部翻译，但不要把那个机制与编辑器标签的 .schema.json 混为一谈。对目录还不熟，可以先看Dawn 主题目录结构，再回到这里处理语言文件。
准备一个不会影响在线商店的检查目录
本机需要已有可用的 Shopify CLI。在新的 translation-lab 文件夹里准备下面这些文件，不要直接覆盖正在使用的 Dawn 文件。这个目录只用于静态检查，不需要执行 theme push，也不需要为本次检查登录店铺。CLI 的安装与常规检测用法可以参照Theme Check 使用教程。
translation-lab/
├── .theme-check.yml
├── layout/theme.liquid
├── templates/index.json
├── sections/translation-lab.liquid
└── locales/
├── en.default.json
├── fr.json
└── en.default.schema.jsonlayout/theme.liquid 保留最小主题布局必需的输出位置：
<!doctype html>
<html lang="{{ request.locale.iso_code }}">
<head>
<meta charset="utf-8">
<title>{{ page_title | escape }}</title>
{{ content_for_header }}
</head>
<body>{{ content_for_layout }}</body>
</html>templates/index.json 只引用这次的测试 Section：
{
"sections": {
"main": { "type": "translation-lab", "settings": {} }
},
"order": ["main"]
}sections/translation-lab.liquid 放一条带参数的提示。days: 3 只是演示插值，并不代表店铺真的三天发货，不能照抄成实际履约承诺。
<p>{{ 'custom.delivery.message' | t: days: 3 }}</p>
{% schema %}
{
"name": "t:sections.translation_lab.name",
"settings": [],
"presets": [{ "name": "t:sections.translation_lab.name" }]
}
{% endschema %}同样出现了 t，但两种写法不能互换。段落中的 | t: days: 3 是 Liquid 过滤器；schema 中的 t:sections.translation_lab.name 是编辑器名称的翻译引用。为后者建立 locales/en.default.schema.json：
{
"sections": {
"translation_lab": { "name": "Translation lab" }
}
}最后，在 .theme-check.yml 继承推荐检查，并明确启用不同语言之间的键一致性检查。这次没有手动改变检查的 severity：
extends: theme-check:recommended
MatchingTranslations:
enabled: true第一轮：复现默认语言缺键
先让 en.default.json 只有一个无关的关闭按钮翻译。fr.json 使用相同结构，把 Close 换成 Fermer。这样两份文件的键一致，但都没有 Section 正在请求的 custom.delivery.message。
{
"general": { "close": "Close" }
}在 translation-lab 的上一级目录运行以下命令。若你的目录名不同，调整 --path，不要误指向日常开发项目。
shopify --version
shopify theme check --path translation-lab --output json --fail-level error本次返回 1 个 error、0 个 warning，退出码为 1。TranslationKeyExists 指向 sections/translation-lab.liquid，说明请求的键在 locales/en.default.json 没有对应条目。这个结果只说明默认语言查找有问题，不能据此判断法语翻译是否正确。
第二轮：英语补齐后，继续发现法语漏键
把 en.default.json 改成下面的完整内容，暂时不改 fr.json。键名按 custom → delivery → message 三层组织；{{ days }} 是翻译文本中的占位符，与调用时传入的 days: 3 对应。
{
"general": { "close": "Close" },
"custom": {
"delivery": {
"message": "Dispatches within {{ days }} days."
}
}
}再次运行同一条检查命令，默认语言缺键的报错消失，这次出现 MatchingTranslations：法语文件缺少 custom.delivery.message。本机 CLI 4.8.0 的实际结果仍是 1 个 error、退出码 1。不要只凭某张文档总表的默认级别推断自己的 CI 会不会失败，应以当前版本、配置和命令输出为准。
接着补齐 fr.json。只翻译值，保持键的层级和占位符名称一致；不要把 days 也翻译成另一个变量名。
{
"general": { "close": "Fermer" },
"custom": {
"delivery": {
"message": "Expédition sous {{ days }} jours."
}
}
}第三次运行后，JSON 输出为 []，退出码为 0，即这套配置下未发现问题。下面的图由三次实际输出整理生成，保留了检查名称、错误信息与退出码，点击可查看大图。
检查通过后，还不能直接认定翻译完成
这次 Shopify 主题翻译排查解决的是“键在哪里、有没有漏”的问题。Theme Check 通过，并不证明措辞准确、语气适合商品，也不证明实际店铺已经发布了法语或正确切换语言。示例中的插值写法符合官方文档，但本次没有在 Shopify 运行时验证最终显示文本。
放回真实主题时，只把需要的键合并进既有文件，不能用本文的短 JSON 覆盖整个 Dawn 语言文件。先在副本中修改并检查，再按草稿主题预览流程核对目标语言下的文案、变量值、长文本换行和按钮宽度。商品标题、商家在编辑器里填写的内容，以及语言的发布状态，也不是给 locales 加一个键就会全部处理好。
遇到问题时，我会按这个顺序排查：先看文件属于店面还是编辑器，再核对完整键路径，然后比较各语言文件是否缺键，最后才检查真实页面中的语言状态和显示效果。不要通过关闭检查隐藏缺键；自动修复也不等于自动完成合格翻译。本文实验没有线上恢复步骤，保留这个独立目录即可重复检查；应用到真实项目时，应通过自己的版本记录撤回本次文件改动。
官方资料：Locale files、Storefront locale files、Schema locale files、translate 过滤器、TranslationKeyExists、MatchingTranslations（访问日期：2026-09-12；本地检查：Shopify CLI 4.8.0）。
