如何使用localize为Angular Library添加本地化功能？

AI 小北

2026-10-1

报错原因

Ivy extraction requires the '@angular/localize' package
该报错是因为Ivy模式下的i18n提取工具无法找到已正确安装和初始化的@angular/localize依赖，或项目配置未开启对应的i18n提取支持。

解决步骤

第一步：确保@angular/localize版本与项目Angular核心版本完全匹配，执行安装命令：
```
npm install @angular/localize@$(npm show @angular/core version) --save
```
如需指定版本安装，将命令中的版本替换为你的Angular主版本即可，例如Angular 16版本可修改为@angular/localize@16。
第二步：在项目根目录的polyfills.ts文件顶部添加引入代码，完成包的初始化：
```
import '@angular/localize/init';
```
第三步：修改angular.json中你的自定义库对应的配置项：
1. 找到projects.<你的库名>.architect.build.options节点，添加配置：
```
"localize": true
```
2. 在projects.<你的库名>.architect下新增i18n提取节点：
```
"i18n": {
  "builder": "@angular-devkit/build-angular:extract-i18n",
  "options": {
    "browserTarget": "<你的库名>:build",
    "outputPath": "src/locale"
  }
}
```
3. 按需配置源语言和目标语言，可在projects.<你的库名>下新增i18n全局配置：
```
"i18n": {
  "sourceLocale": "zh-CN",
  "locales": {
    "en-US": "src/locale/messages.en-US.xlf"
  }
}
```
第四步：修改tsconfig.json（或库专属的tsconfig.lib.json）的配置：
在compilerOptions.types数组中添加localize的类型声明，避免编译和提取时报类型错误：
```
"types": ["@angular/localize"]
```
同时确认angularCompilerOptions下已开启Ivy（Angular 9+默认开启，老项目迁移需手动配置）：
```
"angularCompilerOptions": {
  "enableIvy": true
}
```
第五步：执行提取命令时指定库项目名，避免默认提取主应用内容：
```
ng i18n <你的库名> --output-path src/locale
```

注意：库代码中需要提前标记需要翻译的内容才能被正常提取，模板中用i18n属性标记静态文本，TS代码中用$localize标记动态文本。

如果执行后仍报错，可先清除node_modules文件夹和package-lock.json/yarn.lock文件，重新安装依赖后再执行提取操作。

内容的提问来源于stack exchange，提问作者Muhammad Usman