作者:
    Aymeric PINEAU
    Creation:2025-12-30Last update:2026-08-30

    使用 Intlayer 翻译您的 Fastify 后端网站 | 国际化 (i18n)

    fastify-intlayer 是一个强大的 Fastify 应用程序国际化 (i18n) 插件，旨在通过根据客户端的偏好提供本地化响应，使您的后端服务在全球范围内可访问。

    在 GitHub 上查看软件包实现。

    实际应用场景

    • 以用户语言显示后端错误：发生错误时，以用户的母语显示消息可以提高理解度并减少挫败感。这对于可能显示在前端组件（如 toast 或 modal）中的动态错误消息特别有用。
    • 检索多语言内容：对于从数据库提取内容的应用程序，国际化确保您可以提供多种语言的内容。这对于电子商务网站或内容管理系统等平台至关重要，这些平台需要以用户首选的语言显示产品描述、文章和其他内容。
    • 发送多语言电子邮件：无论是事务性电子邮件、营销活动还是通知，以收件人的语言发送电子邮件都可以显著提高参与度和有效性。
    • 多语言推送通知：对于移动应用程序，以用户首选的语言发送推送通知可以增强交互和留存。这种个性化的触感可以让通知感觉更具相关性和可操作性。
    • 其他通信：来自后端的任何形式的通信（如短信、系统警报或用户界面更新）都受益于使用用户的语言，从而确保清晰度并增强整体用户体验。

    通过对后端进行国际化，您的应用程序不仅尊重文化差异，而且能更好地符合全球市场需求，使其成为在全球范围内扩展服务的关键步骤。

    入门指南

    ide.intlayer.org

    在 GitHub 上查看 应用程序模板。

    安装

    要开始使用 fastify-intlayer，请使用 npm 安装软件包：

    bash
    npx intlayer init --interactive
    --interactive 标志是可选的。如果您是 AI 代理，请使用 intlayer-cli init。
    该命令将检测您的环境并安装所需的软件包。例如：
    bash
    npm install intlayer fastify-intlayer

    设置

    通过在项目根目录中创建 intlayer.config.ts 来配置国际化设置：

    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,
  },
};

export default config;

    声明内容

    创建并管理您的内容声明以存储翻译：

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

const indexContent = {
  key: "index",
  content: {
    exampleOfContent: t({
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      "es-ES": "Ejemplo de contenido devuelto en español (España)",
      "es-MX": "Ejemplo de 内容 devuelto en español (México)",
    }),
  },
} satisfies Dictionary;

export default indexContent;
    只要包含在 contentDir 目录（默认为 ./src）中，您的内容声明就可以在应用程序的任何位置定义。并且匹配内容声明文件扩展名（默认为 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）。
    有关更多详情，请参阅 内容声明文档。

    Fastify 应用程序设置

    设置您的 Fastify 应用程序以使用 fastify-intlayer：

    src/index.ts
    import Fastify from "fastify";
import { intlayer, t, getDictionary, getIntlayer } from "fastify-intlayer";
import dictionaryExample from "./index.content";

const fastify = Fastify({ logger: true });

// 加载国际化插件
await fastify.register(intlayer);

// 路由
fastify.get("/t_example", async (_req, reply) => {
  return t({
    en: "Example of returned content in English",
    fr: "Exemple de contenu renvoyé en français",
    "es-ES": "Ejemplo de contenido devuelto en español (España)",
    "es-MX": "Ejemplo de 内容 devuelto en español (México)",
  });
});

fastify.get("/getIntlayer_example", async (_req, reply) => {
  return getIntlayer("index").exampleOfContent;
});

fastify.get("/getDictionary_example", async (_req, reply) => {
  return getDictionary(dictionaryExample).exampleOfContent;
});

