Angular 7 国际化技能套件

本技能套件为 Angular 7 项目提供完整的国际化解决方案，包含核心配置、翻译管理、NG-ZORRO 适配、老项目改造四个子技能。

支持的技术栈

• Angular: 7.x
• NG-ZORRO: 7.2.0
• TypeScript: 3.1.1
• Node.js: 10.16.2 (必须使用 nvm 切换到此版本)
• @ngx-translate/core: 11.0.1
• @ngx-translate/http-loader: 4.0.0

快速开始

前置检查：Node.js 版本

重要: 在执行任何命令前，必须先检查并切换 Node.js 版本到所需版本。

# 1. 检查当前 node 版本
node -v

# 2. 检查项目所需版本 (查看 package.json 中的 engines 字段)
cat package.json | grep -A 2 '"engines"'

# 3. 如果版本不匹配，使用 nvm 切换到所需版本
nvm list                    # 查看已安装的 node 版本
nvm install 10.16.2         # 安装所需版本 (如果未安装)
nvm use 10.16.2             # 切换到所需版本

本项目要求: Node.js 10.16.2

新项目初始化

# 1. 切换 node 版本到 10.16.2 (如需要)
nvm use 10.16.2

# 2. 配置核心依赖和模块
/angular7-i18n-core

# 3. 配置 NG-ZORRO 国际化
/angular7-i18n-ng-zorro

# 4. 生成翻译文件
/angular7-i18n-translate

老项目改造

# 1. 切换 node 版本到 10.16.2 (如需要)
nvm use 10.16.2

# 2. 一键改造老项目国际化
/angular7-i18n-migration

子技能列表

核心概念

语言读取优先级

1. 第一优先级: localStorage 中的 translate 字段
2. 第二优先级: 浏览器默认语言（navigator.language）
3. 默认值: 中文（zh）

翻译优先级

1. 第一优先级: translate.json 本地翻译字典
2. 第二优先级: 在线翻译 API
3. 备选方案: 简单规则翻译（安全术语映射）

项目目录结构

projects/
└── complianceManager/
    └── src/
        ├── app/
        │   ├── app.module.ts              # 根模块配置（含 APP_INITIALIZER）
        │   └── common-ui/
        │       └── shared/
        │           └── service/
        │               └── language/
        │                   └── language.service.ts    # 语言管理服务
        └── assets/
            └── i18n/
                ├── zh.json                # 中文翻译文件
                └── en.json                # 英文翻译文件

注意: translate.json 仅存在于技能目录中，作为翻译字典模板供 Python 脚本读取，不需要复制到项目中。

安全检查清单

使用本技能后，请确认以下项目：

• [ ] isop-design 已卸载（如存在）
• [ ] isop-design-i18n 已安装
• [ ] translate.json 存在且格式正确
• [ ] shared.module.ts 中配置了 NZ_I18N
• [ ] 翻译文件 zh.json 和 en.json key 一一对应
• [ ] 语言切换后 NG-ZORRO 组件同步更新
• [ ] APP_INITIALIZER 正确配置

使用说明

必须使用 translate 管道的场景

所有模板中的中文文本必须使用 {{ 'key' | translate }} 语法：

替换前：

<button>确定</button>
<h1>安全态势</h1>

替换后：

<button>{{ 'que_ding' | translate }}</button>
<h1>{{ 'an_quan_tai_shi' | translate }}</h1>

动态切换语言

在需要切换语言的组件中调用 LanguageService：

import { Component } from '@angular/core';
import { LanguageService } from './common-ui/shared/service/language/language.service';

@Component({
  selector: 'app-language-switch',
  template: `
    <button (click)="setChinese()">中文</button>
    <button (click)="setEnglish()">EN</button>
  `
})
export class LanguageSwitchComponent {
  constructor(private languageService: LanguageService) {}

  setChinese(): void {
    this.languageService.setLanguage('zh');
  }

  setEnglish(): void {
    this.languageService.setLanguage('en');
  }
}

子技能详细说明

1. i18n-core - 核心配置

功能: 依赖安装、目录结构、language.service.ts、app.module.ts 配置

使用场景: 新项目初始化国际化配置

核心步骤:

1. 安装 @ngx-translate/core@11.0.1 和 @ngx-translate/http-loader@4.0.0
2. 检查并卸载 isop-design（如存在），安装 isop-design-i18n
3. 创建 language.service.ts 语言管理服务
4. 配置 app.module.ts 添加 APP_INITIALIZER

2. i18n-translate - 翻译文件管理

功能: translate.json 管理、Python 脚本生成翻译文件

使用场景: 自动生成 zh.json 和 en.json，优先使用本地翻译字典

核心步骤:

1. Python 脚本扫描 TypeScript 和 HTML 文件中的硬编码中文
2. 优先读取 translate.json 本地翻译字典
3. 对于字典中不存在的中文，调用在线翻译 API
4. 生成 zh.json 和 en.json 翻译文件

3. i18n-ng-zorro - NG-ZORRO 国际化

功能: shared.module.ts 配置、NG-ZORRO 组件国际化

使用场景: 配置 NG-ZORRO 7.x 国际化

核心步骤:

1. 修改 shared.module.ts 添加 NZ_I18N provider
2. 使用 NG-ZORRO 7.x 特定配置：{ provide: NZ_I18N, useValue: zh_CN }
3. 确保语言切换时 NG-ZORRO 组件同步更新

4. i18n-migration - 老项目改造

功能: 老项目改造步骤、isop-design 替换、硬编码中文替换

使用场景: 老项目无痛改造国际化

核心步骤:

1. 检查并替换 isop-design 依赖
2. 配置 shared.module.ts 的 NG-ZORRO 国际化
3. 创建语言服务
4. 配置 AppModule
5. 替换 isop-design 引用为 isop-design-i18n
6. 替换硬编码中文为 translate 管道
7. 运行 Python 脚本生成翻译文件
8. 验证功能

参考文件

• i18n-core.md - 核心配置详细文档
• i18n-translate.md - 翻译文件管理详细文档（含 Python 脚本）
• i18n-ng-zorro.md - NG-ZORRO 适配详细文档
• i18n-migration.md - 老项目改造详细文档
• translate.json - 本地翻译字典模板（仅技能目录）

注意事项

版本兼容性

NG-ZORRO 版本差异

NG-ZORRO 7.x（本项目使用）:

providers: [{ provide: NZ_I18N, useValue: zh_CN }]

NG-ZORRO 8.x+:

providers: [provideNzI18n(zh_CN)]

常见问题

问题：NG-ZORRO 组件未切换语言

• 解决：确认 NzI18nService.setLocale() 已正确调用
• 检查 shared.module.ts 中的 NZ_I18N 配置

问题：翻译文件 key 不对应

• 解决：确保 zh.json 和 en.json 的 key 完全一致
• 使用 Python 脚本自动生成可避免此问题