From 780860348999719972ca4366101b16789e3e7cd7 Mon Sep 17 00:00:00 2001 From: Zhimin YE Date: Thu, 20 Oct 2016 10:59:05 +0100 Subject: [PATCH] translate: i18n done. --- public/docs/ts/latest/cookbook/i18n.jade | 182 ++++++++++++++++++++++- 1 file changed, 178 insertions(+), 4 deletions(-) diff --git a/public/docs/ts/latest/cookbook/i18n.jade b/public/docs/ts/latest/cookbook/i18n.jade index f49ab93d22..c8536740d9 100644 --- a/public/docs/ts/latest/cookbook/i18n.jade +++ b/public/docs/ts/latest/cookbook/i18n.jade @@ -196,7 +196,7 @@ code-example(language="sh" class="code-shell"). By default the tool generates a translation file named **`messages.xlf`** in the XML Localisation Interchange File Format (XLIFF, version 1.2). - 工具默认生成一个名为**`messages.xlf`**的翻译文件，格式为XML本地化互换文件格式(XLIFF, version 1.2)。 + 工具默认生成一个名为**`messages.xlf`**的翻译文件，格式为XML本土化互换文件格式(XLIFF, version 1.2)。 code-example(language="sh" class="code-shell"). ./node_modules/.bin/ng-xi18n --i18nFormat=xmb @@ -246,64 +246,110 @@ a#translate :marked ## Translate _le message textuel_ + ## 翻译 + The `ng-xi18n` command generated a translation source file in the project root folder named `messages.xlf`. The next step is to translate the English language template text into the specific language translation files. The cookbook sample creates a French translation file. + `ng-xi18n`命令在项目根目录生成一个名为`messages.xlf`的翻译源文件。 + 下一步是将英文模板文本翻译到目标语言的翻译文件。 + 本烹饪书创建了一个法语翻译文件。 + a#localization-folder :marked ### Create a localization folder + ### 新建一个本土化目录 + You will probably translate into more than one other language so it's a good idea for the project structure to reflect your entire internationalization effort. + + 你很有可能翻译到更多其他语言，所以为全部国际化工作做适当的调整项目目录结构是理所当然的。 One approach is to dedicate a folder to localization and store related assets (e.g. internationalization files) there. + + 其中一种方法是为本土化和相关资源（比如国际化文件）创建一个专门的目录。 .l-sub-section :marked Localization and internationalization are different but closely related terms. + + 本土化和国际化是不同但是很相近的概念。 :marked This sample follows that suggestion. It has `locale` folder immediately under the project root. Assets within the folder carry a filename extension that matches a language-culture code from a well-known codeset. + 本例遵循这个建议。项目根目录有`locale`目录。 + 目录的资源的文件名都匹配有一个语言代码后缀，参见语言代码对照表. + Move `messages.xlf` into the `locale` folder where it will become the source for all language-specific translations. Then make a copy for the French language named `messages.fr.xlf` . + 将`messages.xlf`移到`locale`目录，这里将存放所有语言与翻译相关的文件。 + 然后为法语复制这个文件，名为`messages.fr.xlf`。 + Follow the same convention for each target language. + 对所有目标语言都采用同样的约定。 + ### Translate + + ### 翻译 + In the real world, you send the `messages.fr.xlf` file to a French translator who would fill in the translations using one of the many XLIFF file editors. + 在现实世界中，`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 `` section: + 我们不需要任何编辑器或者法语知识就可以轻易的翻译本例子文件。 + 打开`messages.fr.xlf`并找到``节点： + +makeExample('cb-i18n/ts/locale/trans-unit.html', '', 'locale/messages.fr.xlf ()')(format=".") :marked This XML element represents the translation of the `

` greeting tag you marked with the `i18n` attribute. + + 这个XML元素代表了你使用`i18n`属性标记的`

