Angular 18+ 高级教程 – 国际化 Internationalization i18n
介绍
先讲讲名词。
Internationalization 的缩写是 i18n,中文叫国际化。
Globalization 是 Internationalization 的同义词,都是指国际化。
Localization 的缩写是 l10n,中文叫本地化。
i18n vs l10n
一个国际化,一个本地化,它俩有什么区别,又有什么关系呢?
我们来看一个具体的例子
上图是苹果公司给美国人访问的官网,内容是 iPhone 16 Pro 的售价。
文字使用的是美式英文 (en-US),价钱使用的是美金 (USD)。
好,我们再看另外两张图
中国人看的是简体中文 (zh-Hans-CN) 和人民币 (CNY)。
日本人看的是日文 (ja-JP) 和日元 (JPY)。
三个网站销售的都是 iPhone 16 Pro。网站设计、排版都一模一样。
唯一的区别就是,网站会依据不同的国家,显示对应的语言和货币。
像这样一个网站,我们就可以说:苹果公司的官网支持国际化,同时也落实了本地化。
所谓支持国际化,意思是,网站架构有能力 handle 不同的语言,货币,时区。(设计,功能全都一样,就语言,货币,时区不同)
所谓落实本地化,意思是,网站不仅有能力 handle 不同的语言,货币,时区,而且它确实做出来了。
国际化指的是一个方案 / preparation,本地化则是具体的实现。
Angular i18n
Angular 有 built-in 的 i18n 方案。我们使用 Angular 就能做出像苹果公司那样支持国际化的网站。
本篇会 step by step 教 i18n,但不会讲解原理,也不会逛源码,开始吧 🚀。
参考
YouTube – Introduction to Internationalization in Angular
Docs – Angular Internationalization
Angular i18n step by step
一步一步来
创建一个新项目
ng new i18n --routing=false --ssr=false --skip-tests --style=scss
安装 @angular/localizepackage
ng add @angular/localize
提醒:是 ng add 不是 yarn add 哦。
它会做几件事:
-
package.json
安装了 @angular/localize package。
注意看,它是安装到了 devDependencies 里哦。
这也意味着,Angular i18n 是在 compile 阶段完成的,而不是在 runtime。
-
angular.json
多了一个 polyfill。我们刚说 i18n 发生在 compile 阶段,但也不完全。有一小部分还是需要 runtime 配合完成的。
这个 polyfill 就用在这些地方。
-
tsconfig
main.ts
还需要 TypeScript 配合,因为 runtime 会用到一些全局变量。
i18n Hello World
App Template
<h1 i18n>Hello World</h1>
注意看,这个 h1 有一个 "i18n" 标签 (attribute)。
它用来表示,这个 "Hello World" 待会儿需要被翻译成其它语言。
注:这里给的是最简单的例子,下面还会有比较复杂的玩法,我们先过一轮简单的。
Generate translation files
执行 command
ng extract-i18n --output-path src/locale
上面我们说了,Angular i18n 发生在 compile 阶段。
这个 command 会创建一个 folder (src/locale) 和一个 file (messages.xlf)
messages.xlf 是要给翻译小姐姐使用的。
它长这样
<?xml version="1.0" encoding="UTF-8" ?> <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2"> <!-- 1. source-language="en-US" 表示我们的 source code 写的是美式英文--> <file source-language="en-US" datatype="plaintext" original="ng2.template"> <body> <!-- 2. 每一句要翻译的文字都有一个独一无二的 ID 代号 --> <trans-unit id="4584092443788135411" datatype="html"> <!-- 3. source 就是我们要翻译的文字,也就是上面 App Template 里的 <h1 i18n>Hello World</h1> --> <source>Hello World</source> <context-group purpose="location"> <!-- 4. location 表明这个要翻译的文字,它来自哪一个 file 和哪一行 --> <context context-type="sourcefile">src/app/app.component.html</context> <context context-type="linenumber">1</context> </context-group> </trans-unit> </body> </file> </xliff>
Angular i18n 会扫描我们所有的文件,然后提取出需要翻译的部分,接着制作出 messages.xlf。
Translate
接着,我们把 messages.xlf 寄给翻译小姐姐。
她会替我们翻译出不同语言的版本,比如
messages-zh-Hans-CN.xlf (简体中文)
<?xml version="1.0" encoding="UTF-8" ?> <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2"> <file source-language="en-US" datatype="plaintext" original="ng2.template"> <body> <trans-unit id="4584092443788135411" datatype="html"> <source>Hello World</source> <!-- 1. 添加了简体中文 --> <target>你好,世界</target> <context-group purpose="location"> <context context-type="sourcefile">src/app/app.component.html</context> <context context-type="linenumber">1</context> </context-group> </trans-unit> </body> </file> </xliff>
messages.ja-JP.xlf (日文)
Setup angular.json and build application
翻译完后,就到了最后环节,ng build。
在 build 之前,我们需要修改一下 angular.json。
告知 Angular 原文、支持的译文、还有它们的文件路径。
"i18n": { // 原文是美式英文 "sourceLocale": "en-US", "locales": { // 支持简体中文 "zh-Hans-CN": { // 简体中文翻译文档在这儿 "translation": "src/locale/messages.zh-Hans-CN.xlf" }, // 支持日文 "ja-JP": { // 日文翻译文档在这儿 "translation": "src/locale/messages.ja-JP.xlf" } } },
还需要设置 projects.i18n.architect.options.localize: true
接着就可以 build 了
ng build --localize
Warning
它出现 warning 是因为我写的 locale ID 它不支持。
一个完整的 locale ID 应该是 "语言-国家",比如:zh-Hans 代表简体中文,CN 代表中国,但它只支持写语言 zh-Hans,-CN 不行。
相关 Github Issue – Unable to find zh-Hant-TW or zh-TW locale in @angular/common
不碍事儿,程序员不关心警告 (如果出现 error,请把国家 -CN 删掉,改成 zh-Hans 就好)。继续
一共 build 出了 3 个 folder "en-US"、"ja-JP"、"zh-Hans-CN"。
每一个 folder 里都有各自的 index.html,main.js 等等。
所有的代码都一摸一样,除了这一句
这一段符文是 unicode,对应的文字是
合起来就是 こんにちは世界,日文 Hello World 的意思。
这段是简体中文 Hello World 的 unicode。
Run application
打开 dist\i18n\browser,然后 Open with Live Server
效果
总结
以上就是 Angular i18n 最简单的 step by step 过程。
有很多细节和玩法我都还没有讲到,下面我们一个一个补上,Let's go 🚀。
i18n 标签 (attribute) 的日常用法
我们逐一看看 i18n 标签的各种日常使用方式。
i18n 习性 の tree shaking
Test Template 里有 i18n 标签。
但是,Test 组件没有被任何其它组件使用。
问:ng extract-i18n 会扫描到这个标签吗?
答:不会,因为扫描是有 tree shaking 概念的。
i18n 习性 の same word same translate
<h1 i18n>Hello World</h1> <h1 i18n>Hello World</h1>
两个 h1 有着一模一样的文字
它们会被放到同一个 <trans-unit> 里,只需要翻译一次。
Description, meaning, translate ID
<h1 i18n="description for this translate">Home</h1>
标签值可以用来描述要翻译的文字。
这行字会被填入 <trans-unit> 里。
除了 description,我们还可以加入 meaning / title。
<h1 i18n="meaning for this translate|description for this translate">Home</h1>
使用 pipe symbol | 作为分隔符,前面一段是 meaning,后一段是 description。
meaning 除了是一个描述以外,它还有 unique 功能。
我们举一个例子。
"Home" 这个英文字,可以被翻译成 "家",也可以被翻译成 "首页"。
具体要翻译成哪一个,还得看它的上下文。
也就是说,上一 part 我们提到的特性 -- same word same translate 这个潜规则是不能满足所有场景的。
当出现这种情况时,meaning 就可以用于区分相同的文字。
<h1 i18n="Header navigation|">Home</h1> <h1 i18n="A song name|">Home</h1>
效果
虽然文字相同,但是 meaning 不同,所以生成出了 2 个 <trans-unit>。
最后说一说 translate ID。
这个 ID 是 unique,Angular i18n 会依据文字和 meaning 自动生成对应的 ID。
如果我们想自己管理,自己 hardcode 写一个也可以。
<h1 i18n="@@id-1">Home</h1> <h1 i18n="@@id-2">Home</h1>
效果
虽然文字一样,meaning 一样,但 ID 不同,所以肯定会分开两个 <trans-unit>。
With HTML and interpolation
<p i18n>Copyright © 2024 <a href="/">{{ companyName() }}</a>. All rights reserved</p>
p 里头包含了 <a> 和 {{ interpolation }},这些都是 OK 的。
翻译的时候,针对文字翻就可以了,其它的不要乱改哦。
Translate attribute value
title、aria-label 这些 element attribute value 也可以被 translate。
<button i18n-aria-label aria-label="Example icon button with a vertical three dot icon" mat-icon-button> <mat-icon>more_vert</mat-icon> </button>
在 i18n 标签后面加上指定的 attribute name 作为 suffix 就可以了。
Without element
假如没有 element,就只有 text,那 i18n 标签要放哪里呢?
答案是 <ng-container>
<ng-container i18n>Hello World</ng-container>
ICU expressions
ICU expressions 被用于 conditional 翻译。
我们看例子来理解
handle conditional number – plural
<p i18n>{ peopleCount(), plural, =0 { no person } =1 { one person } other { {{ peopleCount() }} people } }</p>
它的语法是这样的
{ 参数一,参数二,参数三 }
参数一是 condition,peopleCount 是一个组件 property Signal<number>。
参数二有 2 个值可以填,一个是 plural,一个是 select。
plural 就是针对数字来做判断,select 则是针对 string 来做判断,select 下面会教,我们先看 plural。
参数三是不同数字下要呈现的文字。
在 runtime 阶段,假如 peopleCount = 0,那就会显示 "no person"。
假如 peopleCount = 1,那就会显示 "one person"。
peopleCount = 其它数字,则会显示 "{{ peopleCount() }} people"。
用 @if 实现的话,长这样
<p i18n> @if(peopleCount() === 0) { no person } @else if (peopleCount() === 1) { one person } @else { {{ peopleCount() }} people } </p>
显然使用 ICU expressions 会更精简一些。(但 plural 的表达式是有限的,它只能写 =1,=5,不可以写 >5,<3 大于小于这些都不支持)
翻译文档长这样
同样的,我们只翻译文字就好,其它的不要乱改。
handle conditional string – select
select 和 plural 结构是一样的,只是前者针对 string,后者针对 number。
export class AppComponent { readonly gender = signal<'male' | 'female' | null>(null); }
<p i18n>{ gender(), select, male { male } female { female } other { other } }</p>
当 gender 是 "male" 时,显示 "男"。
当 gender 是 "female" 时,显示 "女"。
当 gender 不是 "male" 也不是 "female" (e.g. null) 时,显示 "其它"。
Translate in script
上面我们讲的都是在 HTML 里做翻译。
如果我的文字写在 script 里头呢?如何打上 i18n 标签?
答案是使用 $localize
export class AppComponent { constructor() { const value = $localize`Hello World`; console.log(value); } }
$localize 是一个全局变量
main.ts 引入的类型就是为了它
$localize 等价于 HTML 的 i18n 标签,用法也大同小异,生成出来的翻译文档也是一样的。
下面这个是 meaning, description, id 的写法
const value = $localize`:meaning|description@@id:Hello World`;
用 : 分号做分割。
唯一比较大的区别是,$localize 不支持 ICU expressions。
假如我们需要 conditional 就用一般的 if else swtich 来完成就可以了,比如:
// <p i18n>{ peopleCount(), plural, =0 { no person } =1 { one person } other { {{ peopleCount() }} people } }</p> const peopleCount = signal(0); const value = peopleCount() === 0 ? $localize`no person` : peopleCount() === 1 ? $localize`one person` : $localize`${peopleCount()} people`; console.log(value);
总结
以上便是 i18n 标签的日常用法。
ng serve for i18n application
上面我们讲的都是 ng build 最终的发布。
那在 development 阶段,ng serve 是否可以开启 i18n application?
可以,但只能选定其中一个 locale。
去 angular.json 指定 locale
把原本的 true,改成 array,array 里只能放一个 locale。
接着 ng serve 就可以了。
Get current locale ID
通过 inject LOCALE_ID,我们可以获知当前是什么 locale。
export class AppComponent { constructor() { console.log(inject(LOCALE_ID)); // zh-Hans } }
在没有 i18n 的情况下,它的默认值是 "en-US" (提醒:它不是依据游览器 settings 哦,它是 hardcode en-US)。
关于 base href
所有 build 出来的 index.html 都带有 <base href="/locale/">
<base href> 有啥用,可以看这篇。
为什么 Angular i18n 要在 base href 加上 locale 呢?
因为它想让我们更方便的部署,我拿 ASP.NET Core 来举例。
ASP.NET Core 常规做法是把 ng build 的产物通通放到 wwwroot folder 里
然后在 program.cs 做 routing
简单说就是,当用户访问 /zh-Hans-CN/**/* 就会访问到 /zh-Hans-CN/index.html。
index.html
polyfills.js 结合 base href 后的路径是 /en-US/polyfills-js
从 wwwroot 往下 "\en-US\polyfills.js",这个路径是正确的。
假如 base href 是 "/",那路径就变成了 "/polyfills.js"。
那这个文档就要在 wwwroot\polyfills.js 才能拿到。
由此可见,加上 base href 会比较合理方便。
如果我们不喜欢它自作主张,也可以去 angular.json 里配置
这样 ng build 出来的 index.html 就变成 <base href="/" > 了。
DatePipe with Locale
DatePipe 会依据 locale 而变化,比如
<p>{{ today() | date }}</p>
在 zh-Hans 的情况下,它的效果是
用 formatDate 也是同理
constructor() { const today = new Date(); const format = 'mediumDate'; const locale = inject(LOCALE_ID); console.log(formatDate(today, format, locale)); // 2024年9月17日 }
formatDate 底层是如何做到 translate 的呢?
首先,它并不是使用游览器原生的 Intl,Angular 自己写了一套逻辑 (为什么 Angular 要自己写一套,不使用原生的?我不太清楚,可能是当时 Inlt 支持度还不高?不管怎样,目前我的感觉是,以后 Angular 很可能会改用原生的 Intl)。
通过 ɵfindLocaleData (formatDate 底层用的就是它) 我们可以拿到许多翻译内容
import { ɵfindLocaleData } from '@angular/core'; constructor() { console.log(ɵfindLocaleData('zh-Hans')); // 注:这里不能是 zh-Hans-CN 哦,因为 Angular 的 locale data 没有 zh-Hans-CN 只有 zh-Hans /.\ }
效果
里面包含了 formatDate 需要用到的日期格式和语言。
我们再试试看 find 其它 locale
console.log(ɵfindLocaleData('ja'));
报错了
原因很简单,Angular 默认是不会加载所有 locale 资料的。zh-Hans 之所以可以 find 到是因为我们做了 i18n,并指定了 ng serve 是 zh-Hans。
它不自动加载,但我们可以手动替它加载。
import { registerLocaleData, } from '@angular/common'; import jaLocaleData from '@angular/common/locales/ja'; registerLocaleData(jaLocaleData, 'ja');
import 日文资料,然后 register 到 localeData 里。
这样就可以 find 到了
console.log(ɵfindLocaleData('ja'));
效果
CurrencyPipe with Locale
不同国家使用不同的货币,locale 除了语言,日期格式,当然也包括货币。
上一 part,我们拿 locale data 查看时,其实货币资料也包含在内。
我们来试试 CurrencyPipe
<p>{{ 500 | currency }}</p>
效果
夷...怎么不是人民币❓🤔
因为 Github Issue – Currency pipe and locale
简单说就是,他们觉得自动换 currency symbol 但不换 value 是不合理的,所以干脆把职责全交给开发人员。
我们有两种方法可以做到 currency pipe with locale。
第一种是使用 getLocaleCurrencyName/Code/Symbol 函数
import { getLocaleCurrencyCode, getLocaleCurrencyName, getLocaleCurrencySymbol } from '@angular/common'; const code = getLocaleCurrencyCode('zh-Hans'); const name = getLocaleCurrencyName('zh-Hans'); const symbol = getLocaleCurrencySymbol('zh-Hans'); console.log([code, name, symbol]); // ['CNY', '人民币', '¥']
这三个函数底层用的是 ɵfindLocaleData 函数,这个我们上一 part 讲解过了。
另外,getLocaleCurrencyName/Code/Symbol 目前已是废弃的状态。
Angular 建议我们使用原生的 Intl 去实现 name 和 symbol
getLocaleCurrencyCode 无法用 Intl 去实现,Angular 的建议是让我们自己写一个 mapping list 😮。
第二种方法就是听从 Angular 的建议,使用原生的 Intl。
const locale = 'zh-Hans'; const code = getLocaleCurrencyCode(locale)!; // Intl 没法从 zh-Hans 生成 CNY,我们只能自己写 mapping list 或者继续用它废弃的接口 const symbolFormatter = new Intl.NumberFormat(locale, { style: 'currency', currency: code, currencyDisplay: 'symbol' }); const symbol = symbolFormatter.formatToParts(0).find(part => part.type === 'currency')!.value; // ¥ const displayNames = new Intl.DisplayNames([locale], { type: 'currency' }); const name = displayNames.of(code); console.log([code, symbol, name]); // ['CNY', '¥', '人民币']
总结
本篇简单介绍了 Angular i18n 方案,没有深入讲解原理,也没有逛源码。
因为我个人从来没有在项目中使用过它,希望未来有机会吧,到时再深入研究研究。
另外,日常项目中,我使用的是 ASP.NET Core – Globalization & Localization。
对比它俩,最大的区别是,ASP.NET Core 的翻译文档是拆散的,每一个页面,甚至每一个组件都有一个翻译文档。
而不像 Angular 那样把整个项目每一个组件资料通通放到了同一个文档里。
感觉 Angular 维护起来可能会比较乱,尤其是当网站或应用程序内容有更动的时候。
目录
上一篇 Angular 18+ 高级教程 – Memory leak, unsubscribe, onDestroy
想查看目录,请移步 Angular 18+ 高级教程 – 目录
喜欢请点推荐👍,若发现教程内容以新版脱节请评论通知我。happy coding 😊💻