RomM 前端国际化（i18n）完全指南：多语言体系、CI 校验与新增语言实战

RomM 前端国际化（i18n）完全指南：多语言体系、CI 校验与新增语言实战

【免费下载链接】rommA beautiful, powerful, self-hosted ROM manager and player.项目地址: https://gitcode.com/GitHub_Trending/rom/romm

本文基于 RomM 仓库中的.claude/skills/frontend-i18n/SKILL.md规范文档，结合 前端 locale 源码 与 CI 工作流，完整讲解 RomM 前端（v1 与 v2 两代界面）的国际化体系：从「en_US 为准、全语言同步」的核心规则，到两大 Python 校验脚本的底层实现，再到如何为 RomM 新增一种语言。读完本文，你将能在不破坏 CI 的前提下，安全地添加、重命名、删除任何用户可见的翻译键，并为 RomM 贡献一门全新的语言。

RomM 是一个自托管的 ROM 管理与在线游玩平台，其前端界面覆盖 v1 经典 UI 与 v2 新版 UI 两套体系。无论哪一代界面，用户可见的字符串都绝不硬编码在组件里，而是统一存放于 frontend/src/locales 下的 locale JSON 文件，经由vue-i18n注入组件。为了让 18 种语言始终与英文基准保持一致，RomM 用 CI（.github/workflows/i18n.yml）在每次改动 locale 文件时强制跑两个 Python 校验脚本。本文从目录结构、核心规则、校验脚本、新增语言四个层面展开，并给出源码级的依据。

一、locale 目录结构与命名空间布局

RomM 前端的全部翻译文件按「语言 / 命名空间」两级组织，位于 frontend/src/locales：

frontend/src/locales/ ├── index.ts # vue-i18n 实例与动态加载逻辑 ├── check_i18n_locales.py # 语言一致性校验（CI 使用） ├── check_i18n_sorted.py # 键排序校验（CI 使用） ├── en_US/ # 基准语言（默认 + 回退） ├── en_GB/ ├── bg_BG/ ├── cs_CZ/ ├── de_DE/ ├── es_ES/ ├── fr_FR/ ├── hu_HU/ ├── it_IT/ ├── ja_JP/ ├── ko_KR/ ├── pl_PL/ ├── pt_BR/ ├── ro_RO/ ├── ru_RU/ ├── tr_TR/ ├── zh_CN/ └── zh_TW/

1.1 命名空间（Namespace）：按功能拆分的翻译文件

命名空间是「按功能特性拆分的文件」，例如 SKILL 中列举的collection、common、console、detail、emulator、gallery、home、library、login、navigation、patcher、platform、scan、settings、task。以当前仓库的 en_US 目录 实际内容为准，具体有：activity、collection、common、console、emptyStates、gallery、home、login、logs、patcher、platform、play、recommendations、rom、scan、settings、setup等 17 个命名空间文件。

这种拆分让每个功能模块的文案可以独立演进：例如 ROM 相关操作文案集中在rom.json，上传与通用 UI 文案集中在common.json，平台筛选文案在platform.json。组件内通过$t("命名空间.键名")引用，例如$t("common.edit")、$t("rom.metadata")（参见 RawMetadataPanel.vue）。

1.2 动态加载：glob 导入与按需分包

locales/index.ts 是 i18n 的装配入口，核心机制如下：

• 通过import.meta.glob("./*/**/*.json")一次性收集所有 locale 文件，并按「语言 → 命名空间 → 懒加载函数」建立索引（modulesByLocale）；
• 创建vue-i18n实例时设置legacy: false（Composition API 模式）、locale与fallbackLocale均为en_US；
• loadLocale(locale)将某个语言的所有命名空间并行加载并合并成一个 message bundle，注册进i18n.global.setLocaleMessage；加载结果按语言做 memoize，来回切换语言不会重复请求；
• 每个命名空间是独立的构建 chunk，因此首次渲染所需的语言包要异步就绪——localesReady这个 Promise 会预先加载en_US与本地存储中记录的语言（localStorage键为settings.locale），启动引导流程会await它，确保首次导航时路由标题能被正确翻译而不是把原始 key 写进浏览器标签页；
• 通过watch(i18n.global.locale, ...)监听语言切换事件，并在切换时按需加载对应语言包；
• 单个命名空间加载失败（如部署后旧 chunk 失效）不会阻塞整个应用：catch中只打印错误，缺失的 key 回退显示为 key 名。

此外，index.ts中还内置了捷克语（cs_CZ）的复数规则pluralRules——RomM 的文案大量使用 vue-i18n 的管道语法表达单复数，例如common.json中的"albums-n": "{n} album | {n} albums"、"platforms-n": "{n} platform | {n} platforms"、"upload-files-selected": "{count} file selected | {count} files selected"。复数规则参数choice的取值 0/1/2/3 分别对应捷克语的四种复数形态，这与 vue-i18n 的复数约定一一对应。

