企业官网建设流程全解析

• 前端
• 后端
• 云原生

导读

本文以仓库中 modules/web/i18n/ja/README.md 为核心骨架，系统介绍 Kubernetes Dashboard 日语（ja）国际化团队的职责划分、翻译规范、XLIFF 文件操作流程、原文修正方法以及团队协作与沟通机制，并结合 modules/web/i18n/ja/messages.ja.xlf、modules/web/i18n/locale_conf.json、modules/web/src/index.config.ts 等源码与配置文件，从 Angular i18n 底层机制上印证整套翻译工作流的实现原理。读完本文，你将能够独立完成一份合规的日语翻译 Pull Request、正确使用yarn fix:i18n与npm run fix更新翻译文件，并理解 Dashboard 国际化管线的完整链路。

一、背景：Dashboard 的多语言架构与日语团队定位

Kubernetes Dashboard 是基于 Angular 构建的通用型 Kubernetes 集群 Web UI。它通过浏览器发送的 HTTPAccept-Language头来确定界面语言，目前支持 9 种语言，见 docs/common/internationalization.md：

所有翻译数据统一存放在modules/web/i18n/目录下，包含三部分：

• 配置：modules/web/i18n/locale_conf.json，其内容为{"translations": [ "de", "en", "es", "fr", "ja", "ko", "zh-Hans", "zh-Hant", "zh-Hant-HK" ]}，按字母序登记全部语言；
• 原文词典：modules/web/i18n/messages.xlf（约 1972 行<trans-unit>），只含<source>元素；
• 各语言翻译文件：如modules/web/i18n/ja/messages.ja.xlf（约 2661 行），每个<trans-unit>同时含<source>与<target>元素。

日语团队（Kubernetes Dashboard Japanese i18n Team）由modules/web/i18n/ja/OWNERS文件管理，当前 approvers 为 shu-mutou、atoato88，reviewers 为 ziyi-xie，并挂有language/ja标签。该团队独立管理i18n/ja/目录下的资源，其成员同时出现在仓库根目录 OWNERS_ALIASES 的sig-ui-leads、dashboard-maintainers组中，体现了 Dashboard 官方把"翻译文件审核权"下放给各语言社区的一贯模式（参见 docs/common/internationalization.md 中"Introducing new language"一节）。

翻译团队的四类贡献

日语团队将贡献划分为四类，这一划分实际上与国际化管线的各个环节一一对应：

1. 和訳への貢献（翻译贡献）：编辑modules/web/i18n/ja/messages.ja.xlf并提交 Pull Request，或参与评审——对应"翻译"环节；
2. 原文修正（源文修正）：发现英文原文有误、需要修改 html 模板时，向kubernetes/dashboard仓库提出修正——对应"源文"环节；
3. 翻訳関連ツールへの貢献（翻译工具贡献）：当新增页面或修正源文时，由 Angular i18n 相关工具自动更新messages.xlf与messages.ja.xlf，改进这些工具与工作流——对应"工具链"环节；
4. その他の貢献（其他贡献）：团队治理（governance）、与上游仓库的协调等。

二、日语翻译规范全解（可与仓库证据对照）

日语团队在长期实践中沉淀了一套相当细致的翻译规范，其总原则是"大致参照云厂商 Web UI 与文档的译法"。以下规范并非凭空约定，而是可以从翻译文件中逐一找到对应实例。

2.1 用词与语体

• 用词统一性优先；
• 正文基本使用"ですます"调（敬体），但术语表使用"である"调（简体）；
• 翻译策略优先级：广泛使用的术语 > 尽可能日语化（汉字、平假名）> 片假名 > 保留英文（如不可翻译的专有名词、外部站点引文）。

2.2 片假名长音规则

外来语片假名原则上必须加长音符（ー），且不设例外（原文强调"混乱の元なので例外は作りません"）：

• -er/or系：アーキテクチャー、ユーザー、セレクター
• -y系：セキュリティー、バイナリー、ユーティリティー
• 词中同样使用长音：インターフェース

这一点可以在翻译文件中得到印证：Parameter → パラメーター（modules/web/i18n/ja/messages.ja.xlf中 id 为 1183601349925746054 的条目）、Logs from → ログ、Ingresses → イングレス、Daemon Sets → デーモンセット等均遵循长音标注。

2.3 标点与排版

• 句读点使用「、。」，不使用「，．」；
• 句中的「?」「!」译为全角「？」「！」；纯装饰用途则保留半角；
• 不使用中黒（・）：如 カスタムスクリプト（而非 カスタム・スクリプト）；
• 英文字母一律半角；
• 数字使用半角阿拉伯数字（成语类如"一部""一方""四捨五入"除外）；
• 冒号（:）、斜杠（/）、连字符（-）及括号一律半角；强调/引用用的双引号" "原则上替换为「」；
• 英数字与日语之间插入半角空格，但句首、句读点紧邻处不插。

2.4 假名与表记细节

