- 桌面应用
【免费下载链接】helium-chromium
Private, fast, and honest web browser
导读
Helium 是一个基于 Chromium 的浏览器项目，其 UI 界面字符串的国际化（i18n）工作流由 i18n/prompt.md 这份"翻译提示词"文档驱动——它不是给人看的说明，而是喂给 LLM 的翻译指令模板。本篇文章将逐条拆解这份 prompt 的 11 条翻译规则与输入/输出格式契约，并结合仓库中真实的源码（devutils/i18n_generate.py、devutils/i18n_translate.py）、数据文件（i18n/source.gen.json、i18n/languages.json）与 70 余个语言翻译文件，帮助你完整理解 Helium 的 UI 字符串翻译体系，并掌握可直接复用的浏览器类产品翻译提示词工程方法。
一、prompt 在 Helium 翻译流水线中的位置
要理解这份 prompt 的价值，先要看它在整个 i18n 管线中扮演什么角色。Helium 的翻译流程是"从补丁提取 → LLM 翻译 → 回写 Chromium"三段式：
- 提取（generate）：
./devutils/i18n.py generate会克隆三个平台仓库（windows/macos/linux）与 onboarding 仓库，读取所有patches/series中触碰到.grd/.grdp文件的补丁，用 unidiff 解析 diff hunk，把新增或改动的 GRIT<message>单元抽取为 JSON 条目，输出到 i18n/source.gen.json。每条记录包含name（如IDS_SETTINGS_PERFORMANCE_*）、source（来自哪个 GRD 文件）、context（用途说明）与message（英文原文）。实现细节见 devutils/i18n_generate.py。 - 翻译（translate）：
./devutils/i18n.py translate调用i18n_translate.py，加载 i18n/prompt.md 作为 system prompt，把语言名与语言代码替换进{{language_name}}/{{language_code}}占位符（devutils/i18n_translate.py），再将待翻译字符串的 JSON 数组作为 user 消息发送给 LLM（OpenAI 兼容的 completions API，或通过--cmd指定的命令行后端）。模型返回纯 JSON 后经解析、校验，合并写回i18n/translations/<lang>.json。 - 应用（apply）：
utils/i18n_apply.py将翻译结果按 fingerprint 写入 Chromium 的 XTB 文件（utils/i18n_apply.py），供浏览器编译时使用。
也就是说，这份 prompt 是"翻译质量"的直接决定者：LLM 的每一句译文都严格受它约束。
二、输入与输出契约：模型需要遵守的数据格式
输入：JSON 数组
模型收到的用户消息是一个 JSON 数组，每个对象包含三个字段：
name：字符串标识符（如IDS_IMPORTED_FROM_BOOKMARK_FOLDER），不可翻译、不可改动，用于回写时与源文件匹配；context：该字符串在界面中的使用位置与用途描述，指导选词与语气；message：需要翻译的英文源字符串。
需要注意两点：
- 某些条目带有
"translate": false标记，它们是已经翻译好的上下文示例，用于帮助模型对齐既有风格与术语，不要翻译。这对应i18n_translate.py中build_payload的逻辑——它会把待翻译字符串前后各 2 条邻近条目一起打包进 payload，已翻译的邻近条目就标记为translate: false充当语境参考（devutils/i18n_translate.py）。 - 同一个
name可能多次出现，携带不同的message（平台或上下文变体），此时要逐条独立翻译，不能因为名字相同就复用或跳过。
输出：严格顺序的 JSON 数组
模型必须只输出一个 JSON 数组，且保持与输入相同的顺序，每个待翻译条目对应一个对象：
name：原字符串标识符（原样保留）；message：默认（中性）形式的译文；feminine/masculine：仅当目标语言有语法性别、且译文在面向女性/男性用户时会发生变化时才提供，与message相同则省略。
文档给出了法语例子：翻译 "Imported from X" 时，message为默认（阳性）形式"Importé depuis X"，feminine为"Importée depuis X"（过去分词随性别变化）。像 "Add search engine" 这类无性别变化的按钮文案，两个字段都要省略。仓库里的法语翻译文件正好印证了这一约定，例如 i18n/translations/fr.json 中：
{ "name": "IDS_IMPORTED_FROM_BOOKMARK_FOLDER", "source": "Imported from <ph name=\"BROWSER_NAME\">$1<ex>Helium</ex></ph>", "message": "Importé depuis <ph name=\"BROWSER_NAME\">$1<ex>Helium</ex></ph>", "feminine": "Importée depuis <ph name=\"BROWSER_NAME\">$1<ex>Helium</ex></ph>" }输出时的硬性约束还有一条：译文中的英文双引号必须转义为\"，或替换为符合目标语言习惯的引号（如法语的«»、德语的„"、日语的「」），否则未转义的双引号会破坏 JSON。此外模型不得输出任何额外文字、解释或 Markdown 格式。i18n_translate.py在解析侧也有兜底：fixup_json会剥离 json ``` 代码围栏并自动修复未转义的双引号（devutils/i18n_translate.py），parse_response则校验字段白名单（仅允许name/message/feminine/masculine）、缺失条目和顺序（devutils/i18n_translate.py）。
翻译文件的落盘格式
模型输出经save_translations合并后，最终写入i18n/translations/<lang>.json的条目结构与 prompt 的输出稍有不同——多了source字段（英文原文）用于内容匹配。匹配按name+source内容而非数组位置进行（i18n/README.md），且source.gen.json中字符串一旦变化，旧译文就会被find_untranslated判定为"过时"并触发重新翻译（devutils/i18n_translate.py）。
三、十一条翻译规则逐条拆解
1. 占位符（<ph>标签）必须原样保留
源字符串中形如<ph name="BROWSER_NAME">$1<ex>Helium</ex></ph>的占位符用于在运行时注入动态值（这里是浏览器名称）。规则要求：
- 不翻译、不重排、不修改
<ph>标签内的任何内容； - 译文必须完整保留这些标签（可整体移动其位置，但不能改动内部）。
例如 i18n/source.gen.json 中的IDS_IMPORTED_FROM_BOOKMARK_FOLDER："Imported from <ph name=\"BROWSER_NAME\">$1<ex>Helium</ex></ph>"。俄语翻译 i18n/translations/ru.json 将其译为"Импортировано из <ph name=\"BROWSER_NAME\">$1<ex>Helium</ex></ph>"——标签被完整搬到译文中。
这套机制在i18n_apply.py中还有对应的"反向转换"：把 GRD 风格的<ph name="X">...内容...</ph>正则替换为 XTB 格式的<ph name="X" />（utils/i18n_apply.py），因此模型侧保留的标签名必须与源完全一致。
2. 品牌名永不翻译
"Helium" 是产品名，任何语言都不得翻译。其他品牌名（如 "uBlock Origin"）同样保持原样。而非品牌的功能名与布局名（如内存节省模式、标签页、书签等）在目标语言有自然说法时应翻译。仓库中大量字符串都是这个模式，比如法语文件把 "Helium services" 译为 "Services Helium"——Helium 保留，services 本地化。
3. 语域（Register）：礼貌、自然，遵循目标语言的敬称惯例
要求使用礼貌、自然的 UI 语域，既不俚语化也不法律文书化。规则明确列出各语言的第二人称选择：
- 区分敬称/非敬称的语言用敬称：法语用 "vous"，德语用 "Sie"，俄语用 "вы"；
- 目标区域习惯非正式口吻的（如西班牙语 "tú"）则用非正式形式；
- 不区分正式程度的语言用中性措辞。
法语翻译中大量 "vous" 形式（如 i18n/translations/fr.json 的 "Vos onglets inactifs redeviennent automatiquement actifs lorsque vous y retournez."）就是这条规则的直接体现。
4. 简洁：长度与原文匹配，不增删信息
按钮标签与菜单项要简洁，描述性文案可以稍长，但不得添加原文没有的信息。这是"忠实翻译"在 UI 场景的落地：界面文案的长度直接影响布局与可用性。
5. 语境与大小写：用context字段指导选词
context字段描述了字符串的使用位置（如 "Title for the dialog shown when Full Disk Access is needed..."），模型应据此选择词义与语气。同时要保留有意义的 UI 大小写风格——Title Case、全大写、句子式标签——并转换为目标语言最自然的对应惯例（很多非拉丁字母语言并无英文式大小写，需按本族习惯处理）。
6. 技术术语：保持不译或使用浏览器既有标准译法
URL、HTTPS、DNS 等技术术语除非目标语言有成熟的浏览器 UI 等价词，否则保持原文。通用计算词汇（"bookmarks"、"tabs"、"downloads"）应使用主流浏览器在该语言中确立的标准译法。这条规则加上第 10 条一起，保证了 Helium 的术语与 Chrome/Chromium 生态保持一致，避免同词不同译造成的割裂感。
7. 键盘快捷键：键名与符号按目标语言/平台惯例保留
Ctrl、Shift、Tab 等键名及符号（如+、→）在绝大多数语言中保持英文/拉丁字母形式，无需本地化。这与 Chromium 的键位展示机制一致，键名改动会导致快捷键提示失效。
8. 语言正字法：俄语要用 ё
规则特别点名俄语（ru）：该写 ё 的地方必须写 ё，用 е 替代会被视为不正确或产生歧义。例如 i18n/translations/ru.json 中的 "выгружает" 系列译文对 ё/е 的处理即遵循此规则。这是"本地化质量"而非"翻译正确性"的层面，但直接影响母语者的观感。
9. 意图与语法角色：命令像命令，设置像标签，帮助像描述
- 命令与按钮要读起来像动作（"Copy"、"Open"、"Reset"）；
- 设置项要读起来像标签或开关（"Allow automatic updates"）；
- 帮助文本要读起来像描述。
并且要使用目标语言正常的命令形式——例如俄语 UI 命令常用完成体动词："Скопировать"（完成体）而非 "Копировать"（未完成体）。这要求译者不仅懂语言，还要懂该语言 UI 的惯例。
10. 浏览器风格：贴合 Chromium/Chrome 既有译法
Helium 是 Chromium 系浏览器，常见浏览器概念的术语与措辞应参考目标语言 Chromium/Chrome 风格的既有翻译。这一条把第 6 条"标准译法"落实到具体参照系，是保证 Helium 70 多种语言（i18n/languages.json 列出 74 个 locale）整体一致性的关键。
11. ICU 复数消息：语法保留，只翻括号内文本
这是最技术性、也最容易翻错的一条。部分消息使用 ICU MessageFormat 复数语法，例如：
{MINUTES, plural, =1 {minute} other {minutes}}规则要求把以下内容当作语法保留：参数名（MINUTES）、关键字plural、精确数字选择器（=0、=1）、复数类别选择器（zero、one、two、few、many、other）、offset:n、#字符及花括号。只翻译每个选择器花括号内的人类可读文本。#表示"插入按区域格式化的数量"，必须原样保留，且原文没有时不得擅自添加。
不要假设所有语言只有英语式的单复数两态。具体做法是：
- 保留源中的所有精确数字分支（如
=0、=1）； - 始终保留
other； - 使用目标语言 CLDR 基数复数类别——源中缺失的类别要补上，源中属于英语但目标语言不用的类别（如
one、few、many）要移除； - 复数类别归属查询 Unicode CLDR Language Plural Rules chart；
- 精确数字选择器优先于语言类别匹配：
=1只指数字 1，而one类别还可能覆盖 21、31 等。
文档用俄语给出完整示例：源中的{MINUTES, plural, =1 {minute} other {minutes}}应译为：
{MINUTES, plural, =1 {минута} one {минута} few {минуты} many {минут} other {минуты}}其中=1处理数字 1，one处理 21、31 等，few处理 2–4、22–24 等，many处理 0、5–20、25–30 等。注意：俄语示例只是机制演示，不是照抄模板——具体类别与措辞必须按{{language_code}}对应的语言而定。最后还要保留消息意图：如果原文省略数字（因为数字单独显示在 UI 上），译文也不要硬把数字塞回去。
source.gen.json中有不少真实 ICU 复数消息，例如崩溃报告对话框的"{COUNT, plural, =1 {Would you like to send a crash report?} other {Would you like to send # crash reports?}}"与扩展调试提示的"{NUM_EXTENSIONS, plural, =1 {This extension is debugging your browser:} other {These extensions are debugging your browser:}}"——前者是英文 only=1/other两分支，译成俄语等语言时必须按 CLDR 补出few/many等类别。
四、从 prompt 到仓库数据：一条规则的具体落地
以规则 1（占位符）与规则 11（ICU 复数）为例，串联起整个仓库：
- 提取端：
i18n_generate.py从补丁的 GRD/GRDP diff 中抽取<message>单元，name/desc/meaning取自 XML 属性，context由 desc 经name_substitution_utils.replace_text处理（devutils/i18n_generate.py），message 原文保留全部<ph>标签与 ICU 语法。 - 翻译端：prompt 作为 system 消息约束 LLM 遵守上述 11 条；
translate子命令通过--language fr de指定目标语言（缺省翻译 i18n/languages.json 中全部 74 个 locale），--from-file可离线导入人工/第三方翻译，--cmd或环境变量I18N_TRANSLATE_CMD可替换 LLM 后端（devutils/i18n_translate.py）。 - 落盘端：校验通过后写入
i18n/translations/<lang>.json，feminine/masculine按模型输出决定是否保留；source字段记录原文供内容匹配。 - 应用端：
utils/i18n_apply.py依据name+source找到 GRD/GRDP 的父 GRD 文件（find_parent_grd通过<part file="...">反查，onboarding 字符串固定挂在generated_resources.grd，见 utils/i18n_apply.py），把<ph>转成 XTB 空标签形式后写入对应语言的.xtb，最终参与浏览器编译。
五、对贡献者与翻译审校者的实践要点
结合 i18n/README.md 的流程说明，这份 prompt 对应的协作规范如下：
- 不要直接提交新语言翻译的 PR：项目按批次批量运行翻译（README 中明确说明）。但修正既有字符串错误的 PR 是欢迎的。
- 审校者关注点正是 prompt 核心规则的镜像：相对
source的准确性、<ph>占位符的完整保留、语域合适度、品牌名未翻译。 - 语言所有者机制：母语者可在 i18n/owners.yml 中申请成为某语言文件的审校负责人，配合批次机制保证长期质量。
- 开发侧：新增字符串后用
./devutils/i18n.py generate重新生成 i18n/source.gen.json，但不要自行生成机器翻译，交给维护者批量处理；翻译应用则用utils/i18n_apply.py（两者均可用-h查看完整参数）。
六、可复用的翻译提示词工程要点
如果要在自己的浏览器类产品中复刻这套方案，prompt 的设计可总结为以下可迁移原则：
- 把"输入/输出格式"写成机器可校验的契约：输入字段定义（name/context/message）、输出字段定义（name/message/feminine/masculine）、顺序要求、引号转义规则、禁出额外文本——全部写成明确指令，配合解析侧校验（字段白名单 + 缺失检测 + 顺序校验）实现闭环。
- 把"术语一致性"拆成多条可执行规则：品牌名禁译、技术术语保留、通用词用主流浏览器标准译法、风格对齐 Chromium——每一条都对应一个可检查点。
- 把"复数"单独成条并给出示例：ICU MessageFormat 最容易翻坏，规则需要明确"哪些是语法、哪些是文本"，并提供俄语这类复杂复数语言的最小示例，同时强调"示例仅为机制演示"。
- 把"语境"显式交给模型：
context字段 + 邻近已翻译条目（translate: false）双重语境，显著提升选词准确率。 - 把"质量红线"前置：语域（敬称惯例）、简洁度（不增删信息）、意图（命令/设置/描述的语法角色）都在 prompt 里一次性约束，而非事后人工返工。
结语
i18n/prompt.md 是一份高度工程化的 LLM 翻译指令：它把品牌保留、占位符保护、语域选择、术语对齐、ICU 复数、性别变体、JSON 契约等十余个维度压缩进一份模板，再由 devutils/i18n_translate.py 的解析与校验逻辑兜底。理解这份文档，不仅等于理解了 Helium 全部 74 个语言翻译文件（i18n/translations/）的生产方式，也等于掌握了一套可复用的"浏览器 UI 翻译提示词"范本。
- 桌面应用
【免费下载链接】helium-chromium
Private, fast, and honest web browser
相关推荐
AutoClip 国际化（i18n）体系全解析：多语言文档结构、CI 同步检查与浏览器翻译兼容
AutoClip 国际化（i18n）体系全解析：多语言文档结构、CI 同步检查与浏览器翻译兼容 AutoClip 是一个基于 AI 的智能视频切片与高光提取系统
人工智能AI 应用大模型音视频短视频后端前端桌面应用OpenChamber 多语言 UI 国际化（i18n）开发指南：locale-ui-patterns 规范与 `@/lib/i18n` 实现解析
OpenChamber 多语言 UI 国际化（i18n）开发指南：locale ui patterns 规范与 @/lib/i18n 实现解析 导读 本文基于
AI Agent人工智能代码智能体交互助手wp-calypso 新版 Dashboard 国际化（i18n）实践指南：@wordpress/i18n 翻译规范与 CSS 逻辑属性
wp calypso 新版 Dashboard 国际化（i18n）实践指南：@wordpress/i18n 翻译规范与 CSS 逻辑属性 本文聚焦 wp cal
前端CMS
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
