Apache Airflow 加泰罗尼亚语（ca）UI 翻译规范：术语表、语法约定与 i18next 实践指南

本文聚焦 Apache Airflow 仓库中加泰罗尼亚语（Catalan，locale 代码 ca）的 UI 翻译指南文档 .agents/skills/airflow-translations/locales/ca.md。该文档是 Airflow 国际化（i18n）体系中面向 AI 翻译代理的"语言风格宪法"，规定了哪些 Airflow 专有术语必须保留英文、哪些概念有固定的加泰罗尼亚语译法，以及性数一致、缩略、变音符号等语言层面的硬性规则。读完本文，你将完整掌握 ca locale 的术语表与状态词汇、可直接复现的复数键（plural key）写法，并能结合仓库中的真实翻译文件与校验工具链理解这些规则是如何被落地和验证的。

加泰罗尼亚语在 Airflow i18n 体系中的位置

Airflow 新一代 UI 采用 i18next 方案，所有翻译文件以 JSON 命名空间（namespace）形式存放在 airflow-core/src/airflow/ui/public/i18n/locales/<locale>/ 目录下。ca locale 目前已包含 admin.json、assets.json、browse.json、common.json、components.json、ca/dag.json、dags.json、dashboard.json、hitl.json、tasks.json 等文件（例如 common.json、tasks.json），与英文默认 locale 的命名空间一一对应。

ca.md 这类 locale 指南文件位于 .agents/skills/airflow-translations/SKILL.md 所定义的翻译技能目录下，每个支持的语言都有一个对应的指南文件（如 locales/de.md、locales/zh-CN.md 等）。SKILL.md 明确了这些指南的用途：翻译前先阅读目标语言的指南文件，其中包含术语表（glossary）、语气规则和格式约定；当 locale 指南与全局翻译规则冲突时，以 locale 指南为准。也就是说，ca.md 的权威性高于 SKILL.md 中的全局规则。

从仓库源码结构看，ca 语言已在两处被正式注册：

• UI 前端 config.ts 的 supportedLanguages 数组中包含 { code: "ca", name: "Català" }（默认语言为 en）；
• Breeze 开发工具链 ui_commands.py 的 PLURAL_SUFFIXES 字典中，"ca" 映射到 MOST_COMMON_PLURAL_SUFFIXES = ["_one", "_other"]，即加泰罗尼亚语只需要 _one 和 _other 两个复数后缀。

这两处注册正是 ca.md 中复数规则与校验工作流的底层实现依据。

1. 必须保留英文的核心 Airflow 术语

ca.md 第 1 节列出了一组**必须原样保留英文（大小写敏感）**的 Airflow 专有术语。这条规则的目的是：Airflow 的概念在代码、文档和社区中都以英文形式传播，UI 中保留英文可避免加泰罗尼亚语用户跨文档检索时产生认知断裂。完整清单如下：

术语	说明
Dag / Dags	Airflow 核心概念；严禁写成 "DAG"
XCom / XComs	Airflow 跨任务通信机制
Asset / Assets	Airflow 跟踪的数据依赖
Plugin / Plugins	可扩展性机制（导航/标签中译为 "Extensió"，但代码引用中保留英文）
Pool / Pools	资源约束机制
Provider / Providers	Airflow 扩展包名
Map Index	任务映射索引
PID	Unix 进程标识符
ID	通用缩写
UTC	时间标准
JSON	标准技术格式名
REST API	标准技术术语
日志级别	CRITICAL、ERROR、WARNING、INFO、DEBUG

在真实翻译文件中可以印证这一规则。例如 common.json 中：

"asset_one": "Asset",
"asset_other": "Assets",
"assetEvent_one": "Esdeveniment d'Asset",
"assetEvent_other": "Esdeveniments d'Asset"

Asset 本身保留英文，只有其修饰词被翻译；dag_task_instance 详情面板中的 pid、pool、executor 键值也均为英文（见 common.json 的 taskInstance 节）。值得注意的是，术语表允许语境化的例外：Plugin 在 UI 导航标签中译为 "Extensió"（见 common.json 的 admin.Plugins: "Extensions" 与 nav.plugins: "Extensions"），但代码引用处仍保留英文——这正是指南中"nav/labels 中译为 Extensió，代码引用保留英文"的落地方式。