// 启动服务器
const start = async () => {
  try {
    await fastify.listen({ port: 3000 });
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

start();

    兼容性

    fastify-intlayer 与以下项完全兼容：

    它还可以跨各种环境（包括浏览器和 API 请求）与任何国际化解决方案无缝协作。您可以自定义中间件通过 header 或 cookie 检测语言区域：

    intlayer.config.ts
    import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... 其他配置选项
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

    默认情况下，fastify-intlayer 将解释 Accept-Language 标头以确定客户端的首选语言。

    有关配置和高级主题的更多信息，请访问我们的 文档。

    配置 TypeScript

    fastify-intlayer 利用 TypeScript 的强大功能来增强国际化过程。TypeScript 的静态类型确保每个翻译键都被考虑到，从而降低丢失翻译的风险并提高可维护性。

    确保在您的 tsconfig.json 文件中包含自动生成的类型（默认为 ./types/intlayer.d.ts）。

    tsconfig.json
    {
  // ... 您的现有 TypeScript 配置
  "include": [
    // ... 您的现有 TypeScript 配置
    ".intlayer/**/*.ts", // 包含自动生成的类型
  ],
}

    VS Code 扩展

    为了改善您使用 Intlayer 的开发体验，您可以安装官方的 Intlayer VS Code Extension。

    从 VS Code Marketplace 安装

    该扩展包含：

    • 翻译键的 自动补全。
    • 针对缺失翻译的 实时错误检测。
    • 翻译内容的 内联预览。
    • 轻松创建和更新翻译的 快速操作。

    有关如何使用该扩展的更多详情，请参阅 Intlayer VS Code Extension 文档。

    Git 配置

    建议忽略由 Intlayer 生成的文件。这可以避免将它们提交到您的 Git 仓库。

    为此，您可以将以下说明添加到 .gitignore 文件中：

    .gitignore
    # 忽略由 Intlayer 生成的文件
.intlayer

    常见问题

    通用方案是使用 i18next 配合 fastify-i18next 或手写钩子，它按命名空间加载 JSON 目录并将语言环境存储在请求对象上。另一种选择是通过 fastify-intlayer 使用 Intlayer，它自动为您注册插件，按请求解析语言环境，并与前端共享相同的类型化内容。

    后端国际化的核心原因在于，用户阅读的大量文本并不经过前端：API 错误消息、事务性邮件、推送通知、短信以及导出的 PDF 文件。这些内容都需要根据接收者的语言进行解析，且应针对每个请求独立解析，而非按会话存储。

    请参阅 为什么选择 Intlayer。

    极少。字典在构建前预先编译，仅包含您声明的语言环境，因此启动时无需加载整个大目录，处理请求路径时也无需读取文件系统。这在 Serverless 和 Edge 环境中尤为重要，因为体积直接决定冷启动耗时。请参阅 Bundle 体积优化。

    可以，有两条迁移路径。您可以使用 i18next 迁移指南 逐步迁移内容。或者，您可以完全保留当前的 API：兼容性适配器 公开与 i18next 完全相同的 API，但底层由 Intlayer 字典驱动，因此只需更改导入语句，路由处理函数代码无需修改。

    可以。JSON 同步插件 将您的 /messages/{locale}/{namespace}.json 文件作为单一真实来源（source of truth），并双向生成 Intlayer 字典。PO 同步插件 对 gettext 目录执行相同的操作，而 按语言环境组织的文件 允许您按语言拆分内容，而不是将所有语言打包到一个文件中。

    不需要。运行 npx intlayer extract，Intlayer 会读取您的源码文件，提取面向用户的字符串，并在每个组件旁边生成 .content 文件，这样您只需审查 diff，而无需手动逐一复制字符串到语言目录中。请参阅 extract 命令。

    在同一项目的前端部分，Intlayer Compiler 则更进一步，可以在构建时直接从 JSX、TSX、Vue 或 Svelte 源码生成字典，使应用的前后端共享同一套内容层，完全无需手动维护键名。

    共有 5 个工具，均为可选：

    • VS Code 扩展：从 useIntlayer 键跳转到声明它的内容文件，从组件中提取内容，并从命令面板或专属的 Intlayer 选项卡运行 build、fill、test、push 和 pull。
    • LSP 服务器：在任何支持 LSP 的编辑器中提供相同的感知能力，支持跳转到定义、查找所有引用、悬停预览翻译值、键和字段的自动补全，以及在键未声明时发出警告。它还可以解析 i18next、react-i18next、next-intl 和 use-intl 调用，助力平滑迁移。
    • MCP 服务器：向 Cursor、VS Code、Claude Desktop、Claude Code 和 ChatGPT 公开 Intlayer 文档与 CLI，使 AI 助手能够基于最新文档进行准确回答，并能自行运行 intlayer fill 等命令。
    • Agent Skills：针对特定领域的技能（如 intlayer-config、intlayer-cli 和 intlayer-content，以及每个框架对应的专属技能），教导 AI 代理您的路由配置和内容节点类型。
    • ESLint 插件：no-raw-text 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
    NestJSHono