使用 Intlayer 翻译您的 Analog (Angular) 应用 | 国际化 (i18n)

目录

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

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

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

请参阅 GitHub 上的 Application Template。

1. 1

   安装依赖项

   使用 npm 安装必要的包：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npx intlayer init --interactive
   

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

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

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npm install intlayer angular-intlayer vite-intlayer
   

   • intlayer

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

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

   • vite-intlayer 将 Intlayer 与 Vite 集成的包。它提供了一个插件来处理内容声明文件，并为最佳性能设置别名。

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

   在你的 Vite 配置中集成 Intlayer

   要将 Intlayer 与 Analog 集成，你需要使用 vite-intlayer 插件。

   修改你的 vite.config.ts 文件：

   vite.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   import analog from "@analogjs/platform";
   
   // https://vitejs.dev/config/
   export default defineConfig(() => ({
     plugins: [
       analog(),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   }));
   

   intlayer() 插件使用 Intlayer 配置 Vite。它处理内容声明文件并为最佳性能设置别名。

4. 4

   声明你的内容

   创建和管理内容声明以存储翻译：

   你的内容声明可以在应用的任何地方定义，只要它们包含在 contentDir 目录中（默认为 ./src）。并且匹配内容声明文件扩展名（默认为 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）。

   有关更多详情，请参阅 内容声明文档。

5. 5

   在你的代码中使用 Intlayer

   要在整个 Analog 应用中使用 Intlayer 的国际化功能，你需要在应用配置中提供 Intlayer。

   src/app/app.config.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { ApplicationConfig } from "@angular/core";
   import { provideIntlayer } from "angular-intlayer";
   
   export const appConfig: ApplicationConfig = {
     providers: [
       provideIntlayer(), // 在这里添加 Intlayer 提供者
     ],
   };
   

   然后，你可以在任何组件中使用 useIntlayer 函数。

   src/app/pages/index.page.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { Component } from "@angular/core";
   import { useIntlayer } from "angular-intlayer";
   
   @Component({
     selector: "app-home",
     standalone: true,
     template: `
       <div class="content">
         <h1>{{ content().title }}</h1>
         <p>{{ content().congratulations }}</p>
       </div>
     `,
   })
   export default class HomeComponent {
     content = useIntlayer("app");
   }
   

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

   然后，在你的页面中使用此组件：

   src/app/pages/index.page.ts

   复制内容

   复制代码

   复制代码到剪贴板

   import { Component } from "@angular/core";
   import { useIntlayer } from "angular-intlayer";
   import { LocaleSwitcherComponent } from "../locale-switcher.component";
   
   @Component({
     selector: "app-home",
     standalone: true,
     imports: [LocaleSwitcherComponent],
     template: `
       <app-locale-switcher></app-locale-switcher>
       <div class="content">
         <h1>{{ content().title }}</h1>
         <p>{{ content().congratulations }}</p>
       </div>
     `,
   })
   export default class HomeComponent {
     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 外部化你的内容。