This technique works for any attribute of any element.
这个技巧适用于任何元素上的任何属性。
You also can assign a meaning, description, and id with the i18n-x="<meaning>|<description>@@<id>"
syntax.
你也同样可以使用 i18n-x="<meaning>|<description>@@<id>"
语法来指定一个含义和描述。
Different languages have different pluralization rules.
不同的语言有不同的单复数规则。
Suppose that you want to say that something was "updated x minutes ago". In English, depending upon the number of minutes, you could display "just now", "one minute ago", or "x minutes ago" (with x being the actual number). Other languages might express the cardinality differently.
假设你要说某些东西“updated x minutes ago(在 x 分钟前修改了)”。 在英语中,根据分钟数,可能要显示为 "just now"、"one minute ago" 或 "x minutes ago"(这里的 x 是实际的数量)。 而在其它语言中则可能会有不同的基数规则。
The example below shows how to use a plural
ICU expression to display one of those three options based on when the update occurred:
下面这个例子示范了如何使用 ICU 表达式 plural
来根据这次修改发生的时间显示这三个选项之一:
The first parameter is the key. It is bound to the component property (minutes
), which determines the number of minutes.
第一个参数是 key。它绑定到了组件中表示分钟数的 minutes
属性。
The second parameter identifies this as a plural
translation type.
第二个参数表示这是一个 plural
(复数)翻译类型。
The third parameter defines a pluralization pattern consisting of pluralization categories and their matching values.
第三个参数定义了一组复数表示模式,这个模式由复数类别和它们所匹配的值组成。
This syntax conforms to the ICU Message Format as specified in the CLDR pluralization rules.
Pluralization categories include (depending on the language):
复数类别包括(取决于语言):
=0 (or any other number)
=0 (或其它数字)
zero
zero(零)
one
one(一个)
two
two(两个)
few
few(少数)
many
many(很多)
other
other(其它)
After the pluralization category, put the default English text in braces ({}
).
复数类别之后的括号({}
)中是默认的英语文本。
In the example above, the three options are specified according to that pluralization pattern. For talking about about zero minutes, you use =0 {just now}
. For one minute, you use =1 {one minute}
. Any unmatched cardinality uses other {{{minutes}} minutes ago}
. You could choose to add patterns for two, three, or any other number if the pluralization rules were different. For the example of "minute", only these three patterns are necessary in English.
在上面的例子中,这三个选项都是根据复数模式来指定的。要说零分钟,就用 =0 {just now}
。一分钟就用 =1 {one minute}
。 无法匹配的数量就用 other {{{minutes}} minutes ago}
。如果复数规则与此不同,你还可以为两个、三个火任意数量添加更多的模式。对于这个 “minute” 的例子,英语中只要这三种模式就够了。
You can use interpolations and html markup inside of your translations.
你可以在翻译结果中使用插值表达式和 HTML 标记。
If your template needs to display different text messages depending on the value of a variable, you need to translate all of those alternative text messages.
如果你的模板中需要根据某个变量的值显示出不同的文本消息,你还需要对所有这些候选文本进行翻译。
You can handle this with a select
ICU expression. It is similar to the plural
ICU expressions except that you choose among alternative translations based on a string value instead of a number, and you define those string values.
你可以使用 ICU 表达式 select
来翻译这些。它与 ICU 表达式 plural
类似,只是你要根据一个字符串值而不是数字来选择这些候选翻译文本,而这些字符串值是你自己定义的。
The following format message in the component template binds to the component's gender
property, which outputs one of the following string values: "m", "f" or "o". The message maps those values to the appropriate translations:
组件模板中的下列消息格式绑定到了组件的 gender
属性,这个属性的取值是 "m" 或 "f" 或 "o"。 这个消息会把那些值映射到适当的翻译文本:
You can also nest different ICU expressions together, as shown in this example:
你也可以把不同的 ICU 表达式嵌套在一起,比如:
Use the ng xi18n
command provided by the CLI to extract the text messages marked with i18n
into a translation source file.
使用 CLI 提供的 ng xi18n
命令来将带 i18n
标记的文本消息提取到一个翻译源文件中。
Open a terminal window at the root of the app project and enter the ng xi18n
command:
在应用的项目根目录打开一个终端窗口,并输入 ng xi18n
命令:
By default, the tool generates a translation file named messages.xlf
in the XML Localization Interchange File Format (XLIFF, version 1.2).
本工具默认会生成一个名叫 messages.xlf
的翻译文件,格式为XML本土化互换文件格式(XLIFF, version 1.2)。
If you don't use the CLI, you have two options:
如果你不使用 CLI,那么你有两个选择:
You can use the ng-xi18n
tool directly from the @angular/compiler-cli
package. For more information, see i18n in the CLI documentation.
你可以直接使用来自 @angular/compiler-cli
包中的 ng-xi18n
工具。更多信息,参见 CLI 文档中的 i18n 部分。
You can use the CLI Webpack plugin AngularCompilerPlugin
from the @ngtools/webpack
package. Set the parameters i18nOutFile
and i18nOutFormat
to trigger the extraction. For more information, see the Angular Ahead-of-Time Webpack Plugin documentation.
你可以使用 CLI 中来自 @ngtools/webpack
包中的 Webpack 插件。设置其 i18nOutFile
和 i18nOutFormat
参数进行触发。 更多信息,参见 Angular AOT Webpack 插件文档。
Angular i18n tooling supports three translation formats:
Angular 的 i18n 工具支持三种翻译格式:
XLIFF 1.2 (default)
XLIFF 1.2 (默认)
XLIFF 2
You can specify the translation format explicitly with the --i18nFormat
flag as illustrated in these example commands:
你可以使用 --i18nFormat
来明确指定想用的格式,范例如下:
The sample in this guide uses the default XLIFF 1.2 format.
本章的范例使用默认的 XLIFF 1.2 格式。
XLIFF files have the extension .xlf. The XMB format generates .xmb source files but uses .xtb (XML Translation Bundle: XTB) translation files.
XLIFF 文件带有 .xlf 扩展名。XMB 格式会生成 .xmb 格式的源文件,但使用 .xtb(XML 翻译包)格式的翻译文件。
You can specify the output path used by the CLI to extract your translation source file with the parameter --output-path
:
你还可以使用 --output-path
参数在 CLI 提取翻译源文件时指定输出路径:
You can change the name of the translation source file that is generated by the extraction tool with the parameter --outFile
:
你还可以使用 --out-file
参数来为提取工具生成的翻译源文件改名:
You can specify the base locale of your app with the parameter --i18n-locale
:
你还可以使用 --i18n-locale
参数来指定应用的基本地区:
The extraction tool uses the locale to add the app locale information into your translation source file. This information is not used by Angular, but external translation tools may need it.
该提取工具会用这个地区标识把本地化信息添加到你的翻译源文件中。这个信息对 Angular 来说没用,不过外部翻译工具可能会需要它。
The ng xi18n
command generates a translation source file named messages.xlf
in the project src
folder.
ng xi18n
命令会在项目根目录生成一个名为 messages.xlf
的翻译源文件。
The next step is to translate this source file into the specific language translation files. The example in this guide creates a French translation file.
下一步是将英文模板文本翻译到指定语言的翻译文件。 这个例子中创建了一个法语翻译文件。
Most apps are translated into more than one other language. For this reason, it is standard practice for the project structure to reflect the entire internationalization effort.
大多数应用都要被翻译成多种其它语言,因此,为全部国际化工作做适当的调整项目目录结构是一种标准实践。
One approach is to dedicate a folder to localization and store related assets, such as internationalization files, there.
方法之一是为本土化和相关资源(比如国际化文件)创建一个专门的目录。
Localization and internationalization are different but closely related terms.
本土化和国际化是不同但是很相近的概念。
This guide follows that approach. It has a locale
folder under src/
. Assets within that folder have a filename extension that matches their associated locale.
本指南遵循了这种方式。在src/
目录下,有一个专门的locale
目录,该目录中的文件都带一个与相关地区匹配的扩展名。
For each translation source file, there must be at least one language translation file for the resulting translation.
对每个翻译文件来说,都必须至少有一个语言的翻译文件作为翻译结果。
For this example:
对于这个例子:
Make a copy of the messages.xlf
file.
复制一份 messages.xlf
文件。
Put the copy in the locale
folder.
把这个副本放进 locale
目录下。
Rename the copy to messages.fr.xlf
for the French language translation.
把这个副本改名为 messages.fr.xlf
以作为法语翻译结果。
If you were translating to other languages, you would repeat these steps for each target language.
如果你要翻译为其他语言,那就为每一个目标语种重复上述步骤。
In a large translation project, you would send the messages.fr.xlf
file to a French translator who would enter the translations using an XLIFF file editor.
在现实世界中,messages.fr.xlf
文件会被发给法语翻译,他们会使用某种 XLIFF 文件编辑器来翻译它。
This sample file is easy to translate without a special editor or knowledge of French.
你不需要任何编辑器或者法语知识就可以轻易的翻译本例子文件。
Open messages.fr.xlf
and find the first <trans-unit>
section:
打开 messages.fr.xlf
并找到第一个 <trans-unit>
区:
<trans-unit id="introductionHeader" datatype="html"> <source>Hello i18n!</source> <note priority="1" from="description">An introduction header for this sample</note> <note priority="1" from="meaning">User welcome</note> </trans-unit> This XML element represents the translation of the
<h1>
greeting tag that you marked with thei18n
attribute earlier in this guide.这个 XML 元素表示前面你加过
i18n
属性的那个打招呼用的<h1>
标签。Note that the translation unit
id=introductionHeader
is derived from the customid
that you set earlier, but without the@@
prefix required in the source HTML.注意这个
id=introductionHeader
的翻译单元是来自你以前设置过的自定义id
的。但是并没有源 HTML 所需的@@
前缀。
Duplicate the <source/>
tag, rename it target
, and then replace its content with the French greeting. If you were working with a more complex translation, you could use the the information and context provided by the source, description, and meaning elements to guide your selection of the appropriate French translation.
复制 <source/>
标记,把它改名为 target
,并把它的内容改为法语版的 “greeting”。 如果你要做的是更复杂的翻译,可能会使用由源文本、描述信息和含义等提供的信息和上下文来给出更恰当的法语翻译。
<trans-unit id="introductionHeader" datatype="html"> <source>Hello i18n!</source> <target>Bonjour i18n !</target> <note priority="1" from="description">An introduction header for this sample</note> <note priority="1" from="meaning">User welcome</note> </trans-unit>
Translate the other text nodes the same way:
用同样的方式翻译其它文本节点:
<trans-unit id="ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3" datatype="html"> <source>I don't output any element</source> <target>Je n'affiche aucun élément</target> </trans-unit> <trans-unit id="701174153757adf13e7c24a248c8a873ac9f5193" datatype="html"> <source>Angular logo</source> <target>Logo d'Angular</target> </trans-unit>
The Angular i18n tools generated the ids for these translation units. Don't change them. Each id
depends upon the content of the template text and its assigned meaning. If you change either the text or the meaning, then the id
changes. For more information, see the translation file maintenance discussion.
Angular 的 i18n 工具会为这些翻译单元生成一些 id,不要修改它们。 每个 id
都是根据模板文本的内容及其含义来生成的。 无论你修改了文本还是含义,它们的 id
都会改变。 要了解更多信息,参见 关于翻译文件可维护性的讨论。
Plural and select ICU expressions are extracted separately, so they require special attention when preparing for translation.
复数和选择的 ICU 表达式都是分别提取的,所以在准备翻译时,它们需要格外注意。
Look for these expressions in relation to other translation units that you recognize from elsewhere in the source template. In this example, you know the translation unit for the select
must be just below the translation unit for the logo.
你要从原始模板中其它地方识别出来的翻译单元来找到这些表达式之间的联系。 比如在这个例子中,你知道 select
一定会出现在 logo 的翻译单元的紧下方。
To translate a plural
, translate its ICU format match values:
要翻译一个复数,就要翻译它的 ICU 格式中匹配的值:
You can add or remove plural cases, with each language having its own cardinality. (See CLDR plural rules.)
你可以添加或删除复数的情况,每种语言都有自己的基数规则。(参见 CLDR 复数规则)。
Below is the content of our example select
ICU expression in the component template:
下面是组件模板中的 ICU 表达式 select
的例子:
The extraction tool broke that into two translation units because ICU expressions are extracted separately.
提取工具会把它拆成两个翻译单元,因为 ICU 表达式是分别提取的。
The first unit contains the text that was outside of the select
. In place of the select
is a placeholder, <x id="ICU">
, that represents the select
message. Translate the text and move around the placeholder if necessary, but don't remove it. If you remove the placeholder, the ICU expression will not be present in your translated app.
第一个单元包含 select
之外的文本。 这里的 select
是一个占位符 <x id="ICU">
,用来表示 select
中的消息。 翻译这段文本,如果需要就把占位符放在那里,但不要删除它。 如果删除了占位符,ICU 表达式就不会出现在翻译后的应用中。
The second translation unit, immediately below the first one, contains the select
message. Translate that as well.
第一个翻译单元的紧下方就是第二个翻译单元,包含 select
中的消息。照样翻译它。
Here they are together, after translation:
在翻译之后,它们会放在一起:
A nested expression is similar to the previous examples. As in the previous example, there are two translation units. The first one contains the text outside of the nested expression:
嵌套的表达式和前一节没有什么不同。就像上一个例子中那样,这里有两个翻译单元。 第一个包含嵌套表达式之外的文本:
The second unit contains the complete nested expression:
第二个包含完整的嵌套表达式:
And both together:
放在一起时:
The entire template translation is complete. The next section describes how to load that translation into the app.
整个模板的翻译就完成了。下一节会讲如何翻译结果加载到应用程序中。
The sample app and its translation file are now as follows:
下面是例子应用及其翻译文件:
To merge the translated text into component templates, compile the app with the completed translation file. Provide the Angular compiler with three translation-specific pieces of information:
要把已经翻译的文件合并到组件模板,就要用翻译过的文件编译应用。 为 Angular 编译器提供三种与翻译有关的信息:
The translation file.
翻译文件
The translation file format.
翻译文件的格式
The locale (fr
or en-US
for instance).
目标地区(比如 fr
或 en-US
)。
The compilation process is the same whether the translation file is in .xlf
format or in another format that Angular understands, such as .xtb
.
无论翻译文件是 .xlf
还是 Angular 支持的其它格式(比如 .xtb
),其编译过程都是一样的。
How you provide this information depends upon whether you compile with the JIT compiler or the AOT compiler.
你如何提供这些信息取决于你使用的是JIT(即时)编译器还是AOT(预先)编译器。
With AOT, you pass the information as a configuration
使用AOT时,用配置项传入这些信息。
With JIT, you provide the information at bootstrap time.
使用JIT时,在引导时提供。
The AOT (Ahead-of-Time) compiler is part of a build process that produces a small, fast, ready-to-run application package.
AOT(预先)编译器是构建过程的一部分,它可以生成又小又快,直接可用的应用包。
When you internationalize with the AOT compiler, you must pre-build a separate application package for each language and serve the appropriate package based on either server-side language detection or url parameters.
当你使用 AOT 编译器进行国际化时,你必须为每种语言预先编译一个独立的应用包,并且依靠服务端语言检测或 URL 参数来找出合适的包。
You also need to instruct the AOT compiler to use your translation configuration. To do so, you configure the translation with three options in your angular.json
file.
你还要指示 AOT 编译器使用你的翻译配置,要这么做,你就要在 angular.json
文件中使用三个选项来配置翻译信息。
i18nFile
: the path to the translation file.
i18nFile
: 翻译文件的路径。
i18nFormat
: the format of the translation file.
i18nFormat
: 翻译文件的格式。
i18nLocale
: the locale id.
i18nLocale
: 地区的 id.
You then pass the configuration with the ng serve
or ng build
commands. The example below shows how to serve the French language file created in previous sections of this guide:
你可以通过 ng serve
或 ng build
命令来传入这些配置项。 下面的例子演示了如何使用前面部分创建的法语文件来启动开发服务器:
For production builds, you define a separate production-fr
build configuration in your angular.json
.
The same configuration options can also be provided through the CLI with your existing production
configuration.
The JIT compiler compiles the app in the browser as the app loads. Translation with the JIT compiler is a dynamic process of:
JIT(即时)编译器在应用程序加载时,在浏览器中编译应用。 在使用 JIT 编译器的环境中翻译是一个动态的流程,包括:
Importing the appropriate language translation file as a string constant.
把合适的语言翻译文件导入成一个字符串常量
Creating corresponding translation providers for the JIT compiler.
为 JIT 编译器创建相应的翻译提供商。
Bootstrapping the app with those providers.
使用这些提供商来启动应用。
Three providers tell the JIT compiler how to translate the template texts for a particular language while compiling the app:
三种提供商帮助 JIT 编译在编译应用时,将模板文本翻译到某种语言:
TRANSLATIONS
is a string containing the content of the translation file.
TRANSLATIONS
是含有翻译文件内容的字符串。
TRANSLATIONS_FORMAT
is the format of the file: xlf
, xlf2
, or xtb
.
TRANSLATIONS_FORMAT
是文件的格式: xlf
、xlif
或 xtb
。
LOCALE_ID
is the locale of the target language.
LOCALE_ID
是目标语言的语言环境。
The Angular bootstrapModule
method has a second compilerOptions
parameter that can influence the behavior of the compiler. You can use it to provide the translation providers:
在下面的 src/app/i18n-providers.ts
文件的 getTranslationProviders()
函数中,根据用户的语言环境和对应的翻译文件构建这些提供商:
Then provide the LOCALE_ID
in the main module:
然后在主文件包中提供 LOCALE_ID
:
By default, when a translation is missing, the build succeeds but generates a warning such as Missing translation for message "foo"
. You can configure the level of warning that is generated by the Angular compiler:
默认情况下,如果缺少了某个翻译文件,构建工具会成功但给出警告(如Missing translation for message "foo"
)。你可以配置 Angular 编译器生成的警告级别:
Error: throw an error. If you are using AOT compilation, the build will fail. If you are using JIT compilation, the app will fail to load.
Error(错误):抛出错误,如果你使用的是 AOT 编译器,构建就会失败。如果使用的是 JIT 编译器,应用的加载就会失败。
Warning (default): show a 'Missing translation' warning in the console or shell.
Warning(警告 - 默认):在控制台中显示一条 “Missing translation” 警告。
Ignore: do nothing.
Ignore(忽略):什么也不做。
You specify the warning level in the configurations
section your Angular CLI build configuration. The example below shows how to set the warning level to error:
你可以在 Angular CLI 构建配置的 configurations
区指定警告级别。下面这个例子展示了如何把警告级别设置为 error
:
If you use the JIT compiler, specify the warning level in the compiler config at bootstrap by adding the 'MissingTranslationStrategy' property. The example below shows how to set the warning level to error:
如果你要使用 JIT 编译器,就在启动时往编译器的配置中添加一个 MissingTranslationStrategy
属性来指定警告级别。下面的例子示范了如何把警告级别设置为 error
: