AxonHub 前端国际化(i18n)开发规范实战:Key 管理、双语资源与货币格式化

原创2026-10-12 16:28:001,409 阅读
文章标签:AI 应用API网关LLM 网关后端前端

AxonHub 前端国际化(i18n)开发规范实战:Key 管理、双语资源与货币格式化

本文以 AxonHub 仓库内 .agent/rules/frontend-i18n.md 这份前端国际化规则为骨架,结合仓库内 i18n 初始化、locale 资源、语言切换与币种设置的源码实现,系统讲解在 AxonHub 前端(React + react-i18next)中如何正确新增翻译 Key、保持双语一致,以及如何用统一模式格式化多币种金额。读完你将掌握这套规则背后的完整实现链路,能够照规范安全地提交多语言改动。

一、规则文档在说什么

.agent/rules/frontend-i18n.md 是 AxonHub 为 AI Agent 与开发者制定的前端国际化约束,核心只有三条:

  1. 代码中新增的每一个 i18n key,必须同时加入 frontend/src/locales/en.json 与 frontend/src/locales/zh.json;
  2. 代码里使用的 key 与 locale 文件中的 key 必须完全一致(字符串逐字相同,不允许拼写差异或多余空白);
  3. 金额必须使用现有的 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)提供:

这套链路意味着:在"系统设置 → 通用设置"里切换币种后,所有遵循 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,再通过 GraphQL UPDATE_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 文案的标准流程

把规则翻译成可执行的步骤,一次合规的双语改动长这样:

  1. 定位模块:确认新文案属于哪个功能域(analytics / channels / models / requests / system / dashboard / currencies …),找到 frontend/src/locales/en/ 与 frontend/src/locales/zh-CN/ 下对应的同名 JSON;
  2. 双文件同步新增:在两个文件的同一层级加入逐字相同的扁平 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": "模型每日请求上限"
  1. 组件内引用:const { t } = useTranslation(); 后用 t('models.labels.dailyCapHint') 渲染,key 字符串与 locale 文件中的 key 必须完全一致(注意冒号、点号、大小写);
  2. 金额一律走 t('currencies.format', ...),不要另写格式化函数;小数位按场景定:精确成本明细用 minimumFractionDigits: 6,统计展示用 minimumFractionDigits: 2, maximumFractionDigits: 2;
  3. 自检:搜索确认新旧 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、金额随语言与币种正确本地化。

登录后查看全文
axonhub