2. 已确立的加泰罗尼亚语标准译法

第 2 节是 ca locale 的核心术语表。以下译法必须被一致使用，任何翻译代理不得为同一概念发明新词汇：

英文术语	加泰罗尼亚语	备注
Task	Tasca / tasca	复合语境中用小写
Task Instance	Instància de tasca	复数 "Instàncies de tasca"
Task Group	Grup de tasques
Dag Run	Execució de Dag	复数 "Execucions de Dag"
Backfill	Reompliment	复数 "Reompliments"
Trigger（名词）	Disparador
Trigger Rule	Regla d'execució
Triggerer	Triggerer	组件名，技术引用保留英文
Scheduler	Programador
Schedule（名词）	Programació
Executor	Executor
Connection	Connexió	复数 "Connexions"
Variable	Variable	复数 "Variables"
Audit Log	Registre d'auditoria
Log	Registre
State	Estat
Queue（名词）	Cua	如 "En cua" 表示 "queued"
Config / Configuration	Configuració
Operator	Operador	复数 "Operadors"
Asset Event	Esdeveniment d'Asset	"Asset" 保留英文
Dag Processor	Dag Processor	组件名，保留英文
Heartbeat	Batec
Plugin	Extensió	仅用于 UI 导航/标签

对照 common.json 的实际条目，术语表与现有翻译完全吻合：dag_one: "Dag"、dagRun_one: "Execució de Dag"、dagRun_other: "Execucions de Dag"、backfill_one: "Reompliment"、taskInstance_one: "Instància de tasca" 等。Triggerer 保留英文这一点也能在 taskInstance.triggerer 子节中得到验证："title": "Informació del Triggerer"、"assigned": "Triggerer assignat"，组件名未被翻译。

3. Task/Run 状态词汇表

第 3 节给出了 Airflow 任务与运行状态的完整映射表，这是状态徽章、日志标签等高频 UI 元素的翻译依据：

英文状态	加泰罗尼亚语
running	Executant-se
failed	Fallit
success	Exitós
queued	En cua
scheduled	Programat
skipped	Saltat
deferred	Diferit
removed	Eliminat
restarting	Reiniciant
up_for_retry	A reintentar
up_for_reschedule	A reprogramar
upstream_failed	Fallit aigües amunt
no_status / none	Sense estat
planned	Planificat
open	Obert

这份表与 common.json 中的 states 对象逐键对应。例如 upstream_failed → "Fallit aigües amunt"（直译为"上游失败"，aigües amunt 是"上游"的地道表达）、up_for_retry → "A reintentar"、up_for_reschedule → "A reprogramar"。现有文件还额外包含 awaiting_input → "Esperant entrada"，这是指南术语表尚未收录的状态，说明 ca.md 的术语表是"存量沉淀"而非封闭清单——新增状态仍需遵循同样的风格（句首大写、状态短语保持简短）来补齐。

4. 加泰罗尼亚语语言规则详解

第 4 节是本文档的技术核心，针对加泰罗尼亚语的语法特征给出翻译层面的操作细则。

语气与语域（Tone and Register）

• 使用正式、专业的语域，适合技术软件 UI；
• 避免口语化表达，优先选择中性、精确的用词；
• UI 字符串保持简短——它们出现在按钮、标签和工具提示中。

这一语域约定在现有翻译中体现为大量使用正式句式，例如 common.json 中的错误提示 "S'ha produït un error inesperat"（发生了一个意外错误）与确认句 "Està segur que vol eliminar {{resourceName}}? Aquesta acció no es pot desfer."，均为标准书面语而非口语。

性数一致（Gender Agreement）

加泰罗尼亚语名词有阴阳性，形容词和冠词必须与之匹配。指南固定了 Airflow 关键术语的性别归属：

• "Dag" 按阳性处理："el Dag"、"un Dag"；
• "Tasca" 为阴性："la tasca"、"una tasca"；
• "Execució" 为阴性："una execució"、"l'execució"；
• "Connexió" 为阴性："la connexió"；
• "Variable" 为阴性："la variable"；
• "Instància" 为阴性："la instància"。

这一规则解释了为什么翻译中会出现 "ID de l'execució"（runId，阴性名词 + 缩略冠词）与 "ID del Dag"（dagId，阳性名词 + del）这样的差异——冠词与缩略形式由名词性别直接决定，翻译时必须先判定性别再选择 el/la/del/de l' 等变体。

