prod.keys与title.keys有何区别？

Question

在多语言国际化（i18n）项目中，`prod.keys` 与 `title.keys` 文件常被用于存储键值对翻译，但二者用途存在本质区别。`prod.keys` 通常用于生产环境，包含经过审核、完整且稳定的翻译键，直接供应用加载使用；而 `title.keys` 可能是特定模块（如页面标题）的局部键文件，仅涵盖标题类文本，作用范围有限。常见问题是：开发人员误将 `title.keys` 当作全量翻译源部署到生产环境，导致其他文案缺失。此外，键名冲突或重复也易引发覆盖问题。如何正确区分和管理这两类 `.keys` 文件，确保翻译资源准确加载？这是实际部署中需重点关注的技术难点。

Answer 1

1. 多语言国际化中 .keys 文件的基本概念与作用

在多语言国际化（i18n）项目中，.keys 文件通常用于存储键值对形式的翻译资源。这些文件以纯文本或结构化格式（如 JSON、Properties）存在，便于不同语言环境下的动态加载。其中，prod.keys 和 title.keys 是常见的命名约定，但其用途有本质区别。

• prod.keys：代表生产环境使用的全量翻译资源文件，包含所有模块、页面、组件的完整翻译键集合，经过审核、测试和版本控制，确保稳定性和一致性。
• title.keys：通常是局部功能模块专用的翻译文件，例如仅用于页面标题、导航栏标题等 UI 元素，作用范围受限，不覆盖全部文案。

若将 title.keys 错误地作为主翻译源部署到生产环境，会导致大量非标题类文本缺失，影响用户体验。

2. 常见问题分析：误用与冲突场景

在实际开发过程中，以下几类问题是高频出现的技术隐患：

1. 开发人员混淆文件职责，将 title.keys 当作主翻译文件打包发布。
2. 多个模块各自维护独立的 *.keys 文件，在合并时未进行去重处理，导致键名重复。
3. 相同键名存在于 prod.keys 与 title.keys 中，加载顺序不确定引发覆盖问题。
4. 缺乏统一命名规范，如使用 page.title.home 与 home.page.title 表达同一语义，增加维护成本。
5. 自动化构建流程未校验翻译完整性，遗漏关键语言包。

问题类型	典型表现	影响层级
文件误用	仅加载 title.keys 至生产环境	全局文案缺失
键冲突	prod.keys 与 title.keys 含相同 key	翻译错乱或覆盖
结构混乱	无目录划分，文件散落各处	难以维护与定位
审核缺失	未经 QA 的 keys 被合入 prod	语义偏差或语法错误

3. 技术实现路径：从设计到部署的全流程管理

为解决上述问题，需建立系统化的 i18n 资源管理体系。以下是推荐的技术实施步骤：

# 示例：构建脚本中合并并校验 keys 文件
merge-i18n-keys() {
  cat modules/*/title.keys > temp/merged-titles.tmp
  cat base/*.keys >> temp/merged-base.tmp
  sort temp/merged-titles.tmp temp/merged-base.tmp | uniq > dist/prod.keys
  validate-keys-completeness dist/prod.keys en,zh,ja,fr
}

通过自动化脚本确保所有翻译键被正确聚合，并执行去重与完整性验证。

4. 架构设计建议与最佳实践

为了清晰区分 prod.keys 与 title.keys 的职责边界，建议采用分层架构模式：

• 基础层：存放通用词汇、按钮、提示语等全局翻译（如 common.keys）。
• 模块层：按功能拆分，如 user.keys、order.keys、title.keys 等。
• 环境层：通过构建流程生成 prod.keys、staging.keys 等环境专属文件。

graph TD A[源码中的i18n调用] --> B{加载器识别语言环境} B --> C[读取模块化.keys文件] C --> D[合并至内存词典] D --> E[运行时根据key返回翻译] F[构建阶段] --> G[静态扫描提取keys] G --> H[生成prod.keys] H --> I[部署至CDN或服务端]

5. 工具链支持与持续集成集成

现代前端工程化体系可借助工具链提升 i18n 管理效率：

• i18next-parser：自动从代码中提取翻译键，避免手动维护遗漏。
• Webpack + i18n-plugin：在构建时合并、压缩、校验 keys 文件。
• CI/CD 流水线：加入“翻译完整性检查”步骤，阻止不完整包上线。

例如，在 GitHub Actions 中添加如下任务：

- name: Validate i18n Keys
  run: |
    node scripts/check-keys.js --required-languages=en,zh,es
    if [ $? -ne 0 ]; then exit 1; fi