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

    使用Intlayer翻译您的Angular 21（Vite）网站 | 国际化 (i18n)

    目录

    为什么选择 Inlayer 而不是替代品？

    与“ngx-translate”或“angular-l10n”等主要解决方案相比，Intlayer 是一个具有集成优化的解决方案，例如：

    Intlayer 经过优化，可与 Angular 完美配合，提供组件级内容范围、延迟加载翻译以及​​扩展国际化 (i18n) 所需的所有功能。

    不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于将捆绑包和页面大小减少多达 50%。

    确定应用程序内容的范围有利于大型应用程序的维护。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有完全类型化 (fully typed)，以确保您的内容的准确性。

    共置内容减少大型语言模型 (LLM) 所需的上下文。 Intlayer 还附带了一套工具，例如用于测试缺失翻译的 CLI、LSP、MCP 和 agent skills，使 AI 代理的开发者体验 (DX) 更加流畅。

    使用您选择的法学硕士，通过自动化在 CI/CD 管道中进行翻译，而费用由您的 AI 提供商承担。 Intlayer 还提供了一个编译器来自动提取内容，以及一个网络平台来帮助在后台翻译。

    将大量 JSON 文件连接到组件可能会导致性能和反应性问题。 Intlayer 可在构建时 (build time)优化您的内容加载。

    Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个自托管的可视化编辑器和一个完整的 CMS 来帮助您管理多语言内容实时，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。

    在Angular应用程序中设置Intlayer的分步指南

    ide.intlayer.org
    intlayer-angular-22-template.vercel.app

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

    1. 安装依赖项

      使用npm安装必要的包：

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

      • intlayer

        核心包，提供了配置管理、翻译、内容声明、转译和CLI命令等国际化工具。

      • angular-intlayer 将Intlayer与Angular应用程序集成的包。它为Angular的国际化提供了上下文提供者（Providers）和Hooks。

      • @angular-builders/custom-esbuild 需要它来自定义Angular CLI的esbuild配置。

    2. 配置您的项目

      创建一个配置文件以配置您应用程序的语言：

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // 您支持的其他语言
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;
      通过此配置文件，您可以设置本地化的URL、中间件重定向、Cookie名称、内容声明的位置和扩展名、禁用控制台中的Intlayer日志等。获取所有可用参数的完整列表，请参考配置文档。

    3. 在Angular配置中集成Intlayer

      要将Intlayer与Angular CLI集成，您需要使用自定义构建器。本指南假设您使用的是 Vite/esbuild（Angular 21项目的默认设置）。

      首先，修改您的 angular.json，使用自定义的esbuild构建器。更新 build 和 serve 配置：

      angular.json
      {
  "projects": {
    "your-app-name": {
      "architect": {
        "build": {
          "builder": "@angular-builders/custom-esbuild:application", // replace "@angular/build:application"
          "options": {
            "define": {
              "process.env": "{}",
            },
            "plugins": ["./esbuild.plugins.ts"],
            "browser": "src/main.ts",
            // ...
          },
        },
        "serve": {
          "builder": "@angular-builders/custom-esbuild:dev-server", // replace "@angular/build:dev-server"
          "options": {
            "prebundle": {
              "exclude": [
                "intlayer",
                "angular-intlayer",
                "@intlayer/config/built",
                "@intlayer/core"
              ]
          },
        },
      },
    },
  },
}
      请确保将 angular.json 中的 your-app-name 替换为您项目的实际名称。

      接下来，在项目的根目录中创建一个 esbuild.plugins.ts 文件：

      esbuild.plugins.ts
      import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";

export default [intlayerEsbuildPlugin()];
      intlayerEsbuildPlugin 函数负责使用Intlayer配置esbuild。它注入插件来处理内容声明文件，并针对最佳性能进行了设置。

      NX 用户：NX 的 Angular 构建器通过 Node 的原生 ESM 解析加载插件文件，并且不会实时编译 TypeScript 插件文件。请改用 .mjs 文件，并相应地更新 angular.json 中的 plugins 引用：

      esbuild.plugins.mjs
      import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";

export default [intlayerEsbuildPlugin()];

      然后在 angular.json 中指向 "./esbuild.plugins.mjs"，而不是 "./esbuild.plugins.ts"。

    4. 声明您的内容

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

      您的内容声明可以定义在应用程序的任何位置，只需将其包含在 contentDir 目录（默认为 ./src）中，并且符合内容声明的文件后缀名（默认为 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）。
      详细信息请参考 内容声明文档。

    5. 在代码中使用Intlayer

      要在整个Angular应用程序中利用Intlayer的国际化功能，您需要在应用程序配置中提供Intlayer。

      src/app/app.config.ts
      import { ApplicationConfig } from "@angular/core";
import { provideRouter } from "@angular/router";
import { provideIntlayer } from "angular-intlayer";
import { routes } from "./app.routes";

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideIntlayer(), // 在此添加Intlayer提供者
  ],
};

      然后，您可以在任何组件中使用 useIntlayer 功能。

      src/app/app.component.ts
      import { Component } from "@angular/core";
