使用Intlayer和Express实现后端国际化(i18n)的完整指南

2025-06-12 15:51:17作者：尤峻淳Whitney

前言：为什么后端也需要国际化？

在全球化应用开发中，前端国际化已经广为人知，但后端国际化同样重要。Intlayer项目提供了一套完整的解决方案，特别是express-intlayer中间件，让Express应用能够轻松实现后端国际化。本文将详细介绍如何利用Intlayer为Express应用添加多语言支持。

核心概念解析

后端国际化的核心价值

统一用户体验：从API错误信息到邮件通知，保持全栈语言一致性
动态内容支持：数据库中的多语言内容可以通过API按需返回
微服务兼容性：在微服务架构中确保各服务返回统一语言格式

Intlayer的核心功能

基于请求自动识别用户语言偏好
类型安全的翻译管理系统
与前端框架无缝集成的能力
灵活的配置选项

实战教程

第一步：环境准备

安装必要的依赖包：

# 使用npm
npm install intlayer express-intlayer

# 使用yarn
yarn add intlayer express-intlayer

# 使用pnpm
pnpm add intlayer express-intlayer

第二步：基础配置

创建intlayer.config.ts配置文件：

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH_MEXICO,
      Locales.SPANISH_SPAIN,
    ],
    defaultLocale: Locales.ENGLISH,
  },
  middleware: {
    headerName: "accept-language", // 默认使用标准HTTP头
    cookieName: "user_lang",      // 可选cookie支持
  },
};

export default config;

第三步：创建翻译内容

推荐使用TypeScript定义翻译内容以获得最佳类型支持：

// src/messages.content.ts
import { t, type Dictionary } from "intlayer";

export const messages = {
  key: "user_messages",
  content: {
    welcome: t({
      en: "Welcome to our service",
      fr: "Bienvenue sur notre service",
      "es-ES": "Bienvenido a nuestro servicio",
      "es-MX": "Bienvenido a nuestro servicio",
    }),
    error: {
      notFound: t({
        en: "Resource not found",
        fr: "Ressource introuvable",
        "es-ES": "Recurso no encontrado",
        "es-MX": "Recurso no encontrado",
      }),
    },
  },
} satisfies Dictionary;

第四步：集成到Express应用

完整集成示例：

import express from "express";
import { intlayer, t, getDictionary, getIntlayer } from "express-intlayer";
import { messages } from "./messages.content";

const app = express();

// 启用国际化中间件
app.use(intlayer());

// 示例路由
app.get("/api/welcome", (req, res) => {
  // 方法1：直接使用t函数
  res.json({
    message: t({
      en: "Hello World",
      fr: "Bonjour le monde",
      "es-ES": "Hola Mundo",
      "es-MX": "Hola Mundo",
    }),
  });
});

app.get("/api/messages", (req, res) => {
  // 方法2：从内容声明中获取
  res.json(getDictionary(messages));
});

app.get("/api/errors/404", (req, res) => {
  // 方法3：通过key获取
  res.status(404).json({
    error: getIntlayer("user_messages").error.notFound,
  });
});

app.listen(3000, () => console.log("Server running on port 3000"));

高级用法

自定义语言检测逻辑

// 自定义中间件示例
app.use((req, res, next) => {
  // 从自定义header获取语言
  const customLang = req.headers["x-custom-lang"];
  if (customLang) {
    req.locale = customLang.toString();
  }
  next();
});

// 然后应用intlayer中间件
app.use(intlayer());

动态内容国际化

app.get("/api/products/:id", async (req, res) => {
  const product = await Product.findById(req.params.id);
  
  res.json({
    ...product,
    // 将产品描述国际化
    description: t({
      en: product.description_en,
      fr: product.description_fr,
      "es-ES": product.description_es,
    }),
  });
});

开发工具推荐

TypeScript配置

确保tsconfig.json包含：

{
  "compilerOptions": {
    "strict": true,
    "types": ["intlayer/types"]
  },
  "include": [
    "src/**/*",
    ".intlayer/**/*.ts"
  ]
}

VS Code扩展

Intlayer官方扩展提供：

实时翻译预览
缺失翻译警告
快速跳转到定义
自动补全支持

最佳实践

目录结构：按功能模块组织翻译文件

/src
  /i18n
    /auth
      login.content.ts
      register.content.ts
    /products
      listing.content.ts
      details.content.ts

错误处理：统一错误消息格式

// errors.content.ts
export const errors = {
  key: "errors",
  content: {
    validation: {
      email: t({...}),
      password: t({...}),
    },
    server: {
      internal: t({...}),
    },
  },
};

性能优化：
- 对频繁访问的翻译内容进行缓存
- 考虑使用CDN分发静态翻译内容
- 实现按需加载翻译包

常见问题解答

Q：如何处理动态插值的翻译？ A：Intlayer支持参数化翻译：

const messages = {
  greeting: t({
    en: "Hello, {name}!",
    fr: "Bonjour, {name}!",
  }),
};

// 使用时
const greeting = t(messages.greeting, { name: "Alice" });