OpenWork 多语言翻译与 i18n 国际化指南:README 本地化与 App UI 翻译实践
OpenWork 多语言翻译与 i18n 国际化指南:README 本地化与 App UI 翻译实践
OpenWork 是一个面向 AI 智能体工作流编排的开源桌面应用(基于 opencode 构建),为了让全球开发者与终端用户都能以母语使用与阅读项目,仓库维护了两套独立的翻译体系:面向仓库文档的 translated_readmes/ 多语言 README,以及面向应用界面的 apps/app/src/i18n/ 运行时国际化(i18n)。本文以仓库根目录的 TRANSLATIONS.md 为核心,结合 i18n 源码与审计脚本,完整讲解这两套体系的目录结构、翻译文件格式、新增语言的完整操作步骤、运行时回退与复数机制,以及用于保障翻译质量的自动化审计工具,读完后你可以立即为 OpenWork 贡献一门新语言。
一、OpenWork 的两层翻译体系:文档级与界面级
TRANSLATIONS.md 明确指出 OpenWork 正在积极招募贡献者将项目翻译为各自然语言,翻译工作分为两个互不干扰的层面:
- README 翻译(文档层):翻译仓库根目录的
README.md,产物存放在translated_readmes/目录,属于纯文档工作,不涉及任何运行时代码。 - 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 种可用语言:
- English(根 README.md)
- 简体中文(README_ZH.md)
- 繁體中文(README_ZH_hk.md)
- 日本語(README_JA.md)
以简体中文版 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 给出了完整的操作流程,每一步都对应仓库中的实际文件:
- 复制模板:将根目录
README.md复制为translated_readmes/README_<LANG>.md(例如README_KO.md、README_DE.md),命名遵循README_+ 语言代码的约定。 - 翻译内容:逐段翻译 README 的全部正文,同时保留文档内部的相对链接结构——链接指向仓库内其他文档时应保持相对关系,指向
translated_readmes/内其他语言版本时可参照现有README_ZH.md的写法(如<a href="https://link.gitcode.com/i/52d322b89a2ce9bc96a6ae849a21b8c8" target="_blank">English</a>)。 - 更新语言索引:在 translated_readmes/README.md 的 Available 行中加入新语言链接,例如在现有四种语言之后追加
한국어。 - 更新根 README 支持语言列表:按 TRANSLATIONS.md 的约定,在根目录
README.md底部的 supported languages 列表中加入新语言名称。这一步保证读者从主 README 能发现新的语言版本。 - 提交 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 为例)需要以下操作:
- 创建语言包:复制
apps/app/src/i18n/locales/en.ts为apps/app/src/i18n/locales/de.ts,逐条翻译 value,保留全部 key 与占位符。可在文件头部像zh.ts那样添加术语约定注释。 - 注册语言文件导出:在 apps/app/src/i18n/locales/index.ts 中新增
export { default as de } from "./de";。 - 注册到核心索引:在 apps/app/src/i18n/index.ts 中完成四处同步修改:
Language联合类型中加入"de";LANGUAGES数组中追加"de";LANGUAGE_OPTIONS中追加{ value: "de", label: "German", nativeName: "Deutsch" }(供语言选择器显示,nativeName必须是该语言的母语自称);TRANSLATIONS映射中加入de并import对应语言包。
- 复数规则确认:若目标语言属于无可见复数标记的语言(如日语、简体中文、泰语),需确认
PLURAL_SUFFIX_EMPTY_LANGUAGES集合是否需要更新;否则按Intl.PluralRules补齐_one/_other等变体。 - 运行审计脚本(见下一节)验证 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 的指引与仓库约定,贡献翻译的推荐路径为:
- README 翻译:按第二节 5 步流程操作,改动范围仅限
translated_readmes/与根README.md; - UI 翻译:按第五节流程新建或完善语言包,并用 scripts/i18n-audit.mjs 的
--missing、--plurals、--placeholders模式自检; - 不确定时先开 issue:TRANSLATIONS.md 明确建议,如果不确定从何入手,可以开一个 issue 并注明想贡献的语言,维护者会给出更具体的指引;
- 提交 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 贡献一门新的母语版本。