• 「～ください」类表述统一为「○○を下さい」「○○してください」，不用「押下ください」这类生硬说法；
• 「〜なし」「〜のため」「〜すること」一律用平假名，避免「〜無し」「〜の為」「〜する事」。

2.5 Dashboard 界面特有约束

• 布局优先：译文不得破坏 UI 布局。若译文过长导致左侧菜单浪费空间或表格列过宽，需重新斟酌用词甚至使用省略语。典型例子：カスタムリソースデフィニション 缩略为 カスタムリソース定義；
• 保留变量与标签：原文含变量（插值）或标签时，必须在译文<target>中整体移动对应<x .../>标签，不可拆散。README 给出了删除确认对话框的完整示例：英文源文将 3 个INTERPOLATION插值标签按顺序排列，日文译文则重排为「ネームスペース {namespace} の {displayName} {name} を本当に削除しますか？」，标签整体搬迁；
• 体言止め动词的处置：面向终端用户的说明/对话框（如 "Confirm"）译为句子（「確認してください」）；作为按钮/菜单动作时译为体言止め（「確認」）。

三、XLIFF 翻译文件的结构与"未翻译标记"机制

翻译工作直接操作的是 XLIFF 1.2 格式文件modules/web/i18n/ja/messages.ja.xlf。其基本单元是<trans-unit>，结构如下（摘自该文件实际内容）：

<trans-unit id="1000282742611934867" datatype="html"> <source>Create from file</source> <target>ファイルから作成</target> </trans-unit>

• <source>：英文原文（对应modules/web/i18n/messages.xlf中的条目，id 完全一致）；
• <target>：日语译文；
• state="new"：未翻译标记。当xliffmerge从源文词典复制新条目到语言文件时，会自动生成空<target>并带上state="new"属性。翻译完成后必须删除该属性，作为"已翻译"的标记。

仓库当前文件中也存在大量state="new"的待翻译条目，例如：

<trans-unit id="8432216995899653457" datatype="html"> <source> Resource Information </source> <target state="new">リソース情報</target> </trans-unit>

这正说明该文件是"进行时"的活文档：随着上游新增页面（如 Ingress Class Name、Endpoints、Mount Option(s)、Read Only Filesystem 等新字段），xliffmerge会不断把新条目复制进来并标记为state="new"，等待日语团队成员翻译并移除标记。任何翻译 PR 都应检查并清理这类标记。

四、翻译贡献的完整操作流程

4.1 环境准备与工具链

1. 参考 DEVELOPMENT.md 的 Getting started 章节搭建运行/验证环境；
2. 通读 docs/common/internationalization.md 确认翻译方法；
3. 编辑modules/web/i18n/ja/messages.ja.xlf的<target>内容，并删除已翻译条目的state="new"属性。

4.2 本地验证：kind 集群 + 开发容器

README 推荐的验证路径是：使用 Dashboard 开发环境容器配合 kind 构建本地 Kubernetes 集群，然后构建并启动 Dashboard：

hack/develop/run-dev-container.sh

该脚本（hack/develop/run-dev-container.sh）会拉起 hack/develop/Dockerfile 定义的开发容器，容器内通过 hack/develop/run-command.sh 与 hack/develop/gosu-command.sh 以非 root 用户执行命令。集群准备可参考 hack/scripts/start-cluster.sh 与 hack/include/kind.mk（kind 集群配置见 hack/include/kind.config.yml）。

启动后通过浏览器访问https://localhost:4443检查翻译效果——注意这是HTTPS端点。

4.3 提交与后续跟踪

• 向kubernetes/dashboard仓库提交 Pull Request；
• 通过监控带有language/ja标签的 Pull Request 来跟进是否有新的待翻译原文。

4.4 与国际化管线的衔接

需要说明的是：开发环境（npm start）不会编译本地化版本，只有执行npm run build或npm run start:prod才会构建本地化产物（见 docs/common/internationalization.md 的 Building localized dashboard 一节）。因此验证日语界面时，务必使用构建命令，而不是普通 dev server。

五、原文修正（source fix）流程

当英文原文存在错误、需要修改 html 模板时，走"原文修正"路线：

1. 定位源文：modules/web/i18n/ja/messages.ja.xlf中每个<trans-unit>的<context context-type="sourcefile">标签记录了源文件位置，修正对象是 modules/web 下的 Angular html 模板文件；

2. 修改模板并验证布局：修改原文后需构建、启动并在浏览器中确认——不仅日语译文显示正常，英文原文显示下布局也不得破坏；

3. 同步更新词典与语言文件：在按 DEVELOPMENT.md 搭建的环境中，git commit时会自动触发更新modules/web/i18n/messages.xlf与各语言文件；也可以手动执行npm run fix显式刷新。npm run fix在 modules/web/package.json 中定义为yarn fix:i18n && yarn fix:html && yarn fix:scss && yarn fix:ts，其中fix:i18n执行ng run kubernetes-dashboard:extract-i18n-merge（即 xliffmerge），它会：

   • 从带i18n属性的 Angular 模板中提取可翻译文本；
   • 更新i18n/messages.xlf原文词典；
   • 把新增条目复制进i18n/[locale]/messages.[locale].xlf并标记state="new"。

