Apache Airflow UI 日语本地化指南：ja 翻译 Agent Skill 的术语规范与 i18n 实现机制

本文解析 Apache Airflow 仓库中 .agents/skills/airflow-translations/locales/ja.md 定义的日语（ja）翻译 Agent Skill：它规定了哪些 Airflow 术语必须保持英文原文、标准日语术语对照表、任务/Dag 运行状态译名、敬语语气与“半角 1/4 空格”排版规则。读完本文，你将掌握 Airflow UI 日语界面字符串的一致性约定，并能结合 SKILL.md 与 breeze 翻译完整性检查命令 独立产出并通过校验的日语翻译文件。

1. 背景：ja.md 在 Airflow 翻译体系中的位置

Airflow 的 UI 国际化基于 i18next，各语言的翻译 JSON 文件位于 ja 语言包目录。每个语言目录下有 10 个命名空间文件：admin.json、assets.json、browse.json、common.json、components.json、dag.json、dags.json、dashboard.json、hitl.json、tasks.json，与英语默认语言包 en/ 一一对应。

SKILL.md 是整个翻译工作的总纲，它定义了完整流程：

1. 新建语言：创建 locales/<locale>/ 目录，并在 i18n 配置 的 supportedLanguages 数组、breeze 的 PLURAL_SUFFIXES 字典、.github/boring-cyborg.yml 的 PR 标签规则中登记该语言；
2. 脚手架生成：执行 breeze ui check-translation-completeness --language ja --add-missing，为每个英文键生成 TODO: translate: 占位条目；
3. 翻译：按对应语言的 locale guideline（日语即本篇的 ja.md）替换所有占位条目；
4. 校验：再次运行 breeze ui check-translation-completeness --language ja，输出表应显示 0 missing、0 TODOs、0 unused、100% 覆盖，然后运行 prek run --from-ref main --hook-stage pre-commit 修复格式问题。

对于已有语言（日语已存在），流程从“更新既有翻译”开始：先读 locale guideline 建立术语基线，再通读该语言现有 JSON 文件复用已有译法——“如果某个词已经被翻译为某种形式，就原样复用该翻译”——最后用完整性检查命令补齐缺失键（--add-missing）或清理未使用键（--remove-unused）。

ja.md 的目标即是为 AI 翻译 Agent 提供 locale 级规则，使新产出的日语字符串与既有 Airflow 日语翻译 100% 一致。该文件当前版本为 1.0（2026 年 3 月）。

2. 核心术语必须保留英文（大小写敏感）

ja.md 第 1 节列出了在日语界面中严禁翻译、必须保持英文原文的术语：

术语	说明
Dag / Dags	Airflow 核心概念；绝不写作 "DAG" 或 "ダグ"
XCom / XComs	任务间交叉通信机制
Asset / Assets	数据依赖（旧称 Dataset）
Plugin / Plugins
Pool / Pools
Provider / Providers
Run / Runs	独立使用时的执行（如 "All Runs"）
UTC、JSON、PID、ID、REST API	通用技术缩写
日志级别 CRITICAL、ERROR、WARNING、INFO、DEBUG

这与 SKILL.md 的全局规则（Terms Kept in English）一致：Dag/Dags 永远是小写 g 的 Dag，全大写 DAG 是明确禁止的写法。日语文件包中可以直接验证这些约定，例如 ja/common.json 中：

• "Connections": "接続" 而 "Providers": "Providers"——Connection 译为“接続”（见第 3 节术语表），Provider 则保留英文；
• "dagRun": "Dag 実行"、"dagId": "Dag ID"——Dag 与 ID 保留原文，并与英文词之间加半角空格。

3. 标准术语翻译对照表

ja.md 第 2 节给出必须遵循的标准译名（与英语术语对照，含备注）：

英语术语	日语翻译	备注
Task	タスク	标准片假名
Task Instance	タスクインスタンス
Task Group	タスクグループ
Dag Run	Dag 実行
Backfill	過去分の再実行
Trigger	トリガー
Scheduler	スケジューラ
Executor	エグゼキュータ
Connection	接続
Variable	変数
Audit Log	監査ログ
State	状態

