Egg.js国际化完全指南：5个实用技巧打造多语言应用

2026-04-02 09:25:18作者：何将鹤

Egg.js作为基于Node.js和Koa的企业级框架，提供了完善的国际化解决方案，帮助开发者构建支持多语言的全球化应用。本文将系统介绍Egg.js国际化的核心概念、环境配置、实战应用及进阶技巧，通过5个实用技巧帮助你快速掌握企业级应用的国际化实践。

一、国际化概念解析：Egg.js多语言架构

什么是国际化

国际化（i18n）是指设计和开发应用时，使其能够轻松适应不同语言和地区的需求。在Egg.js中，这一功能主要通过官方提供的i18n插件实现，该插件位于项目的plugins/i18n/目录下。

Egg.js国际化核心机制

Egg.js i18n插件通过以下机制实现多语言支持：

语言检测：自动从URL参数、Cookie、请求头检测用户语言偏好
资源管理：加载并解析不同格式的语言资源文件
文本转换：提供模板函数实现动态文本翻译
持久化：通过Cookie存储用户语言偏好设置

图：Egg.js请求处理流程展示了国际化中间件在请求生命周期中的作用

二、环境搭建：从零开始配置国际化

1. 准备项目环境

操作目标：创建并初始化Egg.js项目
实现方法：

git clone https://gitcode.com/gh_mirrors/eg/egg
cd egg/examples/helloworld-typescript
npm install

预期效果：获取基础项目结构并安装依赖，为后续国际化配置做好准备。

2. 安装i18n插件

操作目标：添加i18n插件到项目依赖
实现方法：在项目package.json中添加依赖：

{
  "dependencies": {
    "egg-i18n": "^2.1.0"
  }
}

然后执行npm install安装插件。

预期效果：i18n插件被添加到项目依赖中，可在代码中引用相关功能。

3. 启用i18n插件

操作目标：在Egg.js中启用i18n插件
实现方法：在config/plugin.ts中添加配置：

// config/plugin.ts
export default {
  // 其他插件配置...
  i18n: {
    enable: true,
    package: 'egg-i18n',
  },
};

预期效果：Egg.js应用启动时会加载并初始化i18n插件。

三、核心功能：Egg.js国际化配置详解

基础配置策略

Egg.js i18n插件的核心配置文件位于plugins/i18n/src/config/config.default.ts，主要配置项包括：

// config/config.default.ts
export default {
  i18n: {
    defaultLocale: 'en_US',    // 默认语言，当未检测到语言时使用
    dirs: [ 'app/locales' ],   // 语言资源文件存放目录
    queryField: 'locale',      // URL参数名，用于通过URL切换语言
    cookieField: 'locale',     // Cookie键名，用于存储用户语言偏好
    cookieMaxAge: '1y',        // Cookie有效期，设置为1年
    localeAlias: {             // 语言别名映射，简化语言切换
      'zh': 'zh_CN',
      'en': 'en_US'
    }
  }
};

语言资源文件组织

操作目标：创建结构化的语言资源文件
实现方法：在项目中创建以下目录结构：

app/
└── locales/
    ├── en_US.json  // 英文语言包
    ├── zh_CN.json  // 中文语言包
    └── fr_FR.json  // 法语语言包

JSON格式示例（en_US.json）：

{
  "greeting": "Hello",
  "welcome": "Welcome to {name} application",
  "menu": {
    "home": "Home",
    "about": "About Us",
    "contact": "Contact"
  }
}

预期效果：建立清晰的语言资源文件结构，便于维护和扩展多语言支持。

四、实战应用：在项目中使用国际化功能

在控制器中使用

操作目标：在控制器中获取国际化文本
实现方法：使用ctx.__()方法：

// app/controller/home.ts
import { Controller } from 'egg';

export default class HomeController extends Controller {
  async index() {
    const { ctx } = this;
    // 获取带参数的国际化文本
    const welcomeMessage = ctx.__('welcome', { name: 'Egg.js' });
    
    ctx.body = {
      message: welcomeMessage,
      currentLocale: ctx.locale // 当前语言
    };
  }
}

预期效果：根据用户语言偏好，返回对应语言的欢迎消息。

在模板中使用

操作目标：在视图模板中展示国际化文本
实现方法：直接在模板中使用__()函数：

