使用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技能，使 AI 代理的开发者体验 (DX) 更加流畅。

自动化

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

表现

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

无需开发即可扩展

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

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

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

1. 1

   安装依赖项

   使用npm安装必要的包：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npm install intlayer angular-intlayernpm install @angular-builders/custom-esbuild --save-devnpx intlayer init

   • intlayer

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

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

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

2. 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. 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. 4

   声明您的内容

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

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

   详细信息请参考 内容声明文档。

5. 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. 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配置包含了自动生成的类型。

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

Git配置

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

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

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

VS Code 扩展

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

从VS Code应用市场安装

该扩展提供：

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

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

深入了解

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