对照现有语言包可以确认这些约定已被落实：common.json 中 "Pools": "プール"、"Variables": "変数"、"xcoms": "XComs"、"auditLog": "監査ログ"、"backfill_other": "過去分の再実行"；ja/dashboard.json 中出现 "runningDags": "実行中の Dag"，"queuedDags": "待機中の Dag"，均遵循“英文术语 + 半角空格 + 日语”的书写方式。

4. 任务/Dag 运行状态的固定译名

ja.md 第 3 节固定了 9 种运行状态的日语表达：

英语状态	日语翻译
running	実行中
failed	失敗した
success	成功
queued	待機中
scheduled	スケジュール済
skipped	スキップ済
deferred	延期済
removed	削除済
upstream_failed	上流が失敗しました

这 9 个译名在 ja/common.json 的任务状态与 Dag 运行状态两组键中逐字命中："deferred": "延期済"、"failed": "失敗した"、"queued": "待機中"、"removed": "削除済"、"scheduled": "スケジュール済"、"skipped": "スキップ済"、"success": "成功"、"running": "実行中"、"upstream_failed": "上流が失敗しました"。翻译新增状态相关字符串时，必须直接复用这些既有译法，避免同一状态出现两种说法。

5. 日语特有的书写规范

5.1 语气与语体（Tone and Register）

• 统一使用敬语体（“です/ます”体，Desu/Masu form）；
• 技术软件 UI 的语气应中性、专业；
• 按钮与 tooltip 的字符串保持简短。

这一语体约束体现在既有译文里，例如 ja/components.json 的提示串 "limitedList": "その他 +{{count}} 件"、ja/dags.json 中较长的说明文案以“～状態にあります。”等礼貌体结尾。

5.2 空格规则（1/4 规则）

在日文字符与英文/数字字符之间必须插入半角空格：

• 正确：10 個の Dag
• 错误：10個のDag

该规则在语言包中贯彻得非常严格，例如 ja/admin.json 的 "deleteConnection_other": "{{count}} 件的接続を削除" 实为 "{{count}} 件の接続を削除"（数字占位符与“件”、片假名“接続”之间均以半角空格分隔）、"deleteVariable_other": "{{count}} 件の変数を削除"；common.json 中 "dagRunId": "Dag 実行 ID"、"collapseAllExtra": "追加情報の JSON を閉じる" 同样是“英文词两侧留空格”的写法。

5.3 大小写

• 专有技术词首字母大写："Dag"、"Asset"、"XCom"；
• 与 ja 语言包（ja 目录下各 .json）中既有翻译的大小写保持一致。

5.4 日语的复数形式：只有 _other

这是日语与其他语言在 Airflow 翻译工具链中的关键差异。SKILL.md 指出 Airflow 使用 i18next 复数后缀（_one、_other，以及可选的 _zero、_two、_few、_many），而 breeze 命令 ui_commands.py 中的 PLURAL_SUFFIXES 字典明确了各语言需要的后缀：

PLURAL_SUFFIXES = {
    "ar": ["_zero", "_one", "_two", "_few", "_many", "_other"],
    # ...
    "ja": ["_other"],
    "ko": ["_other"],
    "th": ["_other"],
    "zh-CN": ["_other"],
    # ...
}

日语（"ja": ["_other"]，同韩语、泰语、中文）没有单复数变化，因此每个复数基键只需要提供 _other 一个后缀；阿拉伯语则多达 6 个形式，波兰语 4 个。expand_plural_keys 函数（ui_commands.py 起）会按语言后缀把复数基键展开为“必需的完整键集合”，并对照英文语言包判断哪些键缺失（missing）或多余（unused）。所以为日语补全翻译时，只需处理 _other 键即可通过校验。

6. UI 操作动词译名

ja.md 第 5 节固定了 8 个高频 UI 动作按钮的译名：

英语	日语
Add	追加
Delete	削除
Edit	編集
Save	保存
Reset	リセット
Cancel	キャンセル
Confirm	確認
Search	検索