复数形式（i18next 复数后缀）

加泰罗尼亚语使用 i18next 的 _one 和 _other 两个复数后缀（与 Breeze 工具链中 PLURAL_SUFFIXES["ca"] 的配置一致）。按标准加泰罗尼亚语规则添加 -s 或 -es，或直接使用术语表的既定形式：

"task_one": "Tasca",
"task_other": "Tasques"

"dagRun_one": "Execució de Dag",
"dagRun_other": "Execucions de Dag"

ui_commands.py 中的 expand_plural_keys 函数实现了配套逻辑：它根据语言所需的后缀展开复数基础键（plural base），并结合英文 locale 中是否包含 {{count}} 占位符来判断哪些复数键是必需的，从而避免把语言不需要的复数键误报为 unused。这解释了为什么 ca 的翻译文件里每个可数资源（如 asset_*、backfill_*、taskGroup_*）都成对出现 _one/_other 键。

大小写（Capitalization）

• 描述性文字和较长字符串使用句首大写（sentence case）；
• 标题、标签和按钮文本采用类标题大写，风格与现有翻译保持一致；
• 专有术语首字母大写："Dag"、"Asset"、"XCom"、"Pool" 等；
• 不得在句中给普通名词大写。

缩略与冠词融合（Elision and Contractions）

必须应用加泰罗尼亚语标准缩略规则：

• de + 元音 → d'（例："Registre d'auditoria"、"ID d'execució"）；
• el/la + 元音 → l'（例："l'execució"、"l'operador"）；
• 介词融合：a + el → al；de + el → del。

现有翻译是这些规则的示范："Temps d'espera de l'execució del Dag"（Dag 运行超时，common.json 的 dagDetails.dagRunTimeout）在一句话里同时出现了 d'、l'、del 三种形态。

变音符号（Diacritics）

必须完整保留加泰罗尼亚语变音符号：à、è、é、ï、ò、ó、ú、ü、ç，以及 l·l 中的间隔点 ·。绝不省略或替换重音——例如绝不允许把 "Execució" 写成 "Execucio"。注意间隔点案例："Col·lapsar"、"Coincidir" 中的 l·l 是标准拼写而非排版错误，翻译代理在 lint 或手工校对时需将其视为合法字符。

语序（Word Order）

加泰罗尼亚语采用与英语相同的 SVO 标准语序；形容词通常后置于名词，例如 "interval de dates"（日期区间）、"execució activa"（活动运行）。这一约定保证了从英文源串翻译时句法结构基本平移，降低了错译风险。

5. 从现有翻译文件提取的实战模式

