OpenWork 多语言翻译与 i18n 国际化指南:README 本地化与 App UI 翻译实践

原创2026-09-11 23:44:032,344 阅读
文章标签:人工智能AI Agent桌面应用前端后端MCP ClientsMCP 服务本地部署交互助手GUI 自动化浏览器控制企业应用

OpenWork 多语言翻译与 i18n 国际化指南:README 本地化与 App UI 翻译实践

OpenWork 是一个面向 AI 智能体工作流编排的开源桌面应用(基于 opencode 构建),为了让全球开发者与终端用户都能以母语使用与阅读项目,仓库维护了两套独立的翻译体系:面向仓库文档的 translated_readmes/ 多语言 README,以及面向应用界面的 apps/app/src/i18n/ 运行时国际化(i18n)。本文以仓库根目录的 TRANSLATIONS.md 为核心,结合 i18n 源码与审计脚本,完整讲解这两套体系的目录结构、翻译文件格式、新增语言的完整操作步骤、运行时回退与复数机制,以及用于保障翻译质量的自动化审计工具,读完后你可以立即为 OpenWork 贡献一门新语言。

一、OpenWork 的两层翻译体系:文档级与界面级

TRANSLATIONS.md 明确指出 OpenWork 正在积极招募贡献者将项目翻译为各自然语言,翻译工作分为两个互不干扰的层面:

  1. README 翻译(文档层):翻译仓库根目录的 README.md,产物存放在 translated_readmes/ 目录,属于纯文档工作,不涉及任何运行时代码。
  2. App UI 翻译(i18n 层):翻译应用界面字符串,源码位于 apps/app/src/i18n/,产物是 TypeScript 语言包,直接参与应用运行时渲染。

两层体系相互独立:文档翻译只改动 translated_readmes/ 索引与根 README.md 的语言列表;UI 翻译则只触碰 apps/app/src/i18n/ 下的语言文件与注册表。二者共同构成 OpenWork 的多语言完整方案。

二、README 翻译:新增一门文档语言

2.1 目录结构与现状

按 TRANSLATIONS.md 的说明,翻译后的 README 变体统一存放在仓库根目录的 translated_readmes/ 中。当前仓库索引 translated_readmes/README.md 列出了 4 种可用语言:

以简体中文版 translated_readmes/README_ZH.md 为例,其文件头部维护了一组语言切换链接(<a href="https://link.gitcode.com/i/52d322b89a2ce9bc96a6ae849a21b8c8" target="_blank">English</a> | 简体中文 | <a href="https://link.gitcode.com/i/f0491c53db927ba42decc5e090945cc9" target="_blank">其他语言</a>),用于让读者在多个语言版本之间跳转,这与根目录语言索引相互配合。

2.2 新增一门 README 语言的 5 个步骤

TRANSLATIONS.md 给出了完整的操作流程,每一步都对应仓库中的实际文件:

  1. 复制模板:将根目录 README.md 复制为 translated_readmes/README_<LANG>.md(例如 README_KO.md、README_DE.md),命名遵循 README_ + 语言代码的约定。
  2. 翻译内容:逐段翻译 README 的全部正文,同时保留文档内部的相对链接结构——链接指向仓库内其他文档时应保持相对关系,指向 translated_readmes/ 内其他语言版本时可参照现有 README_ZH.md 的写法(如 <a href="https://link.gitcode.com/i/52d322b89a2ce9bc96a6ae849a21b8c8" target="_blank">English</a>)。
  3. 更新语言索引:在 translated_readmes/README.md 的 Available 行中加入新语言链接,例如在现有四种语言之后追加 한국어。
  4. 更新根 README 支持语言列表:按 TRANSLATIONS.md 的约定,在根目录 README.md 底部的 supported languages 列表中加入新语言名称。这一步保证读者从主 README 能发现新的语言版本。
  5. 提交 PR:将上述改动以 Pull Request 形式提交。

提示:从当前仓库结构可以推断,新增 README 语言时仅需新增一个文件并修改两处索引(translated_readmes/README.md 与根 README.md),不会影响应用运行时代码,风险面极小。

三、App UI 翻译:i18n 目录与语言注册

3.1 目录结构

UI 翻译的源码位于 apps/app/src/i18n/,实际结构如下:

apps/app/src/i18n/
├── index.ts          # i18n 核心:语言注册表、t() 翻译函数、locale 管理
└── locales/
    ├── index.ts      # 语言文件统一 re-export
    ├── en.ts         # 英文(唯一事实源,source of truth)
    ├── ja.ts         # 日文
    ├── zh.ts         # 简体中文
    ├── vi.ts         # 越南文
    ├── pt-BR.ts      # 巴西葡萄牙文
    ├── ru.ts         # 俄文
    ├── th.ts         # 泰文
    ├── fr.ts         # 法文
    ├── ca.ts         # 加泰罗尼亚文
    └── es.ts         # 西班牙文

注意:TRANSLATIONS.md 中列出的可用 locale 为 6 种(en、ja、zh、vi、pt-BR、ru),而当前仓库实际已注册 10 种——额外包含 th、fr、ca、es。这说明文档是项目演进过程中的快照,新增语言的速度快于文档更新;以实际源码 apps/app/src/i18n/index.ts 为准,当前支持的语言集合为:en、ja、zh、vi、pt-BR、th、fr、ca、es、ru。

3.2 语言注册表:单一事实源

apps/app/src/i18n/index.ts 是整个 i18n 体系的枢纽,集中定义了 4 个相互关联的注册结构:

export type Language = "en" | "ja" | "zh" | "vi" | "pt-BR" | "th" | "fr" | "ca" | "es" | "ru";

export const LANGUAGES: Language[] = ["en", "ja", "zh", "vi", "pt-BR", "th", "fr", "ca", "es", "ru"];

export const LANGUAGE_OPTIONS = [
  { value: "en", label: "English", nativeName: "English" },
  { value: "ja", label: "Japanese", nativeName: "日本語" },
  { value: "zh", label: "Chinese (Simplified)", nativeName: "简体中文" },
  { value: "vi", label: "Vietnamese", nativeName: "Tiếng Việt" },
  { value: "pt-BR", label: "Portuguese (BR)", nativeName: "Português (BR)" },
  { value: "th", label: "Thai", nativeName: "ไทย" },
  { value: "fr", label: "French", nativeName: "Français" },
  { value: "ca", label: "Catalan", nativeName: "Català" },
  { value: "es", label: "Spanish", nativeName: "Español" },
  { value: "ru", label: "Russian", nativeName: "Русский" },
] as const;

const TRANSLATIONS: Record<Language, Record<string, string>> = { en, ja, zh, vi, "pt-BR": ptBR, th, fr, ca, es, ru };
  • Language 联合类型约束所有语言代码;
  • LANGUAGES 数组是所有受支持语言的单一事实源;
  • LANGUAGE_OPTIONS 为语言选择器 UI 提供 value/label/nativeName(母语名称)三元组;
  • TRANSLATIONS 将语言代码映射到具体语言包对象。

配套的还有 isLanguage() 类型守卫(用于替代 value === "en" || value === "zh" 这类冗长判断)以及 locales/index.ts 中对 10 个语言文件的统一 re-export。

3.3 语言包文件格式

每个 locale 是一个以 export default { ... } as const 导出的扁平 key-value 对象,key 采用点号分层命名(如 app.error_auth_failed、blueprint.welcome_title)。以简体中文包 apps/app/src/i18n/locales/zh.ts 为例(全文件约 1173 行):

export default {
  "app.compact_command_desc": "压缩此会话以减少上下文大小。",
  "app.error_auth_failed": "认证失败",
  "blueprint.welcome_message": "你好,欢迎使用OpenWork!\n\n大家用OpenWork在电脑上编写CSV文件、自动化浏览器任务,以及将联系人同步到Notion。\n\n但唯一的限制是你的想象力。\n\n你想做什么?",
  "blueprint.welcome_title": "欢迎使用OpenWork",
  // ... 其余数百个 key
} as const;

en.ts 是唯一事实源(source of truth):所有其他语言包都以它为基准对齐 key 集合,新增 UI 文案必须先进入 en.ts,再扩散到各语言包。

值得注意的细节是,zh.ts 文件头部以注释形式明确了术语约定(产品名保留英文、Skills 标题与正文的不同译法、MCP 协议名不翻译等),翻译者在接手语言包前应通读该注释以保持全仓库术语一致。

四、运行时机制:t() 翻译函数、回退链与复数处理

i18n 不只是静态映射,apps/app/src/i18n/index.ts 中实现了完整的运行时翻译引擎,理解它有助于翻译者判断某个 key 应该提供哪些变体。