二、核心规则：en_US 为基准，全语言同步（CI 强制）

SKILL.md 用大篇幅强调一条铁律：en_US是唯一事实来源（source of truth），但任何加进en_US的键必须在同一次变更中同步到其他所有语言目录，绝不允许某个键只有英文。

完整规则清单如下：

1. en_US 是基准，也是默认与回退语言：未翻译的 key 最终会回退到en_US的文案（fallbackLocale: "en_US"），因此英文永远兜底，UI 不会因缺失 key 而崩溃。
2. 所有 key 必须全语言同步：新增、重命名、删除一个 key，都要在全部 17 个非英语 locale 目录中同步操作。删除或重命名意味着每个语言都要跟着改。
3. en_US 必须使用美式拼写：如favorites、color、canceled；英式拼写只允许出现在en_GB。这一点会反噬测试：e2e 或单元测试中如果断言某个标签文本，必须断言en_US的字符串，否则测试与基准语言不一致。
4. 真正翻译，而不是粘贴英文：每个键都要翻译成对应语言的真实表达，严禁把英文原文贴进非英语 locale。复用该语言中既有的术语——翻译「metadata」「provider」等词时，先在同一个语言文件里搜索相邻 key，看既有译法，保持术语统一。
5. 复制英文值只是最后手段：只有当确实找不到翻译时，才允许用英文值占位，并且必须标记出来留待回访补译。
6. 修改已有字符串同样算数：只要改了en_US中的值，就意味着要把这个 key 在其余所有语言中重新翻译一遍。
7. 编写时顺带满足排序约束：locale JSON 的键必须按字母序排列（下一节详述），新增键时要插入到正确位置。

2.1 为什么是 en_US 而不是其他语言

从 locales/index.ts 可以看到FALLBACK_LOCALE = "en_US"被同时用作初始locale与fallbackLocale。这意味着：应用启动默认显示英文；即便某个语言包缺失 key，也会静默回退到英文文案，用户不会看到裸的 key 名。en_US 由此成为所有翻译的锚点——所有校验脚本也都是以en_US为参照物，见下一节。

2.2 术语一致性：搜索相邻 key 再动手

SKILL.md 特别强调「Reuse each locale's established terms」。例如在翻译「metadata」「provider」这类高频词时，先在该语言文件中 grep 现有的相邻 key 看渲染结果，沿用既有译法，避免同一个词在不同文件里出现多种翻译。这正是命名空间拆分的价值：术语在一个语言内是全局一致的。

三、提交前验证：两个 Python 校验脚本

SKILL.md 要求在交付前运行两个脚本，它们都位于 frontend/src/locales，且仅依赖 Python 标准库（glob、json、os、sys、argparse），无需安装任何第三方包：

# 1. 语言一致性校验：对比所有非英语 locale 与 en_US python3 frontend/src/locales/check_i18n_locales.py # 2. 键排序校验：检查所有 locale JSON 是否按字母序排列（加 --fix 自动排序） python3 frontend/src/locales/check_i18n_sorted.py

3.1 check_i18n_locales.py：缺文件、缺键、多键都会失败

打开 check_i18n_locales.py 可以看到它的判定逻辑非常直接：

• 以en_US目录为基准，枚举其余所有语言目录（排除en_US自身）；
• 缺文件：如果某语言目录缺少en_US中存在的.json命名空间文件，报Missing files；
• 缺键：对双方都存在的同名文件，遍历en_US的每个 key，若目标语言缺失，报In ... missing keys；
• 多键：反过来遍历目标语言的 key，若en_US中没有，报In ..., extra keys（多余的 key 同样会导致 CI 失败，防止死代码与拼写错误的孤儿键）；
• 任何一类错误都会把has_errors置为True，最终sys.exit(1)让 CI 失败；全部通过则打印✅ All translations are complete!。

也就是说，它执行的是严格的双向集合对比：en_US的 key 集合必须是每个非英语 locale 的 key 集合的超集且完全相等，不允许缺、也不允许多。

3.2 check_i18n_sorted.py：键必须按字母序排序

check_i18n_sorted.py 保证所有 locale 文件键的有序性：

• sort_recursive递归地对每个 dict 的键按字母序排序（嵌套对象如settings.json也会被检查），list 保持原序，标量原样返回；
• 序列化格式刻意对齐 Prettier 的输出：2 空格缩进、保留 Unicode（ensure_ascii=False）、文件末尾换行；
• 检查模式（无参数）下，任何文件的当前内容与「排序后的规范序列化」不一致就会失败，并列出所有不合规文件；
• --fix模式会把不合规文件原地重写为排序后的内容，并打印修复清单。

因此，手工添加新键时，请直接插入到字母序正确的位置（或干脆运行--fix代劳），保持 diff 干净、便于 review。

3.3 CI 强制执行：.github/workflows/i18n.yml

