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

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

    hono-intlayer 是一个功能强大的 Hono 应用程序国际化 (i18n) 中间件，旨在通过根据客户端的首选项提供本地化响应，使您的后端服务能够被全球用户访问。

    实际应用场景

    • 以用户语言显示后端错误：当发生错误时，以用户的母语显示消息可以提高理解度并减少挫败感。这对于可能显示在前端组件（如 toast 或模态框）中的动态错误消息尤其有用。

    • 检索多语言内容：对于从数据库提取内容的应用程序，国际化确保您可以以多种语言提供这些内容。这对于电子商务网站或内容管理系统等平台至关重要，这些平台需要以用户首选的语言显示产品描述、文章和其他内容。

    • 发送多语言电子邮件：无论是事务性电子邮件、营销活动还是通知，以收件人的语言发送电子邮件都可以显著提高参与度和有效性。

    • 多语言推送通知：对于移动应用程序，以用户的首选语言发送推送通知可以增强互动和留存。这种个性化的触感可以使通知感觉更相关、更具操作性。

    • 其他沟通：来自后端的任何形式的沟通，如短信、系统警报或用户界面更新，都能从使用用户的语言中受益，从而确保清晰度并增强整体用户体验。

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

    入门指南

    ide.intlayer.org

    See Application Template on GitHub.

    安装

    要开始使用 hono-intlayer，请使用 npm 安装该包：

    bash
    npx intlayer init --interactive
    --interactive 标志是可选的。如果您是 AI 代理，请使用 intlayer-cli init。
    该命令将检测您的环境并安装所需的软件包。例如：
    bash
    npm install intlayer hono-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 contenido 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}）。
    有关更多详细信息，请参阅内容声明文档。

    Hono 应用程序设置

    设置您的 Hono 应用程序以使用 hono-intlayer：

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

const app = new Hono();

// 加载国际化请求处理器
app.use("*", intlayer());

// 路由
app.get("/t_example", (c) => {
  return c.text(
    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 contenido devuelto en español (México)",
    })
  );
});

app.get("/getIntlayer_example", (c) => {
  return c.json(getIntlayer("index").exampleOfContent);
});

app.get("/getDictionary_example", (c) => {
  return c.json(getDictionary(dictionaryExample).exampleOfContent);
});

export default app;

    兼容性

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

    它还可以与各种环境中的任何国际化解决方案无缝协作，包括浏览器和 API 请求。您可以自定义中间件以通过标头或 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;

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

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

    配置 TypeScript

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

    自动补全

    翻译错误

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

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

    VS Code 扩展

    为了提升您的 Intlayer 开发体验，您可以安装官方的 Intlayer VS Code 扩展。

    从 VS Code 市场安装

    该扩展提供：

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

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

    Git 配置

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

    为此，您可以将以下指令添加到您的 .gitignore 文件中：

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

    常见问题

    Hono 本身没有内置的 i18n 层，因此选择通常是：手动将诸如 i18next 之类的通用库封装到中间件中，或者通过 hono-intlayer 使用 Intlayer。hono-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 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
    FastifyAdonis