4.1 locale 状态与持久化

  • 应用启动时调用 initLocale()(入口见 apps/app/src/index.react.tsx):从 localStorage 的 openwork.language 键读取已保存偏好,通过 isLanguage() 校验后生效,并将 document.documentElement 的 lang 属性同步为当前语言代码(影响屏幕阅读器与浏览器语言提示);无有效存储值时回退到 en。
  • 用户切换语言时调用 setLocale(newLocale):校验非法值回退到 en,写入 localStorage 持久化,同时更新 <html lang> 属性。
  • 组件内取当前语言用 currentLocale(),翻译文案统一调用 t()。

4.2 t() 的查表与回退链

t(key, params?) 的核心查表逻辑 lookupEntry 实现了 目标语言 → 英文 → key 本身 的三级回退:

const lookupEntry = (loc: Language, candidateKey: string): string | null => {
  if (TRANSLATIONS[loc]?.[candidateKey]) return TRANSLATIONS[loc][candidateKey];
  if (loc !== "en" && TRANSLATIONS.en?.[candidateKey]) return TRANSLATIONS.en[candidateKey];
  return null;
};

这意味着:某个语言包即使暂时缺失某个 key,界面也不会白屏或报错,而是自动显示英文原文;只有英文也缺失时才会原样输出 key 字符串。翻译者可以利用这一特性分多次、分模块地渐进补齐翻译,不必一次性完成全部 1000+ 个 key。

4.3 复数规则:Intl.PluralRules 驱动的 key 变体

与许多 i18n 方案不同,OpenWork 在运行时通过 Intl.PluralRules 按语言选取复数形态的 key 变体:

const resolvePluralKey = (loc: Language, key: string, count: number): string => {
  const candidates: string[] = [];
  if (count === 0) candidates.push(`${key}_zero`);
  candidates.push(`${key}_${pluralRule(loc, count)}`, `${key}_other`, key);
  for (const candidate of candidates) {
    if (lookupEntry(loc, candidate) !== null) return candidate;
  }
  return key;
};

候选顺序为:${key}_zero(仅当 count === 0)→ ${key}_one / ${key}_other(依 Intl.PluralRules 判定)→ ${key}_other → 裸 key。例如英文包中的 _one/_other 变体(如 foo_one、foo_other)就是为此准备的。

同时 apps/app/src/i18n/index.ts 中有一个对翻译者非常关键的常量:

const PLURAL_SUFFIX_EMPTY_LANGUAGES = new Set<Language>(["ja", "zh", "th"]);

日语、简体中文、泰语在语法上没有可见的复数标记(名词本身不因数量变化词形),因此这几种语言的 pluralSuffix() 返回空字符串,Intl.PluralRules 对它们的判定为 other,语言包只需提供裸 key 即可命中回退链的最后一环,无需维护 _one/_other 变体。而俄语等拥有复杂复数体系的语言(one/few/many 等)则需要按 Intl.PluralRules 的结果补齐对应变体。

4.4 参数插值

翻译字符串支持 {key} 形式占位符,t() 在查表后对参数做替换:

for (const [k, v] of Object.entries(params)) {
  if (k === "lng") continue;
  out = out.replace(`{${k}}`, String(v));
}

翻译者必须在语言包中保留与英文一致的占位符名称与数量,否则会出现运行时替换失败或漏替换。占位符一致性正是下文审计工具的检查项之一。

五、实操:为 App UI 新增一门语言

结合第三节的注册表结构与第四节的回退机制,新增语言(以 de 为例)需要以下操作:

  1. 创建语言包:复制 apps/app/src/i18n/locales/en.ts 为 apps/app/src/i18n/locales/de.ts,逐条翻译 value,保留全部 key 与占位符。可在文件头部像 zh.ts 那样添加术语约定注释。
  2. 注册语言文件导出:在 apps/app/src/i18n/locales/index.ts 中新增 export { default as de } from "./de";。
  3. 注册到核心索引:在 apps/app/src/i18n/index.ts 中完成四处同步修改:
    • Language 联合类型中加入 "de";
    • LANGUAGES 数组中追加 "de";
    • LANGUAGE_OPTIONS 中追加 { value: "de", label: "German", nativeName: "Deutsch" }(供语言选择器显示,nativeName 必须是该语言的母语自称);
    • TRANSLATIONS 映射中加入 de 并 import 对应语言包。
  4. 复数规则确认:若目标语言属于无可见复数标记的语言(如日语、简体中文、泰语),需确认 PLURAL_SUFFIX_EMPTY_LANGUAGES 集合是否需要更新;否则按 Intl.PluralRules 补齐 _one/_other 等变体。
  5. 运行审计脚本(见下一节)验证 key 完整性、占位符一致性与复数形态正确性,然后提交 PR。

