Project AIRI 术语表工程化指南:从 terms.yaml 到 Crowdin TBX 的 i18n 流水线
Project AIRI 术语表工程化指南:从 terms.yaml 到 Crowdin TBX 的 i18n 流水线
本文以 packages/i18n 包的术语表(Glossary)管理体系为线索,系统讲解 Project AIRI 如何以一份 YAML 作为英文术语的唯一事实源,借助 Valibot 校验与 TBX 生成器输出 Crowdin 可导入的 ISO 30042 术语交换文件。读完本文,你将掌握 terms.yaml 的数据模型与字段语义、术语新增/排除的判定规则、一句话定义的写作规范,以及隐藏在 build-tbx.test.ts 中的格式保障机制,可直接复用于任何基于 Crowdin 的多语言产品。
一、i18n 包的定位与职责边界
Project AIRI 是一个采用 pnpm workspace 的多端 monorepo,包含 Web、Electron 桌面端、移动端等多个应用。所有面向用户的字符串与翻译都收敛在 packages/i18n 一个包内(根目录 AGENTS.md 的项目地图中将其职责标注为 "All translations")。包自身的 AGENTS.md 开篇就划定了两条范围边界:
- 范围是
packages/i18n/**,以及用户能看到的每一个字符串(every string that a user sees); - 具体该编辑哪些 locale 文件,由根目录 AGENTS.md 给出规则。
从 src/index.ts 可以看到,AIRI 共维护 9 个语言目录:en、es、fr、ja、ko、ru、vi、zh-Hans、zh-Hant。其中英文是唯一由仓库拥有的语言(source of truth),其余 8 种语言由 Crowdin 平台托管,翻译结果通过 Pull Request 回到仓库的 src/locales/<locale>/ 目录。根 AGENTS.md 对此有明确纪律:默认只编辑英文源语言和开发者自己的语言,不要随意改动其他 locale,因为下一次 Crowdin 同步会覆盖本地改动。
二、术语表工作流总览:一份 YAML 驱动整条流水线
术语表(Glossary)是 AIRI i18n 体系中最核心的工程机制,它的目的不是"记录术语",而是在翻译发生之前消除歧义。整条流水线由三个文件与一个命令构成:
| 文件/命令 | 角色 |
|---|---|
| glossary/terms.yaml | 英文术语唯一事实源,每个产品概念给出经批准的英文词 |
pnpm -F @proj-airi/i18n glossary:build |
读取并校验 terms.yaml,生成 Crowdin 导入所需的 TBX 文件 |
| glossary/schema.ts | 用 Valibot 定义每个字段的约束,并记录字段与 TBX 元素的映射关系 |
| glossary/build-tbx.ts | TBX 生成器的实际实现(由 glossary:build 脚本调用) |
glossary:build 在 package.json 中定义为 tsx glossary/build-tbx.ts,命令的产物默认写入 glossary/glossary.tbx(build-tbx.ts 的 main() 接受一个可选输出路径参数)。生成器在运行结束时会在标准输出打印统计信息:wrote <path>: <concepts> concepts, <terms> terms。
terms.yaml 的头部注释把分工讲得很清楚:这个仓库拥有英文,Crowdin 拥有其他 8 种语言;翻译后的术语会经 Pull Request 落入 packages/i18n/glossary/translations/ 目录——而 AGENTS.md 明确禁止手动编辑该目录,因为"下一次 Crowdin 下载会替换它"。
三、terms.yaml 数据模型:概念(Concept)与词条(Term)
terms.yaml 采用"概念—词条"两级结构:一个 concept(概念)是一个 glossary entry,对应 id、subject、translatable、definition 等概念级字段;每个概念下挂一个或多个 terms(词条),词条记录具体拼写与语言学属性。以术语 airi 为例:
- id: airi
subject: product
translatable: false
definition: The application that this project makes, an animated character that speaks, listens, and sees.
note: >
Keep the Latin letters in every language; only prose may write the Japanese form アイリ.
terms:
- text: AIRI
part-of-speech: proper noun
status: preferred
context: Welcome to AIRI!
- text: Project AIRI
part-of-speech: proper noun
status: preferred
type: fullForm
note: The full name, used on first mention.
概念级字段
<a href="https://link.gitcode.com/i/e7a604cc11d809315ff04b89e4f905e5" target="_blank">schema.ts</a> 中 ConceptSchema 定义了以下概念级字段:
| 字段 | 校验约束 | TBX 映射 |
|---|---|---|
id |
必须为 kebab-case(正则 ^[a-z0-9]+(?:-[a-z0-9]+)*$),且全表唯一 |
<conceptEntry id="..."> |
subject |
非空字符串 | <descrip type="subjectField"> |
translatable |
布尔值 | <descrip type="translatable">(Crowdin 扩展) |
definition |
非空字符串,约定一句话 | <descrip type="definition"> |
note |
可选字符串 | <note> |
url |
可选、必须是合法 URL | <xref type="externalCrossReference"> |
terms |
至少 1 个词条 | <langSec xml:lang="en"> 下的 <termSec> |
词条级字段
TermSchema 定义了词条字段,其命名刻意跟随 TBX 数据类别而非自定义名称,让映射一目了然:
| 字段 | 允许取值(Valibot picklist) | TBX 映射 |
|---|---|---|
text |
非空字符串 | <term> |
part-of-speech |
adjective / adposition / adverb / auxiliary / coordinating conjunction / determiner / interjection / noun / numeral / particle / pronoun / proper noun / subordinating conjunction / verb / other | <termNote type="partOfSpeech"> |
status |
preferred / admitted / deprecated | <termNote type="administrativeStatus"> |
type |
fullForm / acronym / abbreviation / shortForm / variant / phrase | <termNote type="termType"> |
gender |
masculine / feminine / neuter / other | <termNote type="grammaticalGender"> |
context |
可选,展示词条用法的句子 | <descrip type="context">(仅允许词条级) |
note |
可选 | <note> |
值得注意的一个细节是词性取值:TBX-Basic 规范写作 properNoun(DC-0396),但 Crowdin 导出时写作带空格的 "proper noun"。schema.ts 的注释明确记录了这一坑——Crowdin 读取的是上传内容,所以以 Crowdin 的写法为准,此前一个版本要求 properNoun,反而会拒绝 Crowdin 自己产生的数据(这一结论在 build-tbx.test.ts 中有专门测试用例锁定)。
status 的三个取值是 ISO 704:2022 所称的"可接受度评级"(acceptability rating),对应语义为:preferred(推荐)、admitted(可用但不推荐)、deprecated(弃用)。terms.yaml 中有两个值得学习的用法:
- 同义词组:
neuro-sama概念下同时登记了Neuro-sama(preferred)、Neuro Sama(admitted variant)、Neuro(admitted shortForm); - 弃用标记:
pocket概念下把Stage Pocket标为deprecated,并注明"既不是代号也不是用户看到的名称"。
id 的稳定性是一条重要纪律:schema 注释说明,修改 id 会在 Crowdin 中创建新概念而非更新旧概念,因此 id 必须能在词条改名后存活。
四、生成 TBX:build-tbx.ts 的实现要点
build-tbx.ts 是流水线的核心执行器,其调用链为 main → parseGlossary(Valibot 校验)→ buildTbx → buildConceptEntry。实现中有几处与互操作强相关的工程决策:
1. 精确对齐 TBX-Basic 与 Crowdin 的导出形态
- 根元素使用 ISO 30042:2019 命名空间
urn:iso:std:iso:30042:ed-2,并携带 TBX-Basic 要求的四个属性:type="TBX-Basic"、style="dca"(data-category-as-attribute 风格)、xml:lang="en"、xmlns; - 文件头写入与 Crowdin 导出一致的两条 schema 处理指令(
TBXcoreStructV03_TBX-Basic_integrated.rng与TBX-Basic_DCA.sch),使 XML 编辑器可以校验文件,同时保证与重新下载的 Crowdin 文件做 diff 时差异最小; <tbxHeader>只携带sourceDesc,与 Crowdin 的导出形状一致(测试断言不包含<titleStmt>);- 输出用四空格缩进对齐 Crowdin 导出的排版,让 diff 可读;但元素内含文本的节点不缩进,因为定义或注释中的空白是内容而非排版。
2. 状态值映射
ADMINISTRATIVE_STATUS 把可读状态映射为 Crowdin 导出时实际书写的带后缀形式(来自 ISO 12620):
const ADMINISTRATIVE_STATUS: Record<Term['status'], string> = {
preferred: 'preferredTerm-admn-sts',
admitted: 'admittedTerm-admn-sts',
deprecated: 'deprecatedTerm-admn-sts',
}
3. 元素顺序不是装饰而是正确性
TBX-Basic 固定了每个 section 内部的元素顺序,生成器中的顺序是刻意为之:
conceptEntry内,所有langSec必须排在其它子元素之后;langSec内,所有termSec排在其它子元素之后;termSec内,term在最前,接着是所有termNote,然后才是context与note。
顺序错误会导致 schema 校验器直接拒绝整个文件(而不是部分导入),因此测试用 indexOf 断言了每一处相对顺序。
4. Crowdin 扩展字段
translatable 是 TBX-Basic 没有的数据类别,属于 Crowdin 扩展:生成器把它写成概念级第一个 descrip,值为 yes/no,与 Crowdin 自身导出的形态一致。
5. 折叠块(folded block)的段落处理
YAML 的 > 折叠块会把换行折叠成空格、空行折叠成一个换行。collapse() 函数因此按"两个及以上换行"分割段落——注释特别提醒,按"两个换行"分割看似正确实则错误,因为 YAML 给空行的是单个换行符,这样分割会匹配不到任何内容。生成器会把概念与词条的 note 统一通过 collapse 处理,输出干净的段落。
五、何时添加术语:两条失败判据
AGENTS.md 给出的判定标准非常精炼——只有当一个术语能阻止下面两种失败之一时,才应当加入:
- 只读源字符串的译者选错了词(例如把产品功能名误译成普通名词);
- 两位译者各自选了一个正确但不同的词,造成同一产品概念在不同语言版本中不一致。
反过来,明确不添加的情况有四类:
| 情形 | 原因 | 示例 |
|---|---|---|
| 它是代码 | 被翻译的控制令牌、JSON key、文件名、包名会静默破坏应用,且不报任何错误 | ACT、DELAY、CALL 流式控制令牌 |
| 它是含义常规的常用英文词 | 无需干预 | "Speed"、"Volume" |
| 它的各部分都已有词条且含义不超过各部分之和 | 组合词无需整体登记 | "VRM model" |
| 仅一个功能使用,且只有两位译者可能产生分歧 | 风险不足 | 但 Tachie 例外——它虽只出现两次,却是全文件最强的一条,因为译者很可能搞错 |
关于"代码不能入表",build-tbx.test.ts 专门有一条测试把 terms.yaml 中所有词条与 base.yaml 里的控制令牌比对,断言不存在 ACT/DELAY/CALL 或含 /{}<> 的词条。原因在测试注释里写得很清楚:base.yaml 会把流式控制令牌随系统提示词交给译者,翻译后的令牌会破坏舞台播放且无任何错误提示,所以令牌绝不能成为译者被邀请翻译的术语。
另外一条隐含规则是术语的来源方向:从界面取词,用文档确认词,而不是为了找词去搜文档。terms.yaml 中 magic-motion 的 context("MAGIC motion driver")与 light-wrap 的 context("Set the overall effect amount...")都是从真实界面字符串中摘取的。
六、定义写作规范:一句话定义 + note 承载否定规则
terms.yaml 不存放 rationale(理由),因为每个字段都必须映射到一个 TBX 元素,没有给"为什么加这个词条"留位置——所以添加术语的理由写在 Pull Request 描述里,而不是文件里。
而词条定义本身有严格的写作纪律:
- 用一句话写定义(只有一句话无法承载含义时才允许两句);
- 描述事物本身,而不是描述这个词(Describe the thing, not the word);
- 否定规则放进
note,而不是塞进定义; - 句子保持简短、主动:译者要读这些文字,而且多数译者不以英语为母语。
对照 terms.yaml 中的实际条目,可以清晰看到这套纪律的落地:
light-wrap的note:"It is the color reaching around the edge, not a glow drawn outside it and not a halo."——用否定句排除了"外部辉光"和"光晕"两种误译;backlight的note:"The photographic sense... Do not use the word for the lamp behind a display panel."——从摄影语义出发,堵住"面板背光灯"这一错误方向;memory的note:"Not the computer's RAM... use the word for what a person remembers."——把"内存条"与"角色记忆"两个语义一刀切开;motion与expression的联动约束:"A Motion moves the body and an Expression changes the face; use two different words."——强制两种翻译用词不得相同。
这些 note 本质上就是给译者的"决策表",用最短的句子把最可能的错误方向全部排除掉。
七、测试保障:build-tbx.test.ts 如何守住格式边界
术语表工程化最怕"悄悄变坏",build-tbx.test.ts 用 15 个测试用例从五个层面锁死了这条流水线:
1. 文档形状:断言输出以 XML 声明开头、包含两条 schema 处理指令、根元素携带正确命名空间与 type="TBX-Basic"/style="dca",且 <tbxHeader> 只有 sourceDesc。
2. 缩进与排版:断言四空格缩进风格,同时断言定义元素内的文本不被插入缩进(那是内容)。
3. 元素顺序:用 indexOf 逐对断言 subjectField/definition 在 langSec 之前、term 在 termNote 之前、context 在 note 之前。
4. 数据校验:拒绝重复 id、拒绝非 kebab-case 的 id、接受 Crowdin 风格的 "proper noun" 拼写并拒绝 properNoun、允许同一概念存在多个 preferred 词条(Crowdin 本身允许)。
5. 对 terms.yaml 本身的治理:这是最体现工程价值的部分——测试会真实加载 terms.yaml 校验,并断言:
- 每个非
documentation主题的词条都必须出现在界面字符串或英文文档中(否则译者永远匹配不到它,形同虚设;测试注释披露Ayaka Neko就是因为这个检查被移除的); - 每个
context句子必须包含它所属的词条本身(防止张冠李戴); - 不存在任何控制令牌词条(见第五节)。
这套测试让"加一个词条"变成了一个有完整回归保障的工程操作。
八、与 Crowdin 的协作边界与人工复核流程
术语翻译的最终裁决在 Crowdin,仓库侧通过 enforce-rules-for-i18n 技能维护一套人工复核流程:用脚本拉取待审翻译、按策略批量给出 approve/reject 决策、干跑验证"All matched."后由真人持 token 执行。其中的语言 id 映射值得注意,Crowdin 语言 id 与仓库目录名并不完全一致:
| Crowdin | 仓库目录 |
|---|---|
es-ES |
es |
zh-CN |
zh-Hans |
zh-TW |
zh-Hant |
复核策略与术语表规则一脉相承:与英文相同的翻译直接拒绝(因为 AIRI 对未翻译字符串显示英文,Crowdin 也不导入与源相同的翻译);占位符不一致、\n 被写成字面量、词性错误(名词标签译成动词短语)都属拒绝项。
九、开放问题:terms.yaml 中的 TODO
terms.yaml 中保留了若干带 # TODO: 注释的开放问题,它们如实反映了项目演进中的未决状态(从源码结构看,这些是作者主动留下的决策点):
airi概念的translatable取值:界面字符串在 8 种语言中都保留 "AIRI",但项目散文(包括英文 README)中使用了日语形式 アイリ,是否应允许翻译存在争议;tachie的中文措辞等待母语者确认,当前约定是"没有对应词的语言保留 Tachie";long-term-memory与short-term-memory两个概念已有设置页与路由,但尚无描述行为的实现,定义待确认;character概念正处于改名进行时:界面今天仍用 "Character" 指代一个更小的事物(卡片内的一个标签),而本概念的计划名尚未启用,当前以AIRI Card为 admitted 词条。
十、术语表之外:locale 解析与启动回退
最后补充术语表的外围拼图,让读者理解这份术语服务于哪套运行时。src/index.ts 导出 9 种语言的完整目录对象,并通过 localeRemap 把浏览器/系统的区域标识归一化(例如 zh-CN→zh-Hans、zh-TW→zh-Hant、en-US/en-GB→en),resolveSupportedLocale 在不支持的 locale 上回退到 en。而 startup-fallback.ts 把 Vue 启动前的引导失败文案(failed/retry)序列化为 JSON 字符串,供尚未挂载框架的内联 splash 使用——它要求英文标签必须存在,其余语言缺失时回退英文,并把 < 转义为 \u003c 防止内联注入问题。
结语
Project AIRI 的术语表体系是一个"小而完整"的工程样板:一份 YAML 作为单一事实源,Valibot schema 在入口处拦截结构错误,TBX 生成器对齐 ISO 30042 与 Crowdin 的双重格式约束,测试套件守护格式边界与术语有效性。对任何引入 Crowdin 做多语言协作的产品,terms.yaml + schema.ts + build-tbx.ts 的这套组合,以及"一句话定义 + note 排否定 + 理由写进 PR"的写作纪律,都具备直接的可复制价值。