语言包中可见对应实现：common.json 里 "cancel": "キャンセル"、"reset": "リセット"，删除/添加类动作散见 admin、components 等命名空间。翻译新按钮时直接查此表，不要另起译法（例如“取消”与“キャンセル”二选一、或把 Reset 译成“初期化”）。

7. Agent 操作清单：DO / DON'T

ja.md 第 6 节给出翻译执行者（人或 AI Agent）的红线与要求：

DO：

• 所有面向用户的标签一律使用礼貌体；
• 保留全部 i18next 占位符：{{count}}、{{dagId}} 等；
• 严格执行 1/4 空格规则。

DON'T：

• 不要翻译第 1 节中必须保留英文的术语；
• 不要使用俚语或非正式表达；
• 不要使用全大写的 "DAG"。

关于占位符，SKILL.md 的全局规则补充了细节：翻译串使用 i18next 的 {{variable}} 插值语法，{{…}} 内部的变量名绝不翻译、绝不移除；占位符位置可以按目标语言语序调整，但变量名的大小写必须原样保留（如 {{dagDisplayName}}）。日语语言包正是这样书写的：ja/assets.json 中 "materializeDescription": "上流の Dag {{dagId}} は正常にトリガーされました"，common.json 审计日志中 "description": "{{count}} {{resourceName}} が削除済。 キー: {{keys}}"——变量名 dagId、count、resourceName、keys 均保持英文原样。此外 SKILL.md 提醒：热键值（如 "hotkey": "e"）是字面按键绑定，除非 locale guideline 另有说明，否则不翻译。

8. 日语 UI 如何被加载：i18next 初始化机制

理解 ja 语言包的消费方式，有助于把握“为什么必须与既有译文一致”。Airflow UI 的 i18n 初始化在 config.ts 中完成，几个关键实现事实：

• supportedLanguages 数组包含 { code: "ja", name: "日本語" }（第 38 行），defaultLanguage 为 "en"，日语包因此以英语 en/ 为默认回退源；
• 语言检测顺序为 ["localStorage", "navigator", "htmlTag"]，即优先读取用户手动选择（localStorage 缓存），其次浏览器语言，最后 <html lang> 标签；
• convertDetectedLanguage（config.ts）用 Intl.Locale 规范化浏览器上报的 BCP-47 标签：精确匹配优先，其次把地区变体降级到基础语言（如 en-GB → en），对中文再按 script 区分 zh-CN/zh-TW。该逻辑保证浏览器语言为 ja-JP 时能正确收敛到 ja；
• 翻译文件按 ${basePath}/static/i18n/locales/{{lng}}/{{ns}}.json?v=<version> 的路径经 i18next-http-backend 拉取，?v= 参数以 Airflow 版本作为缓存破坏符，避免 CDN 返回旧版翻译包；
• fallbackLng: defaultLanguage 意味着日语包中缺键的条目会回退到英文，因此漏译不会导致界面空白，但会产生中英混排——这正是校验命令追求 100% 覆盖的原因。

9. 校验流程小结

按 ja.md 完成翻译后，SKILL.md 要求的验收步骤为：

1. 运行 breeze ui check-translation-completeness --language ja，输出表须为 0 missing / 0 TODOs / 0 unused / 100% 覆盖；
2. 运行 prek run --from-ref main --hook-stage pre-commit，由 pre-commit 钩子统一修复 JSON 格式、许可证头与 lint 问题；
3. 对照本文第 2、3、4、6 节与既有 ja/ 语言包逐词核验：英文保留词未被翻译、状态与动词译名零偏差、Dag 与片假名/数字之间的半角空格无遗漏、{{…}} 占位符变量名原样保留。

ja.md 与 SKILL.md 的关系是“全局规则 + locale 特化规则”：当 locale 指南与全局规则冲突时，以 locale 指南为准；而本文件的价值正在于把日语的语体、空格、术语、状态译名等细节固化成可被 AI Agent 稳定执行的检查清单，保证 Airflow UI 的日语界面在持续演进中保持术语一致性。