国际化接入

概览

项目使用 next-intl（Next.js 官方推荐的国际化方案）实现多语言支持，当前内置两种语言：

翻译文件采用两层模型：共享翻译（所有应用共用）+ 应用级覆盖（某个应用需要特殊文案时使用）。更详细的分层策略说明请参阅 国际化策略。

翻译文件结构

• packages/i18n/translations/shared/ — 跨应用共用的 UI 文案，如按钮、导航、通用错误提示等。
• apps/01mvp-web/src/modules/i18n/translations/ — 仅在当前应用中使用的文案，如品牌词、业务术语。

新增语言

i18n: {
  enabled: true,
  locales: {
    en: { currency: "USD", label: "English" },
    zh: { currency: "CNY", label: "简体中文" },
    ja: { currency: "JPY", label: "日本語" }, // 新增
  },
  defaultLocale: "zh",
  defaultCurrency: "CNY",
  localeCookieName: "NEXT_LOCALE",
},

# 共享翻译
touch packages/i18n/translations/shared/ja.json

# 应用覆盖（按需）
touch apps/01mvp-web/src/modules/i18n/translations/ja.json

添加翻译文案

{
  "auth": {
    "login": {
      "title": "Sign In",
      "submit": "Continue"
    }
  }
}

import { useTranslations } from "next-intl";

export function LoginForm() {
  const t = useTranslations("auth.login");

  return (
    <div>
      <h1>{t("title")}</h1>
      <button>{t("submit")}</button>
    </div>
  );
}

cd apps/01mvp-web && pnpm i18n:analyze

翻译覆盖规则

当用户请求语言为 locale 时，最终翻译消息按以下顺序加载，后者覆盖前者：

1. 共享默认语言 — shared/{defaultLocale}.json（即 shared/zh.json）
2. 共享目标语言 — shared/{locale}.json（同名 key 覆盖上一步）
3. 应用默认语言 — app/{defaultLocale}.json（覆盖共享层的同名 key）
4. 应用目标语言 — app/{locale}.json（最高优先级）

对于非默认语言，如果目标语言缺少某个 key，系统会自动回退到默认语言的值。这意味着你只需要翻译有差异的 key。

在邮件模板中使用翻译

邮件模板的翻译 key 统一放在 mail 命名空间下。邮件发送时会自动加载对应 locale 的翻译：

// apps/01mvp-web/src/lib/mail/send.ts
import { getMessagesForLocale } from "@01mvp/i18n";

在邮件模板中通过 messages.mail.* 访问翻译内容。邮件翻译的 key 格式示例：

{
  "mail": {
    "common": {
      "useLink": "请使用以下链接：",
      "openLinkInBrowser": "或复制以下链接到浏览器中打开："
    },
    "magicLink": {
      "body": "您请求了一次魔法链接登录。",
      "login": "立即登录"
    }
  }
}

LocaleSwitch 组件

LocaleSwitch 是一个下拉菜单组件，位于 packages/ui-shared/src/LocaleSwitch.tsx，提供语言切换功能。

工作原理：

• 自动读取 config.i18n.locales 中定义的语言列表
• 使用 useLocale() hook 获取当前语言
• 切换时调用 onLocaleChange 回调（用于更新 locale cookie），然后刷新页面

放置位置：通常放在页面头部导航栏中。如果应用使用了 ConfigContext 提供配置，LocaleSwitch 会自动读取可用语言列表，无需额外传参。

import { LocaleSwitch } from "@01mvp/ui-shared";

export function Header() {
  return (
    <nav>
      {/* 其他导航内容 */}
      <LocaleSwitch />
    </nav>
  );
}

常见问题

相关资源

• 国际化策略（概念） — 分层模型与合并策略的详细说明
• @01mvp/i18n 参考 — 包的 API 与导出说明
• next-intl 官方文档