如何基于Node.js+Express实现网站国际化(i18n)？

1. 安装依赖 #

用i18n这个成熟的npm包实现核心功能，搭配express-session存储用户语言偏好（也可选择cookie存储，按需调整）：

npm install i18n express-session

2. 基础配置（app.js） #

在Express入口文件中完成i18n的集成配置：

const express = require('express');
const session = require('express-session');
const i18n = require('i18n');
const app = express();

// 配置session，用于持久化用户语言选择
app.use(session({
  secret: 'your-custom-secret-key',
  resave: false,
  saveUninitialized: true,
  cookie: { secure: false } // 生产环境建议开启HTTPS并设为true
}));

// 配置i18n核心参数
i18n.configure({
  locales: ['en', 'zh'], // 支持的语言列表
  defaultLocale: 'en', // 默认 fallback 语言
  directory: __dirname + '/locales', // 翻译文件存放目录
  cookie: 'locale', // 可选：用cookie存储语言偏好
  queryParameter: 'lang', // 可选：支持URL参数切换，如?lang=zh
  autoReload: true, // 开发环境自动加载修改后的翻译文件
  updateFiles: false // 禁止自动创建缺失翻译条目，避免误操作
});

// 将i18n挂载到Express中间件链
app.use(i18n.init);

3. 处理翻译内容 #

在项目根目录创建locales文件夹，为每种语言单独创建JSON翻译文件：

locales/en.json #

{
  "welcome": "Welcome to our website",
  "switch_lang": "Switch Language",
  "greeting": "Hello, {{name}}!",
  "article_count": "You have {{count}} article",
  "article_count_plural": "You have {{count}} articles"
}

locales/zh.json #

{
  "welcome": "欢迎来到我们的网站",
  "switch_lang": "切换语言",
  "greeting": "你好，{{name}}！",
  "article_count": "你有 {{count}} 篇文章",
  "article_count_plural": "你有 {{count}} 篇文章"
}

注：复数规则可根据语言特性调整，示例保留统一结构方便维护。

4. 在路由和视图中调用翻译 #

路由中使用 #

app.get('/', (req, res) => {
  // 基础翻译调用
  const welcomeText = req.__('welcome');
  // 带占位符的翻译
  const greeting = req.__('greeting', { name: 'Guest' });
  // 复数场景处理
  const articleText = req.__n('article_count', 5);

  res.render('index', { welcomeText, greeting, articleText });
});

EJS视图中使用（以EJS模板为例） #

<h1><%= __('welcome') %></h1>
<p><%= __('greeting', { name: 'Visitor' }) %></p>
<p><%= __n('article_count', 3) %></p>
<a href="/lang/en">English</a> | <a href="/lang/zh">中文</a>

5. 动态切换语言 #

添加路由处理语言切换请求，将用户选择存入session或cookie：

app.get('/lang/:locale', (req, res) => {
  const { locale } = req.params;
  // 验证语言是否在支持列表内
  if (['en', 'zh'].includes(locale)) {
    req.session.locale = locale; // 存入session持久化
    res.cookie('locale', locale, { maxAge: 900000 }); // 可选：存入cookie，有效期15分钟
  }
  // 重定向回原页面，无来源则返回首页
  res.redirect(req.get('referer') || '/');
});

也可直接通过URL参数切换，如/?lang=zh，因配置了queryParameter: 'lang'，i18n会自动识别并切换。

6. 最佳实践与技巧 #

• 默认语言兜底：将defaultLocale设为用户最常用的语言，避免出现未翻译文本。
• 禁止硬编码：所有前端展示文本必须放入翻译文件，禁止直接写在代码或视图中。
• 拆分命名空间：大型项目可按模块拆分翻译文件，如locales/en/user.json，配置时开启objectNotation: true即可支持。
• 统一占位符格式：使用{{变量名}}格式，便于批量替换和维护。
• 生产环境优化：关闭autoReload减少文件IO开销，提升性能。
• 自动检测浏览器语言：通过请求头Accept-Language自动识别用户偏好，示例代码：

  app.use((req, res, next) => {
    if (!req.session.locale) {
      const browserLang = req.headers['accept-language']?.split(',')[0]?.split('-')[0];
      req.session.locale = ['en', 'zh'].includes(browserLang) ? browserLang : 'en';
    }
    req.setLocale(req.session.locale);
    next();
  });
  

• 多语言测试：模拟不同语言环境，检查是否存在翻译遗漏或格式错误。

内容的提问来源于stack exchange，提问作者Ahmed Shama