这两个脚本并不是建议性的，而是被 .github/workflows/i18n.yml 挂到了 CI 上：

• 触发条件：pull_request且改动路径匹配frontend/src/locales/**/*.json——即任何 locale JSON 变更都会触发；
• 使用astral-sh/setup-uv安装 uv，然后uv python install准备 Python 环境；
• 因为两个脚本都是纯标准库实现，CI 注释明确说明「skip resolving the backend project」，直接uv run --no-project python frontend/src/locales/check_i18n_locales.py和uv run --no-project python frontend/src/locales/check_i18n_sorted.py分别执行；
• 两个 job 任一失败，PR 就会被拦下。

这意味着：任何把新键只加进en_US而不同步其他语言的 PR，根本无法合入 master。这也是「en_US 为基准」规则能够真正落地、而不是停留在文档层面的关键。

四、新增一种语言：从建目录到开 PR

SKILL.md 给出的新增语言流程很简洁，但背后同样有源码约束：

1. 在frontend/src/locales/下新建一个语言目录，例如frontend/src/locales/it_IT/；
2. 完整镜像en_US/的文件结构——有多少个.json命名空间文件，就要建多少个同名文件（缺任何一个都会被check_i18n_locales.py的Missing files报错）；
3. 逐一翻译每个文件中的每个 key，遵循「真正翻译、术语复用」原则；
4. 让文件通过排序校验（check_i18n_sorted.py，可加--fix）；
5. 对master分支开 PR（遵循 CONTRIBUTING.md 的贡献流程）。

SKILL.md 特别注明：这是唯一一种「预期会出现新 locale 目录」的 i18n 变更。除此之外，任何改动都不允许出现语言目录层面的增减——也就是说不存在「只给中文加一个键」的场景，新增 key 必须同时落在全部 18 个语言目录中。

新增语言后，目录会自动被 locales/index.ts 的import.meta.glob("./*/**/*.json")捕获，无需改动任何加载代码；语言选择器写入localStorage的settings.locale键，下次启动时该语言会被作为启动语言预加载。需要注意：如果新语言需要不同于默认的复数规则（如捷克语的 4 形态），还需要在index.ts的pluralRules中补充对应规则，否则复数文案会按 vue-i18n 的默认英语规则渲染。

五、v1 与 v2 的调用约定差异

SKILL.md 明确了三代代码路径下翻译 API 的使用边界，这也是 RomM 前端国际化最容易被踩的坑：

仓库中的实际证据：v1 组件大量使用$t，例如 RawMetadataPanel.vue 中的$t("rom.metadata")、$t("common.edit")、$t("common.save")；而 v2 侧的工具函数则走全局实例，例如 romArtwork.ts 中的i18n.global.t("rom.media-cover")、i18n.global.t("rom.media-title-screen")等一系列媒体类型标签。

这条约定的背后是架构考量：v2 的库原语是可在不同宿主中复用的 UI 原语，若它们直接依赖全局 i18n 实例，就会与宿主绑定、难以单独测试；把文本下沉为 props/slots，由使用方（通常是容器组件）负责注入翻译后的文本，保证了原语的可组合性与可测试性。因此，为 v2 新增组件时，文本应通过 props/slots 透传，而不是在组件内部调用$t。

六、实战检查清单

把 SKILL.md 的要点收敛成一份可对照的 checklist，供提交任何frontend/src/locales/**改动前自检：

• 新键已同时加入全部 18 个语言目录（含 en_GB 等全部非英语目录），未出现「只有英文」的键；
• en_US使用美式拼写（favorites/color/canceled），英式拼写只进en_GB；
• 非英语 locale 的值为真实翻译，而非粘贴的英文；复用该语言既有术语；
• 被修改的既有 key（en_US值变化）已在其他所有语言中重新翻译；
• 删除 / 重命名的 key 已在所有语言中同步删除 / 重命名；
• 键按字母序插入（或运行check_i18n_sorted.py --fix自动整理）；
• 本地跑通两个校验脚本：python3 frontend/src/locales/check_i18n_locales.pypython3 frontend/src/locales/check_i18n_sorted.py
• 若涉及 e2e / 单元测试中的文案断言，断言的是en_US字符串；
• v2 库原语未直接调用$t，文本经 props/slots 传入。

结语

RomM 的国际化体系是一套「文档规范 + 运行时装配 + CI 强制校验」三位一体的工程实践：en_US作为事实来源与回退语言，17 个非英语 locale 与其严格保持键集合一致；index.ts 负责动态加载与按需分包，两个纯标准库 Python 脚本负责在 CI 上拦截一切不同步、未排序的翻译改动。理解了这套机制后，无论是为现有 18 种语言增删改翻译键，还是为 RomM 带来第 19 种语言，你都能在第一次提交时就通过全部检查。

【免费下载链接】rommA beautiful, powerful, self-hosted ROM manager and player.项目地址: https://gitcode.com/GitHub_Trending/rom/romm