第 5 节从存量 ca/*.json 中归纳了三类可直接复用的模式。

始终保持英文的术语："Dag" → "Dag"、"Asset" → "Asset"、"XCom" → "XCom"、"Pool" → "Pool"、"Provider" → "Provider"。

通用翻译键值模式（与 common.json 实际内容一致）：

task_one              → "Tasca"
task_other            → "Tasques"
dagRun_one            → "Execució de Dag"
dagRun_other          → "Execucions de Dag"
backfill_one          → "Reompliment"
backfill_other        → "Reompliments"
taskInstance_one      → "Instància de tasca"
taskInstance_other    → "Instàncies de tasca"
assetEvent_one        → "Esdeveniment d'Asset"
assetEvent_other      → "Esdeveniments d'Asset"
running               → "Executant-se"
failed                → "Fallit"
success               → "Exitós"
queued                → "En cua"
scheduled             → "Programat"

操作动词（按钮文案）：

Add     → "Afegir"
Delete  → "Eliminar"
Edit    → "Editar"
Save    → "Desar"
Reset   → "Restablir"
Cancel  → "Cancel·lar"
Confirm → "Confirmar"
Import  → "Importar"
Export  → "Exportar"
Search  → "Cercar"
Filter  → "Filtrar"

这些动词在 common.json 的 modal 子节中均有对应实例（"add": "Afegir"、"cancel": "Cancel·lar"、"confirm": "Confirmar"、"save": "Desar"），tasks.json 中则有 "searchTasks": "Cercar tasques"、"selectOperator": "Seleccionar operadors" 等组合用法。

6. 翻译代理的 DO / DON'T 清单

第 6 节给出面向 AI 翻译代理（也是人工译者）的硬性约束，可直接作为代码评审 checklist：

DO（必须做）：

• 与现有 ca/*.json 文件的语气、风格、性数一致和大写方式保持一致；
• 全程使用正式的加泰罗尼亚语语域；
• 保留所有 i18next 占位符：{{count}}、{{dagName}}、{{type}} 等；
• 应用正确的加泰罗尼亚语缩略（d'、l'）与冠词融合（al、del）；
• 保留所有变音符号（à, è, é, ï, ò, ó, ú, ü, ç, ·）；
• 为每个键提供所需的全部复数后缀（_one、_other）。

DON'T（禁止做）：

• 翻译第 1 节列出的 Airflow 专有术语；
• 省略或替换变音符号（例如绝不允许把 "Execució" 写成 "Execucio"）；
• 修改热键值（例如 "hotkey": "e" 必须保持为 "e"）；
• 在现有翻译已有对应词汇时另造新词；
• 使用 "DAG"——永远写 "Dag"；
• 在句中给普通名词首字母大写。

关于占位符规则，可以结合 SKILL.md 的全局规则进一步理解：{{variable}} 插值中的变量名绝不能翻译或删除，但占位符位置可以为了符合目标语言语序而重排，且变量大小写必须精确保留（如 {{dagDisplayName}}）。common.json 中的批量清理提示是典型范例：

"description": "{{count}} {{resourceName}} s'han netejat correctament. Claus: {{keys}}"

{{count}} 置于句首以匹配加泰罗尼亚语语序，而 {{resourceName}}、{{keys}} 均原样保留。热键不翻译的规则同样可见："download": { "hotkey": "d", "tooltip": "Prem {{hotkey}} per a descarregar els registres" }——热键值是字面按键绑定，仅提示语被翻译。

7. 配套校验工作流：breeze 翻译完整性检查

虽然 ca.md 本身只定义语言规则，但它服务的翻译任务最终要通过仓库工具链验收。按照 SKILL.md 的流程，对 ca 这类已存在的 locale：

1. 检查完整性，查看缺失键与覆盖率：

   breeze ui check-translation-completeness --language ca
   

2. 补齐缺失键（生成 TODO: translate: 桩）：

   breeze ui check-translation-completeness --language ca --add-missing
   

3. 清理无用键（英文 locale 中不存在、或该语言不需要的复数后缀）：

   breeze ui check-translation-completeness --language ca --remove-unused
   

4. 翻译完成后验证：输出表应显示 0 missing、0 TODOs、0 unused、100% coverage；随后运行 pre-commit 钩子修复格式、许可证头与 lint 问题：

   prek run --from-ref main --hook-stage pre-commit
   

从源码结构看，该命令的复数判定逻辑由 ui_commands.py 中 PLURAL_SUFFIXES 与 expand_plural_keys 共同实现：对 ca 而言，只有当英文源键包含 {{count}} 或英文侧定义了多种复数形式时，才会把复数基础键展开为 base + _one / base + _other 并纳入"必需键"集合——这与 ca.md 中"提供每个键所需的全部复数后缀（_one、_other）"的要求完全对应。因此，翻译代理只要遵循 ca.md 的术语表与复数规则，breeze ui check-translation-completeness 就能给出确定性的验收结论。

小结

ca.md 的价值在于它把"翻译加泰罗尼亚语 UI 字符串"这一开放问题收敛为一套可机械执行的规则集：英文保留术语表（Dag/XCom/Asset/Pool/Provider 等）+ 固定译法术语表（Tasca、Execució de Dag、Reompliment 等）+ 状态词汇表 + 六条语法硬规则（语域、性数、复数、大小写、缩略、变音符号、语序）+ DO/DON'T 清单。配合仓库中 ca locale 现有翻译 作为风格范本、config.ts 中的语言注册与 Breeze 完整性检查工具 作为验收手段，这套规则保证了新产生的加泰罗尼亚语字符串与既有翻译 100% 一致。文档版本标注为 1.0（2026 年 3 月，派生自现有 ca/*.json locale 文件），后续若 states 等对象新增条目，应按同样的风格约定回填并更新指南。