Angular 国际化：i18n 支持

启用 Angular 的 i18n（国际化）功能，能让你的应用自动根据用户的语言环境显示对应语言的内容。 以下是完整的操作流程，从初始化项目到最终部署多语言版本。

准备工作

1. 确保已安装最新版 Angular CLI。打开终端，执行：

   ng version

   如果版本低于 15.x，建议升级以获得最佳 i18n 支持。

2. 创建新项目时启用 i18n（推荐）。运行以下命令：

   ng new my-i18n-app --localize

   此命令会自动配置基础国际化设置，并提示你选择默认语言（如 zh-Hans 表示简体中文）。

3. 若已有项目需添加 i18n，手动修改 angular.json 文件，在 projects > your-project-name > i18n 节点下添加：

   "i18n": {
     "sourceLocale": "zh-Hans",
     "locales": {
       "en": "src/locale/messages.en.xlf"
     }
   }

   其中 sourceLocale 是源语言（开发时写代码用的语言），locales 定义目标语言及其翻译文件路径。

标记需要翻译的文本

1. 在组件模板中使用 i18n 属性标记静态文本。例如：

   <h1 i18n>欢迎使用本应用</h1>

   Angular 会自动提取此文本用于翻译。

2. 为动态内容或带参数的文本添加描述和含义（可选但推荐）。格式为：

   <p i18n="页面标题|首页的主标题@@homeTitle">欢迎回来，{{ user.name }}！</p>

   • 引号内第一部分是描述（供翻译人员参考）
   • 竖线后是含义（区分相同文本在不同上下文的用途）
   • @@ 后是自定义 ID（避免 Angular 自动生成的哈希 ID）

3. 标记属性值。例如按钮的 title 提示：

   <button title="点击保存" i18n-title>保存</button>

4. 处理复数和性别等复杂逻辑时，使用 ICU 消息格式。例如：

   <span i18n>
     {userCount, plural,
       =0 {暂无用户}
       =1 {有 1 位用户}
       other {有 {{userCount}} 位用户}
     }
   </span>

提取翻译源文件

1. 运行提取命令生成 .xlf 文件：

   ng extract-i18n

   默认在 src/ 目录下生成 messages.xlf（XML Localization Interchange File Format）。

2. 若需指定输出格式或路径，使用参数：

   ng extract-i18n --output-path src/locale --format xlf2

   常见格式包括 xlf（旧版）、xlf2（新版，推荐）、xmb。

3. 检查生成的 messages.xlf 文件。关键结构如下：

   <trans-unit id="homeTitle" datatype="html">
     <source>欢迎回来，{{ INTERPOLATION }}</source>
     <context-group purpose="location">
       <context context-type="sourcefile">app.component.html</context>
     </context-group>
   </trans-unit>

   • <source> 是源语言文本
   • INTERPOLATION 表示插值表达式（如 {{ user.name }}）
   • id 对应模板中的 @@homeTitle

创建并填充翻译文件

1. 为目标语言复制源文件并重命名。例如英文翻译：

   cp src/messages.xlf src/locale/messages.en.xlf

2. 编辑 messages.en.xlf，为每个 <trans-unit> 添加 <target> 节点：

   <trans-unit id="homeTitle" datatype="html">
     <source>欢迎回来，{{ INTERPOLATION }}</source>
     <target>Welcome back, {{ INTERPOLATION }}!</target>
   </trans-unit>

   • 保留所有占位符（如 {{ INTERPOLATION }}）
   • 若文本含 HTML 标签，需用 <x id="..."/> 占位，例如：

     <source>Hello <b>world</b>!</source>
     <target>Hola <x id="START_BOLD"/>mundo<x id="CLOSE_BOLD"/>!</target>

3. 处理 ICU 复数消息时，完整翻译整个结构：

   <source>
     {VAR_PLURAL,
       =0 {No users}
       =1 {One user}
       other {Many users}
     }
   </source>
   <target>
     {VAR_PLURAL,
       =0 {Ningún usuario}
       =1 {Un usuario}
       other {Muchos usuarios}
     }
   </target>

构建多语言应用

1. 配置 angular.json 的 build 和 serve 目标。在 projects > your-project > architect 下找到 build，添加 localize 选项：

   "build": {
     "builder": "@angular-devkit/build-angular:browser",
     "options": {
       "localize": true
     },
     "configurations": {
       "production": {
         "localize": ["en"]
       }
     }
   }

   • localize: true 表示构建所有配置的语言
   • localize: ["en"] 表示仅构建英文版

2. 本地测试特定语言版本。运行：

   ng serve --configuration=en

   应用将在 http://localhost:4200 以英文启动。

3. 构建生产版本。执行：

   ng build --configuration=production

   输出目录（默认 dist/）将包含：

   • dist/my-i18n-app/：源语言版本（如中文）
   • dist/my-i18n-app/en/：英文版本

动态切换语言（运行时）

Angular 官方 i18n 不支持运行时动态切换语言（因翻译在构建时注入）。如需此功能，必须：

1. 为每种语言单独构建应用（如上一步所示）。
2. 通过服务器路由或子目录提供不同语言版本。例如：
   • https://example.com/ → 中文版
   • https://example.com/en/ → 英文版
3. 在页面顶部添加语言切换器，跳转到对应路径：

   <select (change)="switchLang($event)">
     <option value="/">中文</option>
     <option value="/en/">English</option>
   </select>

   switchLang(event: any) {
     window.location.pathname = event.target.value;
   }

常见问题处理

高级技巧

1. 使用自定义 ID 避免哈希变动。当源文本修改时，Angular 默认会生成新 ID 导致翻译失效。显式指定 ID 可解决：

   <p i18n="@@userGreeting">你好，{{ name }}！</p>

2. 批量处理多个语言。在 angular.json 中配置多语言：

   "locales": {
     "en": "src/locale/messages.en.xlf",
     "es": "src/locale/messages.es.xlf",
     "fr": "src/locale/messages.fr.xlf"
   }

   构建时使用 --localize=true 一次性生成所有版本。

3. 自动化翻译流程。结合 CI/CD 工具：

   • 提交代码后自动运行 ng extract-i18n
   • 将新 .xlf 文件推送到翻译平台（如 Lokalise、Crowdin）
   • 翻译完成后拉取 .xlf 并触发构建

# 示例：GitHub Actions 片段
- name: Extract translations
  run: ng extract-i18n --format xlf2
- name: Upload to Crowdin
  uses: crowdin/github-action@v1
  with:
    upload_sources: true