import { RouterOutlet } from "@angular/router";
import { useIntlayer } from "angular-intlayer";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [RouterOutlet],
  templateUrl: "./app.component.html",
  styleUrl: "./app.component.css",
})
export class AppComponent {
  content = useIntlayer("app");
}

      在您的模板中：

      src/app/app.component.html
      <div class="content">
  <h1>{{ content().title }}</h1>
  <p>{{ content().congratulations }}</p>
</div>

      Intlayer 内容将作为 Signal 返回，因此您可以通过调用信号来访问值：content().title。

    6. 更改内容的语言

      要更改内容的语言，您可以使用 useLocale 函数提供的 setLocale 函数。这允许您设置应用程序的区域设置，并相应更新内容。

      创建一个用于切换语言的组件：

      src/app/locale-switcher.component.ts
      import { Component } from "@angular/core";
import { CommonModule } from "@angular/common";
import { useLocale } from "angular-intlayer";

@Component({
  selector: "app-locale-switcher",
  standalone: true,
  imports: [CommonModule],
  template: `
    <div class="locale-switcher">
      <select
        [value]="locale()"
        (change)="setLocale($any($event.target).value)"
      >
        @for (loc of availableLocales; track loc) {
          <option [value]="loc">{{ loc }}</option>
        }
      </select>
    </div>
  `,
})
export class LocaleSwitcherComponent {
  localeCtx = useLocale();

  locale = this.localeCtx.locale;
  availableLocales = this.localeCtx.availableLocales;
  setLocale = this.localeCtx.setLocale;
}

      然后，在 app.component.ts 中使用此组件：

      src/app/app.component.ts
      import { Component } from "@angular/core";
import { RouterOutlet } from "@angular/router";
import { useIntlayer } from "angular-intlayer";
import { LocaleSwitcherComponent } from "./locale-switcher.component";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [RouterOutlet, LocaleSwitcherComponent],
  templateUrl: "./app.component.html",
  styleUrl: "./app.component.css",
})
export class AppComponent {
  content = useIntlayer("app");
}

    配置TypeScript

    Intlayer使用模块扩充（Module Augmentation）来获得TypeScript的好处，并使您的代码库更健壮。

    自动补全

    翻译错误

    请确保您的TypeScript配置包含了自动生成的类型。

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

    Git配置

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

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

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

    VS Code 扩展

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

    从VS Code应用市场安装

    该扩展提供：

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

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

    深入了解

    想要深入了解，您可以实现可视化编辑器或使用CMS外部化您的内容。

    常见问题

    • @angular/localize（内置 i18n）：消息被提取到 XLIFF 文件中，每个语言环境被编译进独立的构建产物中，这意味着每种语言对应一个部署产物，无法在运行时切换语言环境。
    • ngx-translate 和 Transloco：通过服务加载的运行时 JSON 目录，支持语言环境切换，但没有构建时类型安全。
    • Intlayer：最先进的解决方案。内容可以在代码库中的任何位置声明（靠近每个组件或集中管理），并在构建时进行编译，全链路类型安全，支持运行时语言环境切换、AI 翻译、可视化编辑器和 CMS。

    脱离 @angular/localize 的常见原因正是其“每个语言环境一次构建”的模式。Intlayer 保持单一构建产物并在运行时无缝切换语言。请参阅 为什么选择 Intlayer。

    远少于基于命名空间的方案，因为页面永远不会下载它不渲染的语言目录。构建时编译器将 useIntlayer 调用替换为组件使用的确切字典条目，因此未使用的键和未使用的语言都会被自动丢弃，并且 动态字典 会按语言环境拆分剩余内容。与常规替代方案相比，Intlayer 可将 bundle 和页面体积减少高达 50%。请参阅 Bundle 体积优化 和 性能基准。

    基本可以。请按照 ngx-translate 迁移指南 或 Transloco 迁移指南 迁移内容。您也可以逐步迁移：JSON 同步插件 将现有的 JSON 目录作为单一真实来源（source of truth），并生成 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 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
    Vite和LitAngular 19 (Webpack)