<!-- app/view/index.nj -->
<!DOCTYPE html>
<html>
<head>
  <title>{{ __('page.title') }}</title>
</head>
<body>
  <h1>{{ __('welcome', { name: 'Egg.js' }) }}</h1>
  <nav>
    <ul>
      <li><a href="/">{{ __('menu.home') }}</a></li>
      <li><a href="/about">{{ __('menu.about') }}</a></li>
      <li><a href="/contact">{{ __('menu.contact') }}</a></li>
    </ul>
  </nav>
</body>
</html>

预期效果：模板根据当前语言环境自动渲染对应语言的文本内容。

语言切换实现

操作目标：允许用户手动切换语言
实现方法：创建语言切换控制器：

// app/controller/locale.ts
import { Controller } from 'egg';

export default class LocaleController extends Controller {
  async switch() {
    const { ctx } = this;
    const { lang } = ctx.query;
    
    // 验证语言参数是否有效
    const validLocales = ['zh_CN', 'en_US', 'fr_FR'];
    if (validLocales.includes(lang)) {
      // 设置语言并持久化到Cookie
      ctx.i18n.setLocale(lang);
      ctx.body = {
        success: true,
        message: ctx.__('language.changed'),
        currentLocale: lang
      };
    } else {
      ctx.body = {
        success: false,
        message: ctx.__('language.invalid')
      };
    }
  }
}

在路由中添加：

// app/router.ts
router.get('/switch-language', controller.locale.switch);

预期效果：用户访问/switch-language?lang=zh_CN即可切换到中文语言，并通过Cookie记住偏好。

五、进阶技巧：优化国际化体验

1. 语言自动检测优化

操作目标：提高语言检测准确性
实现方法：扩展语言检测逻辑，优先使用用户显式选择的语言，其次使用Cookie，最后使用浏览器默认语言：

// app/middleware/locale.ts
export default () => {
  return async (ctx, next) => {
    // 先检查URL参数
    const queryLocale = ctx.query.locale;
    // 再检查Cookie
    const cookieLocale = ctx.cookies.get('locale');
    // 最后使用浏览器语言
    const headerLocale = ctx.get('Accept-Language')?.split(',')[0];
    
    // 设置检测到的语言
    if (queryLocale) {
      ctx.i18n.setLocale(queryLocale);
      // 更新Cookie
      ctx.cookies.set('locale', queryLocale, { maxAge: 365 * 24 * 3600 * 1000 });
    } else if (cookieLocale) {
      ctx.i18n.setLocale(cookieLocale);
    } else if (headerLocale) {
      ctx.i18n.setLocale(headerLocale);
    }
    
    await next();
  };
};

预期效果：提供更智能的语言检测体验，优先尊重用户显式选择。

2. 大型项目的语言资源管理

操作目标：优化大型项目的语言资源组织
实现方法：按模块拆分语言文件，实现按需加载：

app/
└── locales/
    ├── common/
    │   ├── en_US.json
    │   └── zh_CN.json
    ├── user/
    │   ├── en_US.json
    │   └── zh_CN.json
    └── order/
        ├── en_US.json
        └── zh_CN.json

在代码中指定模块加载：

// 加载user模块的语言资源
const userName = ctx.__('user.name', null, { module: 'user' });

预期效果：提高大型项目的语言资源管理效率，减少不必要的资源加载。

3. 性能优化策略

操作目标：提升国际化功能的性能
实现方法：

使用tegg/core/metadata/实现语言资源缓存
生产环境预编译语言文件
对高频访问的多语言内容进行内存缓存

// app/service/i18n.ts
import { Service } from 'egg';

export default class I18nService extends Service {
  private cache = new Map();
  
  async getMessage(key: string, locale: string = this.ctx.locale) {
    const cacheKey = `${locale}:${key}`;
    
    // 检查缓存
    if (this.cache.has(cacheKey)) {
      return this.cache.get(cacheKey);
    }
    
    // 从文件加载
    const message = this.ctx.__({ key, locale });
    
    // 缓存结果，设置10分钟过期
    this.cache.set(cacheKey, message);
    setTimeout(() => this.cache.delete(cacheKey), 10 * 60 * 1000);
    
    return message;
  }
}