AxonHub 前端国际化(i18n)开发规范实战:Key 管理、双语资源与货币格式化
AxonHub 前端国际化(i18n)开发规范实战:Key 管理、双语资源与货币格式化
本文以 AxonHub 仓库内 .agent/rules/frontend-i18n.md 这份前端国际化规则为骨架,结合仓库内 i18n 初始化、locale 资源、语言切换与币种设置的源码实现,系统讲解在 AxonHub 前端(React + react-i18next)中如何正确新增翻译 Key、保持双语一致,以及如何用统一模式格式化多币种金额。读完你将掌握这套规则背后的完整实现链路,能够照规范安全地提交多语言改动。
一、规则文档在说什么
.agent/rules/frontend-i18n.md 是 AxonHub 为 AI Agent 与开发者制定的前端国际化约束,核心只有三条:
- 代码中新增的每一个 i18n key,必须同时加入
frontend/src/locales/en.json与frontend/src/locales/zh.json; - 代码里使用的 key 与 locale 文件中的 key 必须完全一致(字符串逐字相同,不允许拼写差异或多余空白);
- 金额必须使用现有的 i18n 格式化模式,禁止在组件里手写
toFixed、Intl.NumberFormat等各自为政的格式逻辑。
第三条给出的标准调用如下:
t('currencies.format', {
val: cost,
currency: settings?.currencyCode,
locale: i18n.language === 'zh' ? 'zh-CN' : 'en-US',
minimumFractionDigits: 6,
})
需要特别指出:规则文档写成时假设 locale 是 en.json / zh.json 两个单文件,而当前仓库的实际组织方式已经演进为按功能模块拆分目录:英文资源在 frontend/src/locales/en/,简体中文资源在 frontend/src/locales/zh-CN/,每个目录下按 analytics.json、channels.json、currencies.json、models.json、requests.json 等功能域分文件管理。因此落地这条规则时的真实动作是:在 frontend/src/locales/en/ 与 frontend/src/locales/zh-CN/ 下对应模块的 JSON 文件中同步新增同名 key。仓库还在 frontend/src/locales/flatten_i18n.js 提供了一个把嵌套 JSON 拍平成点号路径 key 的辅助脚本,说明这套目录结构是可维护、可批量规整的。
二、Key 资源是如何加载与合并的:i18n 初始化源码解读
要真正理解"key 必须双语一致",先看资源如何进入 i18next。frontend/src/lib/i18n.ts 是前端国际化的唯一初始化入口,其加载逻辑为:
const enModules = import.meta.glob('../locales/en/*.json', { eager: true }) as Record<string, unknown>;
const zhCNModules = import.meta.glob('../locales/zh-CN/*.json', { eager: true }) as Record<string, unknown>;
const enTranslation = mergeTranslations(...Object.values(enModules).map(getModuleDefaultExport));
const zhTranslation = mergeTranslations(...Object.values(zhCNModules).map(getModuleDefaultExport));
const resources = {
en: { translation: enTranslation },
zh: { translation: zhTranslation },
'zh-CN': { translation: zhTranslation },
};
要点拆解:
- 通过 Vite 的
import.meta.glob('../locales/en/*.json', { eager: true })一次性全量加载目录下所有 JSON,新文件无需手动注册即可自动合并进resources; mergeTranslations用Object.assign({}, ...translations)把多个模块文件浅合并为单一翻译表。这意味着扁平化点号 key(如currencies.format)是当前仓库的事实标准,同名顶层分组的 JSON 会被后者覆盖,所以拆分文件时应在currencies.json、requests.json等文件中保持各自独立命名空间,避免 key 冲突;zh与zh-CN两个语言代码共享同一份中文翻译表,因此切换语言时中文永远只有一份维护成本。
初始化配置中还声明了 fallbackLng: 'en'(缺 key 时回退英文)与 supportedLngs: ['en', 'zh', 'zh-CN'],并通过 i18next-browser-languagedetector 按 localStorage → navigator → htmlTag 的顺序探测语言,且 convertDetectedLanguage 会把任何 zh-* 归一为 zh。这一整套机制决定了:如果你只改了 zh-CN 目录而没有同步 en 目录,英文用户会直接看到 key 字符串或回退缺失文案——这正是规范第一条要防止的。
三、货币格式化:currencies.format 的完整实现与标准用法
规则第三条要求金额统一走 t('currencies.format', ...)。它的 key 定义在 frontend/src/locales/en/currencies.json 与 frontend/src/locales/zh-CN/currencies.json 中,两个文件的第一行完全一致:
"currencies.format": "{{val, currency}}",
{{val, currency}} 是 i18next 的插值 + 自定义 format 语法:val 是传入数值,currency 是传给 interpolation.format 的格式名。真正的格式化实现在 frontend/src/lib/i18n.ts:
interpolation: {
escapeValue: false, // React 已经默认转义了
format: (value, format, lng, options) => {
if (format === 'currency') {
return new Intl.NumberFormat(options?.locale || lng, {
style: 'currency',
currency: options?.currency || 'USD',
currencyDisplay: 'narrowSymbol',
minimumFractionDigits: options?.minimumFractionDigits,
maximumFractionDigits: options?.maximumFractionDigits,
}).format(value);
}
return value;
},
},
可以看到底层交给 Intl.NumberFormat:locale 决定数字分组与符号位置,currency 决定币种符号,currencyDisplay: 'narrowSymbol' 让 $、¥、€ 等窄符号优先(例如中文环境下显示 ¥ 而非 CNY),小数位由 minimumFractionDigits / maximumFractionDigits 控制。因此调用方传入的参数语义为:
| 参数 | 来源 | 作用 |
|---|---|---|
val |
待格式化的金额数值(如成本、配额估算) | 传给 Intl.NumberFormat.format |
currency |
generalSettings?.currencyCode,默认 'USD' |
币种代码,来自系统通用设置 |
locale |
由 i18n.language 映射:zh 系列 → zh-CN,否则 → en-US |
控制本地化数字与货币显示规则 |
minimumFractionDigits / maximumFractionDigits |
按业务精度需求传入 | 控制小数位数,如费用明细用 6,展示卡片用 2 |
3.1 真实组件中的三种典型用法
规则文档给出的 minimumFractionDigits: 6 只是其中一个场景,仓库内有十余处遵循同一模式的调用,按精度可分为三类:
(1)账单/成本高精度展示——6 位小数,如 frontend/src/components/quota-badges.tsx:
const formatClineCost = (units?: number, scale?: number) => {
if (units == null || !scale) return '';
return t('currencies.format', {
val: units / scale,
currency: 'USD',
locale: i18n.language === 'zh' ? 'zh-CN' : 'en-US',
minimumFractionDigits: 6,
});
};
(2)统计卡片/图表——2 位小数,如 frontend/src/features/analytics/components/overview-cards.tsx:
const currencyCode = generalSettings?.currencyCode || 'USD';
const locale = i18n.language.startsWith('zh') ? 'zh-CN' : 'en-US';
const formatCurrency = (val: number) =>
t('currencies.format', {
val,
currency: currencyCode,
locale,
minimumFractionDigits: 2,
maximumFractionDigits: 2,
});
(3)仅取币种符号做前缀——传 val: 0,如 frontend/src/components/model-price-editor.tsx 与 frontend/src/components/price-schedule-editor.tsx:
const currencyPrefix = currencyCode
? t('currencies.format', { val: 0, currency: currencyCode, locale: 'en-US' })
: '';
传入 0 时 Intl.NumberFormat 只渲染出币种符号(如 $、¥),可安全用作输入框前缀。
3.2 常见反模式
从源码调用方式可以反推出几条必须避免的写法:
- 不用
toFixed/ 模板字符串拼接,如`${cost.toFixed(6)} USD`——符号位置、千分位、负号方向都会随 locale 变化,硬拼接无法本地化; - 不在组件内各自
new Intl.NumberFormat(...)——尽管技术上可行,但会绕开currencies.format的单一实现,导致currencyDisplay、小数位策略在页面间漂移; - 不写死
'USD'——在通用设置支持用户配置币种的前提下(见下一节),硬编码币种会让整个仪表盘金额与用户预期不符。
四、币种从哪里来:通用设置与 currencyCode 的完整链路
settings?.currencyCode 并非凭空而来,它由系统通用设置(System General Settings)提供:
- 类型定义:
SystemGeneralSettings接口声明了currencyCode: string与timezone: string两个字段,见 frontend/src/features/system/data/system.ts; - 可配置币种清单:frontend/src/features/system/data/currencies.ts 导出了
currencyCodes数组(AED、CNY、EUR、USD 等 100+ 币种代码),并由CurrencyCode类型约束; - 设置表单:frontend/src/features/system/components/general-settings.tsx 中默认值
'USD',加载时回填settings.currencyCode,保存时把选择写回后端; - 读取侧:各页面通过
useGeneralSettings()获取设置,然后统一generalSettings?.currencyCode || 'USD'兜底(如 frontend/src/features/usage-statistics/index.tsx)。
这套链路意味着:在"系统设置 → 通用设置"里切换币种后,所有遵循 currencies.format 的页面会自动同步显示新币种。这也是规范第三条存在的根本原因——只有全部走同一 key,币种切换才能全局生效。
五、语言如何切换与持久化:双语一致性的运行时保障
除了在代码中补 key,语言偏好还涉及运行时切换。相关实现集中在 frontend/src/hooks/useLanguage.ts 与 frontend/src/components/language-switch.tsx:
- 语言开关提供
English/中文两个选项(code分别为'en'、'zh'),见 language-switch.tsx; changeLanguage先调用i18n.changeLanguage(language)立即刷新 UI,再通过 GraphQLUPDATE_ME_MUTATION把preferLanguage写入用户资料;失败时回滚语言并提示错误;- 用户登录后,frontend/src/features/auth/data/auth.ts 会读取
userLanguage并同步i18n.changeLanguage(userLanguage); - 未登录场景下,语言仍由
localStorage缓存的语言检测结果决定(见 frontend/src/lib/i18n.ts)。
从这里可以得出一个对开发者的实操提醒:新增中文文案时,zh-CN 目录下的翻译是运行时唯一生效的中文资源(zh 与 zh-CN 共享同一对象),所以双语一致性不只指"两份文件都要有 key",还意味着两份文件的内容都要同步更新,否则会出现"key 齐全但英文/中文文案滞后"的问题。
六、动手落地:给一个功能新增 i18n 文案的标准流程
把规则翻译成可执行的步骤,一次合规的双语改动长这样:
- 定位模块:确认新文案属于哪个功能域(analytics / channels / models / requests / system / dashboard / currencies …),找到
frontend/src/locales/en/与frontend/src/locales/zh-CN/下对应的同名 JSON; - 双文件同步新增:在两个文件的同一层级加入逐字相同的扁平 key,例如:
// frontend/src/locales/en/models.json
"models.labels.dailyCapHint": "Daily request cap per model"
// frontend/src/locales/zh-CN/models.json
"models.labels.dailyCapHint": "模型每日请求上限"
- 组件内引用:
const { t } = useTranslation();后用t('models.labels.dailyCapHint')渲染,key 字符串与 locale 文件中的 key 必须完全一致(注意冒号、点号、大小写); - 金额一律走
t('currencies.format', ...),不要另写格式化函数;小数位按场景定:精确成本明细用minimumFractionDigits: 6,统计展示用minimumFractionDigits: 2, maximumFractionDigits: 2; - 自检:搜索确认新旧 key 在
en/与zh-CN/两个目录中都存在;若涉及嵌套结构,可运行 frontend/src/locales/flatten_i18n.js 将 JSON 统一拍平成点号路径 key,保证合并加载时 key 不发生嵌套冲突。
七、总结
AxonHub 前端国际化规则虽短,却精准概括了三件工程要事:双语资源同步、key 字符串一致、金额统一走 i18n 格式化。结合源码可以看到,这些约束背后是 frontend/src/lib/i18n.ts 的全量合并加载、Intl.NumberFormat 的统一实现、currencies.json 的标准 key,以及 general-settings.tsx 驱动的全局币种配置。对任何改动前端文本的提交而言,遵循这份规范就能保证:中英文同步、无缺失 key、金额随语言与币种正确本地化。