使用 Intlayer 翻译你的 Angular 19 (Webpack) 网站

目录

为什么选择 Intlayer 而不是其他方案？

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

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

查看 GitHub 上的应用模板。

1. 1

   安装依赖

   使用 npm 安装必要的包：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npx intlayer init --interactive
   

   --interactive 标志是可选的。如果你是 AI 代理，请使用 intlayer-cli init。

   此命令将检测你的环境并安装所需的包。例如：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npm install intlayer angular-intlayer
   npm install @angular-builders/custom-webpack --save-dev
   

   • intlayer

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

   • angular-intlayer 将 Intlayer 与 Angular 应用集成的包。它为 Angular 国际化提供上下文 Provider 和 Hook。

   • @angular-builders/custom-webpack 自定义 Angular CLI 的 Webpack 配置所需。

2. 2

   配置你的项目

   架构

   在此架构中，angular-intlayer 提供 provideIntlayer()，并在 src/app/app.config.ts 中注册，以便每个组件都能通过 useIntlayer signal 读取其内容。Angular CLI 切换为自定义 Webpack 构建器，webpack.config.ts 将 Intlayer 插件合并到构建中，以监视并重新构建你的内容声明。内容声明文件与组件一起放置在 src/app/ 中。

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   .
   ├── src
   │   ├── app
   │   │   ├── app.component.html        # Root template reading the content signal
   │   │   ├── app.component.ts          # Root component using useIntlayer
   │   │   ├── app.config.ts             # Application config with provideIntlayer()
   │   │   ├── app.content.ts            # App content declaration
   │   │   └── locale-switcher.component.ts
   │   └── main.ts
   ├── angular.json                      # Custom Webpack builder for build and serve
   ├── intlayer.config.ts
   ├── package.json
   ├── tsconfig.json
   └── webpack.config.ts                 # mergeConfig() from angular-intlayer/webpack
   

   配置

   创建一个配置文件来配置应用的语言：

   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 集成，你需要使用自定义构建器。本指南假设你使用 Webpack（许多 Angular 项目的默认设置）。

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

   angular.json

   复制内容

   复制代码

   复制代码到剪贴板

   {
     "projects": {
       "your-app-name": {
         "architect": {
           "build": {
             "builder": "@angular-builders/custom-webpack:browser", // 替换 "@angular-devkit/build-angular:application"
             "options": {
               "customWebpackConfig": {
                 "path": "./webpack.config.ts",
                 "mergeStrategies": { "module.rules": "prepend" },
               },
               "main": "src/main.ts", // 替换 "browser": "src/main.ts"
               // ...
             },
           },
           "serve": {
             "builder": "@angular-builders/custom-webpack:dev-server", // 替换 "@angular-devkit/build-angular:dev-server"
           },
         },
       },
     },
   }
   

   确保在 angular.json 中用你项目的实际名称替换 your-app-name。

   接下来，在项目的根目录创建一个 webpack.config.ts 文件：

   webpack.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { mergeConfig } from "angular-intlayer/webpack";
   
   export default mergeConfig({});
   

   mergeConfig 函数使用 Intlayer 配置 Webpack。它注入 IntlayerPlugin（处理内容声明文件）并设置别名以获得最佳性能。

4. 4

   声明你的内容

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

   src/app/app.content.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: t({
         zh: "你好",
         en: "Hello",
         fr: "Bonjour",
         es: "Hola",
       }),
       congratulations: t({
         zh: "恭喜！你的应用正在运行。🎉",
         en: "Congratulations! Your app is running. 🎉",
         fr: "Félicitations! Votre application est en cours d'exécution. 🎉",
         es: "¡Felicidades! Tu aplicación está en ejecución. 🎉",
       }),
       exploreDocs: t({
         zh: "浏览文档",
         en: "Explore the Docs",
         fr: "Explorer les Docs",
         es: "Explorar los Docs",
       }),
       learnWithTutorials: t({
         zh: "通过教程学习",
         en: "Learn with Tutorials",
         fr: "Apprendre avec les Tutoriels",
         es: "Aprender con los Tutorios",
       }),
       cliDocs: "CLI Docs",
       angularLanguageService: t({
         zh: "Angular 语言服务",
         en: "Angular Language Service",
         fr: "Service de Langage Angular",
         es: "Servicio de Lenguaje Angular",
       }),
       angularDevTools: "Angular DevTools",
       github: "Github",
       twitter: "Twitter",
       youtube: "Youtube",
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   你的内容声明可以定义在应用的任何地方，只要它们包含在 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 返回，所以你通过调用 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 使用模块扩充来发挥 TypeScript 的优势并使你的代码库更强大。

确保你的 TypeScript 配置包含自动生成的类型。

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

Git 配置

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

为此，你可以在 .gitignore 文件中添加以下指令：

#  忽略 Intlayer 生成的文件
.intlayer

VS Code 扩展

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

该扩展提供：

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

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

深入了解

要进一步深入，你可以实现 可视化编辑器 或使用 CMS 外置你的内容。

常见问题