`问候语标签的翻译。 Using the _source_, _description_, and _meaning_ elements to guide your translation, replace the `` tag with the French greeting: + + 翻译中利用_source_、_description_和_meaning_元素的信息，替换``标签为法语问候语： + +makeExample('cb-i18n/ts/locale/messages.fr.xlf.html', 'trans-unit', 'locale/messages.fr.xlf (, after translation)')(format=".") :marked Note that the `id` is generated by the tool. Don't touch it. Its value depends on the content of the message and its assigned meaning. Change either factor and the `id` changes as well. + + 注意`id`是工具生成的。不要修改它。 + 它的值取决于两个因素：信息的内容和其指定的含义。 + 改变任何一个因素，`id`就会改变。 .alert.is-helpful :marked Repeat the extraction process whenever you add new app messages or edit existing ones. Be careful not to lose the previous translations. Specialized software can help manage the change process. + 每当你添加或者编辑应用信息，重复提取流程。 + 小心不要丢失之前的翻译。专门的软件可以帮助你管理变更流程。 + #app-pre-translation :marked ### The app before translation + + ### 翻译前的应用程序 After the previous steps, the sample app _and_ its translation file are as follows: + 如下所示，是完成前面的步骤后的例子应用**和**它的翻译文件： + +makeTabs(` cb-i18n/ts/app/app.component.html, cb-i18n/ts/app/app.component.ts, @@ -323,136 +369,264 @@ a#merge :marked ## Merge the completed translation file + ## 合并已经翻译的文件 + To merge the translated text into component templates, you compile the application with the completed translation file. The process is the same whether the file is in `.xlf` format or in one of the other formats (`.xlif` and `.xtb`) that Angular understands. + + 要合并已经翻译的文件到组件模板，使用翻译过的文件编译应用。 + 不管文件是`.xlf`格式还是其他Angular接受的格式（`.xlif`和`.xtb`），流程是一样的。 You provide the Angular compiler with three new pieces of information: + + 你为Angular编译器提供下列三种新信息： + * the translation file - * the translation file format + + * 翻译文件 + + * the translation file format + + * 翻译文件的格式 + * the _Locale ID_ (`fr` or `en-US` for instance) + + * 目标_语言环境ID_ + (例如`fr`或`en-US`) _How_ you provide this information depends upon whether you compile with the JiT (_Just-in-Time_) compiler or the AoT (_Ahead-of-Time_) compiler. + + 你如何提供这些信息取决于你使用的是JiT（即时）编译器还是AoT（预先）编译器。 * with [JiT](#jit), you provide the information at bootstrap time. - * with [AoT](#aot), you pass the information as `ngc` options. + + * 使用[JiT](#jit)时，在引导时提供 + + * with [AoT](#aot), you pass the information as `ngc` options. + + * 使用[AoT](#aot)时，在`ngc`命令的选项里提供 a#jit .l-main-section :marked ### Merge with the JiT compiler + + ### 用JiT编译器合并 The JiT (_Just-in-Time_) compiler compiles the application in the browser as the application loads. Translation with the JiT compiler is a dynamic process of ... + JiT（即时）编译器在应用程序加载时，在浏览器中编译应用。 + 在使用JiT编译器的环境中翻译是一个动态的流程，包括： + 1. determining the language version for the current user, + + 1. 决定当前用户的语言， + 2. importing the appropriate language translation file as a string constant, + + 2. 导入合适的语言翻译文件到一个字符串常量， + 3. creating corresponding translation providers to guide the JiT compiler, + + 3. 新建对应的翻译提供商来指导JiT编译器， + 4. bootstrapping the application with those providers. + 4. 使用这些提供商来启动应用。 + Open `index.html` and revise the launch script as shown here: + + 打开`index.html`并这样修改加载脚本： + +makeExample('cb-i18n/ts/index.html', 'i18n', 'index.html (launch script)')(format='.') :marked In this sample, the user's language is hardcoded as a global `document.locale` variable in the `index.html`. + 在本例中，用户的语言在`index.html`中被硬编码到一个全局的`document.locale`变量中。 + a#text-plugin :marked ### SystemJS Text plugin + ### SystemJS文本插件 + Notice the SystemJS mapping of `text` to a `systemjs-text-plugin.js`. With the help of a text pluglin, SystemJS can read any file as raw text and return the contents as a string. You'll need it to import the language translation file. + 注意SystemJS将`text`映射为`systemjs-text-plug.js`。 + 在这个文本插件的帮助下，SystemJS可以读取任何原始文件并将其内容作为字符串返回。 + 你需要使用它来导入语言翻译文件。 + SystemJS doesn't ship with a raw text plugin but it's easy to add. Create the following `systemjs-text-plugin.js` in the root folder: + + SystemJS没有自带原始文本插件，但是我们很容易添加它。 + 在根目录新建下面的`systemjs-text-plugin.js`文件： + +makeExample('cb-i18n/ts/systemjs-text-plugin.js', null, 'systemjs-text-plugin.js')(format='.') :marked ### Create translation providers + ### 新建翻译提供商 + Three providers tell the JiT compiler how to translate the template texts for a particular language while compiling the application: + 三种提供商帮助JiT编译在编译应用时，将模板文本翻译到某种语言： + * `TRANSLATIONS` is a string containing the content of the translation file. + + * `TRANSLATIONS`是含有翻译文件内容的字符串。 + * `TRANSLATIONS_FORMAT` is the format of the file: `xlf`, `xlif` or `xtb` + + * `TRANSLATIONS_FORMAT`是文件的格式: `xlf`、`xlif`或`xtb`。 + * `LOCALE_ID` is the locale of the target language. + * `LOCALE_ID`是目标语言的语言环境。 + The `getTranslationProviders` function in the following `app/i18n-providers.ts` creates those providers based on the user's _locale_ and the corresponding translation file: + + 在下面的`app/i18n-providers.ts`文件的getTranslationProviders`函数中，根据用户的**语言环境**和对应的翻译文件构建这些提供商： +makeExample('cb-i18n/ts/app/i18n-providers.ts', null, 'app/i18n-providers.ts') :marked * It gets the locale from the global `document.locale` variable that was set in `index.html`. + * 它从在`index.html`中设置的全局`document.locale`变量中获取语言环境。 + * If there is no locale or the language is U.S. English (`en-US`), there is no need to translate. The function returns an empty `noProviders` array as a `Promise`. It must return a `Promise` because this function could read a translation file asynchronously from the server. + * 如果没有语言环境或者语言是美国英语（`en-US`），则就无需翻译。 + 该函数以`Promise`的形式返回一个空的`noProviders`数组。 + 它必须要返回`Promise`，因为这个函数可能异步从服务器读取翻译文件。 + * It creates a transaction filename from the locale according to the name and location convention [described earlier](#localization-folder). + * 根据[上面描述](#localization-folder)的名字和本土化的约定，它根据语言环境创建一个合约文件名。 + * The `getTranslationsWithSystemJs` method reads the translation and returns the contents as a string. Notice that it appends `!text` to the filename, telling SystemJS to use the [text plugin](#text-plugin). + * `getTranslationsWithSystemJs`方法读取翻译并以字符串的形式返回其内容。 + 注意它在文件名上附加`!text`，告诉SystemJS使用[文本插件](#text-plugin)。 + * The callback composes a providers array with the three translation providers. + * 回调函数使用这三种翻译提供商创建一个提供商数组。 + * Finally, `getTranslationProviders` returns the entire effort as a promise. + * 最后，`getTranslationProviders`返回以承诺的形式返回全部流程的结果。 + ### Bootstrap the app with translation providers + ### 使用翻译提供商引导应用 + The Angular `bootstrapModule` method has a second, _options_ parameter that can influence the behavior of the compiler. + Angular的`bootstrapModule`方法接受**可选的**第二参数，它可以影响编译器的行为。 + You'll create an _options_ object with the translation providers from `getTranslationProviders` and pass it to `bootstrapModule`. Open the `app/main.ts` and modify the bootstrap code as follows: + + 从`getTranslationProviders`返回的翻译提供商创建_options_对象，并将其传给`bootstrapModule`。 + 打开`app/main.ts`并这样修改引导代码： + +makeExample('cb-i18n/ts/app/main.ts', null, 'app/main.ts')(format=".") :marked Notice that it waits for the `getTranslationProviders` promise to resolve before bootstrapping the app. + 注意，它等待`getTranslationProviders`承诺的解析完成后，才引导应用。 + The app is now _internationalized_ for English and French and there is a clear path for adding more languages. + 现在，应用已经被国际化为英语版和法语版，而且我们有了清晰的添加更多语言的方法。 + a#aot .l-main-section :marked ### _Internationalize_ with the AoT compiler + + ### 使用AoT编译器时的国际化 The JiT compiler translates the application into the target language while compiling dynamically in the browser. - That's flexible but may not be fast enough for your users. + That's flexible but may not be fast enough for your users. + + JiT编译器在浏览器中动态编译应用时，将其翻译到目标语言。 + 这样很灵活，但是对用户来讲，可能速度太慢。 The AoT (_Ahead-of-Time_) compiler is part of a build process that produces a small, fast, ready-to-run application package. When you internationalize with the AoT compiler, you pre-build a separate application package for each language. Then in the host web page (`index.html`), you determine which language the user needs and serve the appropriate application package. + AoT（预先）编译器是一种构建流程，出产尺寸小、速度快和可执行的应用程序包。 + 在使用Aot编译器的环境中国际化，你为每种语言预先构建一个单独的应用程序包。然后，在宿主网络页面（`index.html`）中，你再决定用户需要哪种语言，并选择合适的应用程序包。 + This cookbook doesn't cover how to build multiple application packages and serve them according to the user's language preference. It does explain the few steps necessary to tell the AoT to apply a translations file. + 本烹饪书不介绍如何构建多种应用程序包和如何根据用户的语言设置推送它们。 + 它介绍了一些必要的步骤，来告诉AoT采用用翻译文件。 + Internationalization with the AoT compiler requires some setup specifically for AoT. Start with application project as shown [just before merging the translation file](#app-pre-translationStart) and refer to the [AoT cookbook](aot-compiler.html) to make it _AoT-ready_. + + 使用AoT编译器时的国际化，需要一些针对AoT的设置。 + 以[合并翻译文件之前](#app-pre-translationStart)的应用项目开始，并参见[AoT烹饪书](aot-compiler.html)，把它变成与AoT兼容的项目。 Next, issue an `ngc` compile command for each supported language (including English). The result is a separate version of the application for each language. + + 接下来，为每种支持的语言（包括英语）运行一次`ngc`编译命令。 + 结果是每种语言都有自己单独的应用版本。 Tell AoT how to translate by adding three options to the `ngc` command: + + 通过添加下面三种选项到`ngc`命令来告诉AoT编译器如何翻译： + * `--i18nFile`: the path to the translation file + + * `--i18nFile`: 翻译文件的路径 + * `--locale`: the name of the locale + + * `--locale`: 语言环境的名字 + * `--i18nFormat`: the format of the localization file + + * `--i18nFormat`: 翻译文件的格式 For this sample, the French language command would be + + 本法语例子的命令为： code-example(language="sh" class="code-shell"). ./node_modules/.bin/ngc --i18nFile=./locale/messages.fr.xlf --locale=fr --i18nFormat=xlf .l-sub-section :marked Windows users may have to quote the command: + + Windows用户可能需要双引号这个命令： code-example(language="sh" class="code-shell"). "./node_modules/.bin/ngc" --i18nFile=./locale/messages.fr.xlf --locale=fr --i18nFormat=xlf