4. 提交内容完整性：PR 中必须同时包含修改后的 html 文件、messages.xlf以及各语言文件，不能只提交 html。

六、从源码印证：一条翻译如何变成界面语言

日语团队的翻译最终能否生效，取决于整个国际化管线的配置，以下仓库文件共同构成这条链路：

1. modules/web/angular.json（L10-L48）：i18n.sourceLocale.code为en，i18n.locales中登记了全部 8 个目标语言，其中ja的配置为：

"ja": { "translation": "i18n/ja/messages.ja.xlf", "baseHref": "" }

2. modules/web/src/index.config.ts（L19-L56）：前端声明支持语言列表supportedLanguages，日语条目为{ label: 'Japanese', value: 'ja' }；同时defaultLanguage: 'en'、languageCookieName: 'lang'定义了默认语言与语言 Cookie 名；
3. modules/web/i18n/locale_conf.json：{"translations": [ "de", "en", "es", "fr", "ja", "ko", "zh-Hans", "zh-Hant", "zh-Hant-HK" ]}控制make build产物中包含哪些语言版本。

也就是说：**语言文件（messages.ja.xlf）→ 构建配置（angular.json）→ 运行时语言表（index.config.ts）→ 构建产物（locale_conf.json）**四者缺一不可。日语团队修改翻译文件后，正是通过这条管线将译文编译进日语版本的 Dashboard 中。若未来要新增一种语言，按 docs/common/internationalization.md 的"Introducing new language"一节，需在以上四处逐一登记，并为本语言目录添加 OWNERS 文件（含labels: - language/[locale]，便于跟踪带该标签的 PR）。

七、翻译工具与团队治理

7.1 协作工具的选型标准

日语团队正在寻找适合团队规模的协作翻译工具，其筛选标准相当具体，可作为评估任何 i18n 协作平台的需求清单：

• 支持 XLIFF 格式文件；
• 提供 WebUI、支持多人协同编辑；
• 可显示/编辑原文中的变量占位 html 标签（因为<x .../>插值标签必须整体移动，不能损坏）；
• 适合 Kubernetes Dashboard 乃至 Kubernetes 社区规模使用。

7.2 团队治理与其他贡献

• 持续改进翻译方针、整备翻译术语表；
• 团队目录下的资源更新由modules/web/i18n/ja/OWNERS中的成员（以及根目录OWNERS_ALIASES中的相关组）批准，日常管理基本由 OWNERS 成员自治完成。

八、沟通与 Issue 规范

• 讨论通过 GitHub Issue 进行；目前没有日语团队专属 Slack 频道或邮件列表，但 OWNERS 中列出的贡献者可在 Kubernetes Slack 工作区的#sig-ui频道找到；
• Issue 标题必须用英语书写（例如：Which translation is appropriate for "Container", "コンテナ" or "コンテナー" ?）；
• 属于团队内部讨论事项（如译法争议）的 Issue 加language/ja标签，可用日语讨论；
• 涉及原文修正、工具改进等需要上游仓库成员参与的事项不加标签，且必须用英语讨论（因为上游成员也会参与）。

九、实操速查：一次合规的日语翻译贡献 Checklist

1. 搭建环境：按 DEVELOPMENT.md 完成开发环境，用hack/develop/run-dev-container.sh启动开发容器并准备 kind 集群；
2. 打开modules/web/i18n/ja/messages.ja.xlf，按第二节的翻译规范填写/修正<target>内容；
3. 删除已翻译条目的state="new"属性（这是"已翻译"的官方标记机制）；
4. 变量与标签整体移动，切勿拆散<x .../>插值节点；
5. 执行npm run build（或npm run start:prod）构建本地化版本（dev server 不编译本地化）；
6. 浏览器访问https://localhost:4443验证日语界面与布局；
7. 修改原文时，同步更新 html 模板与messages.xlf、各语言文件（可用npm run fix显式刷新）；
8. 提交包含翻译文件（必要时含 html 与词典文件）的 PR，Issue 标题用英文，团队内部争议加language/ja标签。

十、参考资源

• 日语团队章程：modules/web/i18n/ja/README.md
• 日语翻译文件：modules/web/i18n/ja/messages.ja.xlf
• 原文词典：modules/web/i18n/messages.xlf
• 语言配置：modules/web/i18n/locale_conf.json
• 国际化总览：docs/common/internationalization.md
• 语言表与默认语言：modules/web/src/index.config.ts
• 构建语言配置：modules/web/angular.json
• i18n 相关脚本：modules/web/package.json
• 开发环境容器：hack/develop/run-dev-container.sh、hack/develop/Dockerfile
• 开发指南：DEVELOPMENT.md

• 前端
• 后端
• 云原生