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/localesfrontend/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: falseComposition API 模式、locale与fallbackLocale均为en_USloadLocale(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的键必须在同一次变更中同步到其他所有语言目录绝不允许某个键只有英文。完整规则清单如下en_US 是基准也是默认与回退语言未翻译的 key 最终会回退到en_US的文案fallbackLocale: en_US因此英文永远兜底UI 不会因缺失 key 而崩溃。所有 key 必须全语言同步新增、重命名、删除一个 key都要在全部 17 个非英语 locale 目录中同步操作。删除或重命名意味着每个语言都要跟着改。en_US 必须使用美式拼写如favorites、color、canceled英式拼写只允许出现在en_GB。这一点会反噬测试e2e 或单元测试中如果断言某个标签文本必须断言en_US的字符串否则测试与基准语言不一致。真正翻译而不是粘贴英文每个键都要翻译成对应语言的真实表达严禁把英文原文贴进非英语 locale。复用该语言中既有的术语——翻译「metadata」「provider」等词时先在同一个语言文件里搜索相邻 key看既有译法保持术语统一。复制英文值只是最后手段只有当确实找不到翻译时才允许用英文值占位并且必须标记出来留待回访补译。修改已有字符串同样算数只要改了en_US中的值就意味着要把这个 key 在其余所有语言中重新翻译一遍。编写时顺带满足排序约束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 locales 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.py3.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 空格缩进、保留 Unicodeensure_asciiFalse、文件末尾换行检查模式无参数下任何文件的当前内容与「排序后的规范序列化」不一致就会失败并列出所有不合规文件--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 为基准」规则能够真正落地、而不是停留在文档层面的关键。四、新增一种语言从建目录到开 PRSKILL.md 给出的新增语言流程很简洁但背后同样有源码约束在frontend/src/locales/下新建一个语言目录例如frontend/src/locales/it_IT/完整镜像en_US/的文件结构——有多少个.json命名空间文件就要建多少个同名文件缺任何一个都会被check_i18n_locales.py的Missing files报错逐一翻译每个文件中的每个 key遵循「真正翻译、术语复用」原则让文件通过排序校验check_i18n_sorted.py可加--fix对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 模板 / 组合式函数composables$t(...)模板中用$t(命名空间.键)直接取文案v1 普通工具函数utilsi18n.global.t(...)不能访问组件实例时走全局实例v2 库原语lib primitives禁止调用$t文本必须通过 props / slots 由上层传入仓库中的实际证据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 的值为真实翻译而非粘贴的英文复用该语言既有术语被修改的既有 keyen_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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/localesfrontend/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: falseComposition API 模式、locale与fallbackLocale均为en_USloadLocale(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的键必须在同一次变更中同步到其他所有语言目录绝不允许某个键只有英文。完整规则清单如下en_US 是基准也是默认与回退语言未翻译的 key 最终会回退到en_US的文案fallbackLocale: en_US因此英文永远兜底UI 不会因缺失 key 而崩溃。所有 key 必须全语言同步新增、重命名、删除一个 key都要在全部 17 个非英语 locale 目录中同步操作。删除或重命名意味着每个语言都要跟着改。en_US 必须使用美式拼写如favorites、color、canceled英式拼写只允许出现在en_GB。这一点会反噬测试e2e 或单元测试中如果断言某个标签文本必须断言en_US的字符串否则测试与基准语言不一致。真正翻译而不是粘贴英文每个键都要翻译成对应语言的真实表达严禁把英文原文贴进非英语 locale。复用该语言中既有的术语——翻译「metadata」「provider」等词时先在同一个语言文件里搜索相邻 key看既有译法保持术语统一。复制英文值只是最后手段只有当确实找不到翻译时才允许用英文值占位并且必须标记出来留待回访补译。修改已有字符串同样算数只要改了en_US中的值就意味着要把这个 key 在其余所有语言中重新翻译一遍。编写时顺带满足排序约束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 locales 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.py3.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 空格缩进、保留 Unicodeensure_asciiFalse、文件末尾换行检查模式无参数下任何文件的当前内容与「排序后的规范序列化」不一致就会失败并列出所有不合规文件--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 为基准」规则能够真正落地、而不是停留在文档层面的关键。四、新增一种语言从建目录到开 PRSKILL.md 给出的新增语言流程很简洁但背后同样有源码约束在frontend/src/locales/下新建一个语言目录例如frontend/src/locales/it_IT/完整镜像en_US/的文件结构——有多少个.json命名空间文件就要建多少个同名文件缺任何一个都会被check_i18n_locales.py的Missing files报错逐一翻译每个文件中的每个 key遵循「真正翻译、术语复用」原则让文件通过排序校验check_i18n_sorted.py可加--fix对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 模板 / 组合式函数composables$t(...)模板中用$t(命名空间.键)直接取文案v1 普通工具函数utilsi18n.global.t(...)不能访问组件实例时走全局实例v2 库原语lib primitives禁止调用$t文本必须通过 props / slots 由上层传入仓库中的实际证据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 的值为真实翻译而非粘贴的英文复用该语言既有术语被修改的既有 keyen_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
