国际化语言

"我们的游戏评论区炸了！"创作团队 QQ 群传来急促的声音。

你打开玩家反馈面板，眼前一片飘红：

• 日本玩家山本："中国語が読めない！"（看不懂中文！）
• 英国玩家 Tom："Why is there no English version? I'm crying!"（为什么没有英文版？我要哭了！）
• 法国玩家 Luc："Où est la version française?"（法语版在哪里？）
• 德国玩家 Hans："Kann man die Sprache ändern?"（能改语言吗？）

作为创作者，你知道必须立刻解决这个语言障碍问题！ 这时，i18next 就是你的救星！它是一个强大的国际化框架，能帮你轻松实现多语言支持。

安装

npm install i18next

Info

建议将本地化配置置于客户端脚本中实现，而非直接集成在服务端脚本中。这种架构设计能够更好地满足不同用户的个性化需求，同时遵循了前端处理用户特定配置的最佳实践。

基础配置

// i18n.ts
import i18n from "i18next";

// 初始化配置
i18n.init({
  lng: "en", // 默认语言
  fallbackLng: "en", // 回退语言
  debug: false, // 生产环境应设为false
  resources: {
    en: {
      translation: {
        // 英文翻译
        welcome: "Welcome!",
        greeting: "Hello, {{name}}!",
        buttons: {
          submit: "Submit",
          cancel: "Cancel",
        },
      },
    },
    zh: {
      translation: {
        // 中文翻译
        welcome: "欢迎！",
        greeting: "你好，{{name}}！",
        buttons: {
          submit: "提交",
          cancel: "取消",
        },
      },
    },
  },
});

export default i18n;

核心 API 使用

1. 基本翻译

import i18n from "./i18n";

// 简单翻译
console.log(i18n.t("welcome")); // 输出: "Welcome!" 或 "欢迎！"

// 带插值
console.log(i18n.t("greeting", { name: "Alice" })); // "Hello, Alice!" 或 "你好，Alice！"

// 嵌套键
console.log(i18n.t("buttons.submit")); // "Submit" 或 "提交"

2. 语言切换

// 获取当前语言
console.log(i18n.language); // 输出当前语言代码

// 切换语言
i18n.changeLanguage("zh").then(() => {
  console.log("语言已切换至中文");
});

// 监听语言变化
i18n.on("languageChanged", (lng) => {
  console.log(`语言已变为: ${lng}`);
});

3. 复数处理

// 配置复数规则
i18n.init({
  // ...其他配置
  resources: {
    en: {
      translation: {
        itemCount: "{{count}} item",
        itemCount_plural: "{{count}} items",
      },
    },
    zh: {
      translation: {
        itemCount: "{{count}} 个项目",
      },
    },
  },
});

// 使用
console.log(i18n.t("itemCount", { count: 1 })); // "1 item" 或 "1 个项目"
console.log(i18n.t("itemCount", { count: 5 })); // "5 items" 或 "5 个项目"

多语言配置文件

MyGame/
├── i18n/
│   ├── config.ts                # i18n 初始化配置文件
│   └── locales/                 # 多语言资源目录
│       ├── en/                  # 英文语言包
│       │   ├── common.json      # 通用翻译
│       │   └── home.json        # 首页相关翻译
│       └── zh/                  # 中文语言包
│           ├── common.json      # 通用翻译
│           └── home.json        # 首页相关翻译

1. 创建 JSON 翻译文件

英文翻译文件示例 (en/common.json)

{
  "welcome": "Welcome to our application!",
  "greeting": "Hello, {{name}}!",
  "buttons": {
    "submit": "Submit",
    "cancel": "Cancel"
  },
  "itemCount": "{{count}} item",
  "itemCount_plural": "{{count}} items"
}

中文翻译文件示例 (zh/common.json)

{
  "welcome": "欢迎使用我们的应用！",
  "greeting": "你好，{{name}}！",
  "buttons": {
    "submit": "提交",
    "cancel": "取消"
  },
  "itemCount": "{{count}} 个项目"
}

zh/home.json和en/home.json 文件类似，这里不再展示。

2. 加载 JSON 配置

创建 i18n/config.ts 配置文件：

import i18n from "i18next";
import zhCNcommon from "./locales/common.json";
import enCommon from "./locales/common.json";

import zhCNhome from "./locales/home.json";
import enHome from "./locales/home.json";

i18n.init({
  lng: "en", // 默认语言设置为英文
  fallbackLng: "en", // 回退语言也是英文
  supportedLngs: ["en", "zh-CN"], // 支持的语言列表
  resources: {
    // 翻译资源
    en: {
      // 英文资源
      translation: enHome, // 默认命名空间的翻译
      common: enCommon, // 'common'命名空间的翻译
    },
    "zh-CN": {
      // 简体中文资源
      translation: zhCNhome, // 默认命名空间的翻译
      common: zhCNcommon, // 'common'命名空间的翻译
    },
  },
});

export default i18n;

使用方式

console.log(i18n.t("welcome")); // 输出默认命名空间的 welcome
console.log(i18n.t("common:welcome")); // 输出 common 命名空间的 welcome

TypeScript 类型支持

创建 i18n.d.ts 文件增强类型：

// i18n.d.ts
import "i18next";
import enTranslation from "../locales/en/home.json";
import enCommon from "../locales/en/common.json";
// ...其他导入

declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: "translation";
    resources: {
      translation: typeof enTranslation;
      common: typeof enCommon;
    };
  }
}

总结

使用纯 i18next 包在 TypeScript 客户端中的优势：

1. 轻量级：不依赖其他框架
2. 强大功能：支持复数、插值、上下文等高级特性
3. 类型安全：完整的 TypeScript 支持
4. 灵活扩展：可按需添加插件

使用 JSON 配置 i18next 的优势：

1. 关注点分离：翻译文本与代码逻辑分离
2. 易于维护：非技术人员也可以编辑翻译文件
3. 版本控制友好：JSON 文件易于版本管理和协作

通过这种配置方式，你可以轻松管理大型应用的国际化需求，同时保持代码的整洁和可维护性。