Apache Airflow 阿拉伯语（ar）UI 本地化规范：六类复数、术语词表与 CLDR 规则的工程落地

本篇指南基于 Apache Airflow 仓库中的阿拉伯语翻译 Agent 技能文档（locales/ar.md）展开，系统讲解 Airflow UI 阿拉伯语（ar）locale 的术语体系、CLDR 六类复数规则、混合语写作约束与数字书写规范，并结合 i18n 配置 与 breeze 翻译完整性检查工具 的源码实现，说明这些规则如何在真实工程中生效。读完后你将掌握：如何为 Airflow UI 新增或修订阿拉伯语字符串而不破坏既有译名一致性，以及如何用仓库自带工具验证翻译覆盖度。

1. 文档定位：ar locale 的“权威术语源”

阿拉伯语翻译指南是整个 airflow-translations 技能 中按语言拆分的 19 份 locale 指南之一（与 de.md、ja.md、zh-CN.md 等并列，见 SKILL.md 的 Locale-Specific Guidelines 表格）。它的核心职责是：

• 锁定既有译名：当 Operator、Pool 等术语在阿拉伯语 locale 文件中已有既定译法时，新字符串必须复用原词，而不是引入同义新词；
• 约束阿拉伯语特有的语言学规则：包括 CLDR 六类复数、仅使用西方阿拉伯数字（0-9）、禁止对英文 Airflow 术语附加阿语双数/复数词尾等；
• 优先于全局规则：SKILL.md 明确说明“若 locale 指南与全局规则冲突，遵循 locale 指南”。

推荐变体：文档指定使用现代标准阿拉伯语（MSA, Modern Standard Arabic），与 ar locale 目录 下现有译文保持一致。

1.1 ar 在 Airflow i18n 体系中的工程接入点

从源码结构看，ar 的“合法身份”由以下仓库文件共同背书：

接入点	文件	作用
前端语言清单	config.ts	supportedLanguages 数组中注册 { code: "ar", name: "العربية" }（第 28 行），UI 语言选择器与语言检测均基于此清单
翻译文件目录	locales/ar/	存放 10 个命名空间 JSON：admin.json、assets.json、browse.json、common.json、components.json、dag.json、dags.json、dashboard.json、hitl.json、tasks.json，与英语 en/ 目录一一对应
复数形式注册表	ui_commands.py	PLURAL_SUFFIXES["ar"] 声明阿拉伯语所需的 6 个复数后缀（第 76 行）
完整性检查文档	10_ui_tasks.rst	breeze ui check-translation-completeness 命令的官方用法说明

值得注意的一个细节：config.ts 中有一段关于 convertDetectedLanguage 的注释，解释了 i18next 解析 navigator.languages 时“区域码回退到基础语言”的匹配顺序问题——这正是像 ar 这类单码 locale（不像 zh-CN/zh-TW 带区域后缀）在语言检测中的典型场景：浏览器语言列表按序匹配时，ar 会直接命中清单中的精确码。

2. 术语体系：永不翻译词与标准译名表

2.1 全局永不翻译词（Arabic 与所有 locale 一致）

文档第 1 节列出以下术语在任何上下文中都不得翻译，它们与 SKILL.md 的 Terms Kept in English 表 一致：

• Airflow —— 产品名；
• Dag / Dags —— Airflow 概念，严禁写成 DAG（全大写是明确的 DON'T）；
• XCom / XComs —— 跨任务通信机制名；
• REST API、JSON、UTC；
• 日志级别：CRITICAL、ERROR、WARNING、INFO、DEBUG。

2.2 标准翻译对照表（Standard Translations）

文档第 2 节的完整对照表如下，这是新译名时的强制参照：

英文术语	阿拉伯语翻译	备注
Task	مهمة
Task Instance	مثيل المهمة
Task Group	مجموعة المهام
Dag Run	تشغيل Dag	保留英文 Dag
Pool	مجموعة الموارد
Provider	حُزمة	现有 UI 多为复数 حُزم
Operator	المشغّل	现有 UI 复数 المُشغِّلات
Scheduler	المُجَدْوِل	组件标签
Triggerer	المُطلِق	专指 triggerer，不用于泛指 trigger
Executor	منفذ	组件标签

文档特别强调一条治理原则：不要为尚未在阿拉伯语 locale 文件中出现过的术语补充词汇表条目。新术语出现时，应先检查邻近既有序列的译文，指南只收录有真实用法的词。

2.3 词表在真实 locale 文件中的印证

common.json 中的实际键值验证了上述词表并非纸面约定：

"allOperators": "جميع المُشغِّلات",     // Operator 复数
"taskInstance_one": "مثيل المهمة",        // Task Instance
"taskInstance.executor": "منفذ",          // Executor
"taskInstance.pool": "مجموعة الموارد",    // Pool
"nav.dags": "Dags",                        // Dags 保留英文
"dagId": "معرف Dag",                       // Dag 保留英文
"download.download": "تنزيل",              // 动作标签
"modal.save": "حفظ",                        // 动作标签
"delete": "حذف"                            // 动作标签

