Project AIRI 术语表工程化指南:从 terms.yaml 到 Crowdin TBX 的 i18n 流水线

原创2026-10-16 11:33:482,302 阅读
文章标签:AI 应用大模型AI Agent数字人前端后端桌面应用移动开发音频

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 给出的判定标准非常精炼——只有当一个术语能阻止下面两种失败之一时,才应当加入:

  1. 只读源字符串的译者选错了词(例如把产品功能名误译成普通名词);
  2. 两位译者各自选了一个正确但不同的词,造成同一产品概念在不同语言版本中不一致。

反过来,明确不添加的情况有四类:

情形 原因 示例
它是代码 被翻译的控制令牌、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"的写作纪律,都具备直接的可复制价值。

登录后查看全文
airi