六、质量保障:i18n 审计脚本

仓库提供了专门的审计工具 scripts/i18n-audit.mjs,用于在提交翻译前系统性检查语言包质量。脚本以 en.ts 为基准,支持多种模式(node scripts/i18n-audit.mjs <模式>):

模式 功能
(无参数 / --all) 默认全量审计(不含 --hardcoded)
--ci 同全量审计,但缺失非英文 key 时不视为失败(适合 CI 渐进接入)
--missing 列出英文包有但某语言包缺失的 key,按前缀分组统计
--orphan 列出语言包有但英文包没有的孤立 key(冗余翻译)
--duplicates 检查任意语言包内的重复 key
--unused 检查英文包中全仓库源码从未引用的 key
--dangling 检查源码中 t() 调用指向了英文包中不存在的 key
--aliases 检查是否使用 translate/tr 等别名替代规范的 t() 调用
--placeholders 校验语言包内 {占位符} 与英文的一致性
--plurals 校验每个语言包要么提供裸 key,要么提供其所需的全部 CLDR 复数形态
--hardcoded 扫描源码中硬编码的英文字符串(该模式默认不包含在全量审计中)
--prune (破坏性)从所有语言包移除未使用的 key
--sort (破坏性)对所有语言包的 key 按字母序排序

其中两个模式对翻译者尤其重要:

  • --missing:翻译未完成时直接运行,即可得到“还有多少个 key 待翻译、缺在哪些模块前缀下”的精确清单。由于运行时存在英文回退,未翻译的 key 不会破坏应用,但会以英文呈现,因此该命令是衡量翻译进度的核心指标。
  • --plurals 与 --placeholders:分别把守复数形态与占位符两条最容易出错的翻译规则。--plurals 的判定逻辑与运行时一致——脚本会剥离 _zero/_one/_two/_few/_many/_other 后缀,允许日语、中文、泰语只提供裸 key,而其他语言必须按 Intl.PluralRules 补齐变体,确保“静态检查通过 = 运行时复数渲染正确”。

此外,脚本的孤儿 key 判定同样兼容复数体系(英文包没有 _one 变体但有裸 key 时,语言包提供 _one 不算孤立),避免了对亚洲语言复数写法的误报。全量审计默认会跳过 locales 目录自身,防止翻译 key 与源码引用“自我匹配”造成假阳性。

七、贡献流程与翻译约定

按照 TRANSLATIONS.md 的指引与仓库约定,贡献翻译的推荐路径为:

  1. README 翻译:按第二节 5 步流程操作,改动范围仅限 translated_readmes/ 与根 README.md;
  2. UI 翻译:按第五节流程新建或完善语言包,并用 scripts/i18n-audit.mjs 的 --missing、--plurals、--placeholders 模式自检;
  3. 不确定时先开 issue:TRANSLATIONS.md 明确建议,如果不确定从何入手,可以开一个 issue 并注明想贡献的语言,维护者会给出更具体的指引;
  4. 提交 PR:文档翻译与 UI 翻译均以 Pull Request 形式合入。

翻译风格方面,apps/app/src/i18n/locales/zh.ts 头部注释提供了可复用的经验模板:产品专有名词(OpenCode、OpenWork 等)保留英文;协议名(MCP)保留英文不意译;核心交互术语(命令、插件、会话、应用)统一译法。建议新语言包在文件头部同样以注释固化自己的术语约定,方便后续贡献者保持一致。

八、结语

OpenWork 的双层翻译体系设计得清晰且务实:文档层通过 translated_readmes/ 索引 + 根 README 语言列表实现零运行时成本的本地化;UI 层则依托 apps/app/src/i18n/index.ts 的注册表、t() 三级回退链与 Intl.PluralRules 复数机制,配合 scripts/i18n-audit.mjs 的自动化校验,让新增语言成为一项“改文件 + 跑审计”的低风险工作。无论你想翻译 README 还是应用界面,从复制 en.ts 或 README.md 开始,按注册、补齐、审计三步走,即可为 OpenWork 贡献一门新的母语版本。

登录后查看全文
openwork