common.json 第 461-468 行 的 triggerer 对象（class、id、job、title 等键全部使用 المُطلِق 词形）也印证了 Triggerer → المُطلِق 的组件级约定；而 taskInstance.trigger（第 460 行）译为 المُحفِّز（触发器），恰好体现文档中“المُطلِق 专用于 triggerer 组件、不用于泛指 trigger”的区分。

dags.json 则展示了 Dag 保留英文时的混排连写风格：

"dagActions": {
  "delete": {
    "button": "حذف الDag",
    "warning": "سيؤدي هذا إلى إزالة جميع البيانات الوصفية المرتبطة بالDag، بما في ذلك التشغيلات والمهام."
  }
}

3. 阿拉伯语专属写作规则

3.1 语气与语域（Tone and Register）

• 使用中性、专业的 MSA，适合技术型 UI；
• 标签保持简洁；
• 优先复用 ar/*.json 中已有措辞，而非选用更文学化或教科书式的替代说法。

3.2 动作标签（Action Labels）

文档明确给出既有 UI 中使用的简洁动作标签样例：تشغيل（运行）、حذف（删除）、حفظ（保存）、تنزيل（下载）。不得为了新造标签而引入纯命令式形式如 شغّل、امسح，除非该确切上下文中现有 locale 已经在用。

从 common.json 可以看到这些标签的实际形态：delete: "حذف"、download.download: "تنزيل"、modal.save: "حفظ"，且快捷键提示统一采用“اضغط {{hotkey}} …”句式（如第 131 行 tooltip: "اضغط على {{hotkey}} لتنزيل السجلات"）。

3.3 阿英混排与占位符（Placeholders）

两条硬规则：

1. 嵌入的英文 Airflow 术语保持原始大小写：Dag、Dags、XCom，不得变形；
2. 占位符逐字保留：{{count}}、{{dagDisplayName}}、{{hotkey}} 等变量名不得翻译或删除，只能为自然语序调整位置（这与 SKILL.md 的 Variables and Placeholders 全局规则一致）。

现有 locale 中已确立的混排模式包括 معرف Dag（Dag ID）、تشغيل Dag（Dag Run）、{{count}} Dags。dags.json 第 2 行 的 "assetSchedule": "تم تحديث {{count}} من أصل {{total}}" 展示了两个占位符在同一句子中的自然排序——阿语“从…中更新…”的语序要求把 {{total}} 放到句尾。

3.4 六类复数（CLDR Arabic cardinal 规则）

这是阿拉伯语与其他 locale 差异最大的部分。Airflow 的 UI 工具链要求 ar 提供全部六个 i18next 复数后缀键：

后缀	适用数值（基数规则）
_zero	0
_one	1
_two	2
_few	3–10（mod 100）
_many	11–99（mod 100）
_other	其余情况

即使某些形式文本相同，也必须保留所有必需键。这条规则的工程实现就在 ui_commands.py 第 76 行：

PLURAL_SUFFIXES = {
    "ar": ["_zero", "_one", "_two", "_few", "_many", "_other"],
    "ja": ["_other"],
    "pl": ["_one", "_few", "_many", "_other"],
    ...
}

可以看到，ar 是表中唯一需要 6 种形式的语言（注释第 73 行也写道：“Arabic has 6 forms, Polish has 4 forms”）。breeze ui check-translation-completeness 正是用这份注册表来判定哪些复数键“缺失”、哪些“多余”：expand_plural_keys 函数 会将复数基名（如 dag）按目标语言的 suffix 集合展开，若英文侧任一形式含 {{count}} 或存在多个复数形式，则会强制要求该语言侧齐备。

文档给出了三段可直接复用的仓库既有模式：

"dag_zero": "لا يوجد أي Dag",
"dag_one": "Dag",
"dag_two": "2 Dags",
"dag_few": "Dags",
"dag_many": "Dags",
"dag_other": "Dags"

"pool_zero": "لا يوجد أي مجموعة",
"pool_one": "مجموعة",
"pool_two": "مجموعتان",
"pool_few": "مجموعات",
"pool_many": "مجموعة",
"pool_other": "مجموعة"

"warning_zero": "لا يوجد أي تحذير",
"warning_one": "1 تحذير",
"warning_two": "تحذيران",
"warning_few": "{{count}} تحذيرات",
"warning_many": "{{count}} تحذير",
"warning_other": "{{count}} تحذير"

其中 dag_* 六键在 common.json 第 55-60 行 中一字不差地存在，证明文档中的示例直接取自真实 locale，而非杜撰。注意 pool_*、task_*、taskGroup_*（common.json 第 428-442 行）等纯阿语词则使用了完整的形态变化（如 مهمتان/مجموعتا مهام），而 dag_* 保留英文词形不变。

关键规则：对保留英文的 Airflow 术语，直接使用英文词，不得强加阿语双数或复数词尾。正确写法是 2 Dags，而不是 Dagان 或 Dagين。

3.5 数字书写：仅西方阿拉伯数字

• 只允许 0 1 2 3 4 5 6 7 8 9；
• 禁止东方阿拉伯数字 ٠ ١ ٢ ٣ ٤ ٥ ٦ ٧ ٨ ٩。

common.json 第 279-282 行 的 timeRange 是这一规则的实例："last12Hours": "آخر 12 ساعة"、"last24Hours": "آخر 24 ساعة" 均使用西方数字。

4. 既有译文示例：从 locale 文件反查写法

文档第 4 节整理自当前 locale 的真实条目，可作为翻译时的“活词表”：

既定术语：

allOperators        -> "جميع المُشغِّلات"
taskInstance_one    -> "مثيل المهمة"
scheduler           -> "المُجَدْوِل"
triggerer           -> "المُطلِق"
executor            -> "منفذ"
Providers           -> "حُزم"

Dag 相关模式：

dagId               -> "معرف Dag"
triggerDag.title    -> "تشغيل Dag"
favoriteDags_zero   -> "لا توجد أي Dags مفضلة"

动作标签风格：

delete              -> "حذف"
download.download   -> "تنزيل"
modal.save          -> "حفظ"

对照 common.json 可以确认这些条目（如 allOperators 第 10 行、dagId 第 84 行）均真实存在；admin.json、dashboard.json 等其他命名空间文件则承载了 scheduler、triggerer、executor 等组件级标签。

5. 实操工作流：新增/更新 ar 翻译与验证

SKILL.md 定义了标准流程，阿拉伯语工作流与之完全一致，<locale> 取 ar。由于 airflow-core/src/airflow/ui/public/i18n/locales/ar/ 目录已存在，日常场景走“更新既有翻译”分支：

1. 先读本指南（即本文对应的 ar.md）建立词表与格式规则；

2. 通读现有 JSON：读 locales/ar/ 下的命名空间文件，学习在用术语，同词必须同译；

3. 检查覆盖度：

   breeze ui check-translation-completeness --language ar
   

   输出表应显示缺失/TODO/多余键数量与覆盖率；

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

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

5. 清除废弃键（英文 locale 已不需要的键，或本语言不需要的复数后缀）：

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

6. 翻译所有 TODO: translate: 条目，替换整行（含前缀）为译文，复数基名需一次写齐六个后缀；

7. 验证：再次运行 completeness 检查，目标输出为 0 missing / 0 TODOs / 0 unused / 100% coverage；然后运行 pre-commit 钩子修复格式与许可头：

   breeze ui check-translation-completeness --language ar
   prek run --from-ref main --hook-stage pre-commit
   

这些命令的完整参数语义见 dev/breeze/doc/10_ui_tasks.rst，其中明确提到该命令“支持语言特定复数形式（如波兰语 4 种、阿拉伯语 6 种），并可自动增删键”。

若是从零新增一个尚不存在的 locale，则还需先建目录、在 config.ts 的 supportedLanguages 注册语言、在 ui_commands.py 的 PLURAL_SUFFIXES 注册复数后缀（规则可对照 i18next 官方规则查询，ar 对应六后缀），并用 --add-missing 生成桩文件后再翻译——ar 已具备全部注册，通常无需走这条路径。

6. DO / DON'T 速查清单

DO（应当）：

• 与 ar/*.json 已有措辞保持一致；
• 保留 Dag、XCom 为英文原形；
• 使用适合软件 UI 的简洁 MSA；
• 复数键一次提供全部 6 个后缀；
• 仅使用西方阿拉伯数字；
• 示例一律取自现有 locale 文件，而非自造。

DON'T（禁止）：

• 写出 DAG（全大写）；
• 为当前 locale 未使用的术语凭空扩充大词表；
• 给 Dag 等英文 Airflow 术语附加阿语双数/复数词尾（如 Dagان）；
• 在无仓库证据的情况下，用教科书式译法替换既有 UI 措辞；
• 使用东方阿拉伯数字 ٠١٢٣…；
• 为每个阿语名词添加语法性别注释（增加噪声且无必要）；
• 不照抄 locale 真实条目而自造动作/状态示例。

7. 相关路径索引

资源	路径
阿拉伯语翻译指南（本文主体）	locales/ar.md
翻译技能总纲（全局规则、工作流、验证）	SKILL.md
阿拉伯语 locale 文件（10 个命名空间 JSON）	locales/ar/
前端语言注册（supportedLanguages）	config.ts
复数后缀注册表与完整性检查实现	ui_commands.py
breeze UI 任务官方文档	10_ui_tasks.rst

适用前提：本文规则基于当前仓库的 ar locale 文件与 CLDR 阿拉伯语基数复数规则（文档标注版本 1.0，2026 年 5 月）。若 Airflow 后续调整 UI 工具链（如复数后缀注册表或完整性检查命令），应以仓库当前版本为准。