From 7e65406a61b8c379a33b851316a1993db48522be Mon Sep 17 00:00:00 2001 From: cuiliang Date: Thu, 12 Apr 2018 15:26:59 +0800 Subject: [PATCH] Update tutorial-i18n.md --- docs/guide-zh-CN/tutorial-i18n.md | 200 ++++++++++++++++++++++++-------------- 1 file changed, 125 insertions(+), 75 deletions(-) diff --git a/docs/guide-zh-CN/tutorial-i18n.md b/docs/guide-zh-CN/tutorial-i18n.md index 97560b1..e71f376 100644 --- a/docs/guide-zh-CN/tutorial-i18n.md +++ b/docs/guide-zh-CN/tutorial-i18n.md @@ -1,5 +1,5 @@ -国际化 -======= +国际化（Internationalization） +=========================== 国际化（I18N）是指在设计软件时，使它可以无需做大的改变就能够适应不同的语言和地区的需要。对于 Web 应用程序， 这有着特别重要的意义，因为潜在的用户可能会在全球范围内。 @@ -7,11 +7,16 @@ Yii 提供的国际化功能支持全方位信息翻译， 视图翻译，日期和数字格式化。 -## 区域和语言 +## 区域和语言（Locale and Language） -区域设置是一组参数以定义用户希望能在他们的用户界面所看到用户的语言，国家和任何特殊的偏好。 +### 区域（Locale） + +区域设置是一组参数以定义用户希望能在他们的用户界面所看到用户的语言， +国家和任何特殊的偏好。 它通常是由语言 ID 和区域 ID 组成。 + 例如，ID “en-US” 代表英语和美国的语言环境。为了保持一致性， + 在 Yii 应用程序中使用的所有区域 ID 应该规范化为 `ll-CC`， 其中 `ll` 是根据两个或三个字母的小写字母语言代码 [ISO-639](http://www.loc.gov/standards/iso639-2/) 和 `CC` 是两个字母的国别代码 @@ -19,13 +24,17 @@ Yii 提供的国际化功能支持全方位信息翻译， 有关区域设置的更多细节可以看 [ICU 项目文档](http://userguide.icu-project.org/locale#TOC-The-Locale-Concept)。 +### 语言（Language） + 在 Yii中，我们经常用 “language” 来代表一个区域。 -一个 Yii 应用使用两种语言：[[yii\base\Application::$sourceLanguage|源语言]] 和 -[[yii\base\Application::$language|目标语言]] 。 -前者指的是写在代码中的语言，后者是向最终用户显示内容的语言。 -而信息翻译服务主要是将文本消息从原语言翻译到目标语言。 +Yii 应用程序使用两种语言： +* [[yii\base\Application::$sourceLanguage|源语言]]：前者指的是写在代码中的语言，后者是向最终用户显示内容的语言。 +* [[yii\base\Application::$language|目标语言]]：而信息翻译服务主要是将文本消息从原语言翻译到目标语言。 +所谓的消息翻译服务主要将文本消息从源语言转换为目标语言。 + +### 配置（Configuration） 可以用类似下面的应用程序配置来配置应用程序语言： ```php @@ -53,20 +62,27 @@ return [ \Yii::$app->language = 'zh-CN'; ``` -## 消息翻译 +> Tip: 如果您的源语言在代码的不同部分中有所不同，那么您可以覆盖不同消息源的源语言， +> 这将在下一节中介绍。 + +## 消息翻译（Message Translation） +### 从源语言到目标语言（From source language to target language） 消息翻译服务用于将一条文本信息从一种语言（通常是 [[yii\base\Application::$sourceLanguage|源语言]] ） 翻译成另一种语言（通常是 [[yii\base\Application::$language|目标语言]]）。 -它的翻译原理是通过在语言文件中查找要翻译的信息以及翻译的结果。 -如果要翻译的信息可以在语言文件中找到，会返回相应的翻译结果； + +它的翻译原理是通过在语言文件中查找要翻译的信息以及翻译的结果。如果要翻译的信息可以在语言文件中找到，会返回相应的翻译结果； 否则会返回原始未翻译的信息。 +### 如何实现（How to implement） 为了使用消息翻译服务，需要做如下工作： -* 调用 [[Yii::t()]] 方法且在其中包含每一条要翻译的消息； -* 配置一个或多个消息来源，能在其中找得到要翻译的消息和翻译结果； -* 让译者翻译信息并将它们存储在消息来源。 +1. 调用 [[Yii::t()]] 方法且在其中包含每一条要翻译的消息； +2. 配置一个或多个消息来源，能在其中找得到要翻译的消息和翻译结果； +3. 让译者翻译信息并将它们存储在消息来源。 + +#### 1. 包裹一条消息（Wrap a text message） 这个 [[Yii::t()]] 方法的用法如下， ```php @@ -76,6 +92,7 @@ echo \Yii::t('app', 'This is a string to translate!'); 第一个参数指储存消息来源的类别名称， 第二个参数指需要被翻译的消息。 +#### 2. 配置一个或多个消息源（Configure one or multiple message sources） 这个 [[Yii::t()]] 方法会调用 `i18n` [应用组件](structure-application-components.md) 来实现翻译工作。这个组件可以在应用程序中按下面的代码来配置， @@ -98,15 +115,47 @@ echo \Yii::t('app', 'This is a string to translate!'); ], ``` +在上面的代码中，正在配置 [[yii\i18n\PhpMessageSource]] 支持的消息源。 + +##### 带 `*` 符号的类别通配符（Category wildcards with `*` symbol） + 在上面的代码中，配置了由 [[yii\i18n\PhpMessageSource]] 所支持的消息来源。模式 `app*` 表示所有以 `app` 开头的消息类别名称都使用这个翻译的消息来源。 -该 [[yii\i18n\PhpMessageSource]] 类使用 PHP 文件来存储消息翻译。 -每 PHP 文件对应单一类别的消息。默认情况下， -文件名应该与类别名称相同。但是，你可以配置 -[[yii\i18n\PhpMessageSource::fileMap|fileMap]] 来映射一个类别到不同名称的 PHP 文件。在上面的例子中， -类别 `app/error` 被映射到PHP文件 `@app/messages/ru-RU/error.php`（假设 `ru-RU` 为目标语言）。如果没有此配置， + +#### 3. 让译员翻译消息并将它们存储在消息源中（Let the translators translate messages and store them in the message source(s)） + +The [[yii\i18n\PhpMessageSource]] 类使用PHP文件和一个简单的 PHP 数组来存储消息转换。 +这些文件包含 `源语言` 中的消息到 `目标语言` 中的翻译的映射。 + +> Info: 您可以使用 [`message` 命令](#message-command) 自动生成这些 PHP 文件， +> 这将在本章后面介绍。 + +每个PHP文件对应于单个类别的消息。 默认情况下，文件名应与类别名称相同。 +`app/messages/nl-NL/main.php` 的例子： + +```php + 'welkom' +]; + +``` + + +##### 文件映射（File mapping） + +[[yii\i18n\PhpMessageSource::fileMap|fileMap]] 来映射一个类别到不同名称的 PHP 文件。 + +在上面的例子中，类别 `app/error` 被映射到PHP文件 `@app/messages/ru-RU/error.php`（假设 `ru-RU` 为目标语言）。 +如果没有此配置， 该类别将被映射到 `@app/messages/ru-RU/app/error.php` 。 +##### 其他存储类型（Other storage types） + 除了在PHP文件中存储消息来源， 也可以使用下面的消息来源在不同的存储来存储翻译的消息： @@ -114,13 +163,13 @@ echo \Yii::t('app', 'This is a string to translate!'); - [[yii\i18n\DbMessageSource]] 使用一个数据库表来存储翻译的消息。 -## 消息格式化 +## 消息格式化（Message Formatting） 在要翻译的消息里，你可以嵌入一些占位符，并让它们通过动态的参数值来代替。 你甚至可以根据目标语言格式的参数值来使用特殊的占位符。 在本节中，我们将介绍如何用不同的方式来格式化消息。 -### 消息参数 +### 消息参数（Message Parameters） 在待翻译的消息，可以嵌入一个或多个占位符，以便它们可以由给定的参数值取代。 通过给不同的参数值，可以动态地改变翻译内容的消息。 @@ -161,7 +210,7 @@ $subtotal = 200; echo \Yii::t('app', 'Price: {0}, Count: {1}, Subtotal: {2}', $price, $count, $subtotal); ``` -In case of a single positional parameter its value could be specified without wrapping it into array: +在单个位置参数的情况下，它的值可以被指定而不包含在数组中： ```php echo \Yii::t('app', 'Price: {0}', $price); @@ -191,7 +240,7 @@ short form: {PlaceholderName, ParameterType} full form: {PlaceholderName, ParameterType, ParameterStyle} ``` -> Note: If you need to use special characters such as `{`, `}`, `'`, `#`, wrap them in `'`: +> Note: 如果您需要使用特殊字符（如 `{`，`}`，`'`，`#`，请使用 `'`： > ```php echo Yii::t('app', "Example of string with ''-escaped characters'': '{' '}' '{test}' {count,plural,other{''count'' value is # '#{}'}}", ['count' => 3]); @@ -201,7 +250,7 @@ echo Yii::t('app', "Example of string with ''-escaped characters'': '{' '}' '{te 关于如何指定这样的占位符的说明。接下来我们会展示一些常用的使用方法。 -#### 数字 +#### 数字（Number） 参数值应该被格式化为一个数。例如， @@ -224,16 +273,16 @@ $sum = 42; echo \Yii::t('app', 'Balance: {0, number, ,000,000000}', $sum); ``` -Characters used in the custom format could be found in -[ICU API reference](http://icu-project.org/apiref/icu4c/classicu_1_1DecimalFormat.html) under "Special Pattern Characters" -section. +自定义格式中使用的字符可以在“特殊模式字符”一节的 +[ICU API 参考](http://icu-project.org/apiref/icu4c/classicu_1_1DecimalFormat.html) +中找到。 -The value is always formatted according to the locale you are translating to i.e. you cannot change decimal or thousands -separators, currency symbol etc. without changing translation locale. If you need to customize these you can -use [[yii\i18n\Formatter::asDecimal()]] and [[yii\i18n\Formatter::asCurrency()]]. +该值始终根据您翻译的区域设置进行格式设置，即无需更改翻译区域设置即可更改小数或千位分隔符，货币符号等。 +如果你需要定制这些，你可以使用 +[[yii\i18n\Formatter::asDecimal()]] 和 [[yii\i18n\Formatter::asCurrency()]]。 -#### 日期 +#### 日期（Date） 该参数值应该被格式化为一个日期。 例如， @@ -256,7 +305,7 @@ echo \Yii::t('app', 'Today is {0, date, yyyy-MM-dd}', time()); [格式化参考](http://icu-project.org/apiref/icu4c/classicu_1_1SimpleDateFormat.html#details)。 -#### 时间 +#### 时间（Time） 参数值应该被格式化为一个时间。 例如， @@ -279,7 +328,7 @@ echo \Yii::t('app', 'It is {0, date, HH:mm}', time()); [格式化参考](http://icu-project.org/apiref/icu4c/classicu_1_1SimpleDateFormat.html#details)。 -#### 拼写 +#### 拼写（Spellout） 参数值为一个数并被格式化为它的字母拼写形式。 例如， @@ -288,19 +337,19 @@ echo \Yii::t('app', 'It is {0, date, HH:mm}', time()); echo \Yii::t('app', '{n,number} is spelled as {n, spellout}', ['n' => 42]); ``` -By default the number is spelled out as cardinal. It could be changed: +默认情况下，该数字拼写为基数。 它可以改变： ```php // may produce "I am forty-seventh agent" echo \Yii::t('app', 'I am {n,spellout,%spellout-ordinal} agent', ['n' => 47]); ``` -Note that there should be no space after `spellout,` and before `%`. +请注意，在 `spellout,` 之后和 `%` 之前不应该有空格。 -To get a list of options available for locale you're using check -"Numbering schemas, Spellout" at [http://intl.rmcreative.ru/](http://intl.rmcreative.ru/). +要获取可用于您正在使用的语言环境的选项列表，请查看 +[http://intl.rmcreative.ru/](http://intl.rmcreative.ru/) 上的“编号模式，拼写”。 -#### 序数词 +#### 序数词（Ordinal） 参数值为一个数并被格式化为一个序数词。 例如， @@ -309,19 +358,19 @@ To get a list of options available for locale you're using check echo \Yii::t('app', 'You are the {n, ordinal} visitor here!', ['n' => 42]); ``` -Ordinal supports more ways of formatting for languages such as Spanish: +Ordinal 支持更多格式化西班牙语等语言的方式： ```php // may produce 471ª echo \Yii::t('app', '{n,ordinal,%digits-ordinal-feminine}', ['n' => 471]); ``` -Note that there should be no space after `ordinal,` and before `%`. +请注意，在 `ordinal,` 之后和 `%` 之前不应该有空格。 -To get a list of options available for locale you're using check -"Numbering schemas, Ordinal" at [http://intl.rmcreative.ru/](http://intl.rmcreative.ru/). +要获取可用于您正在使用的语言环境的选项列表，请查看 +[http://intl.rmcreative.ru/](http://intl.rmcreative.ru/) 上的“编号模式，序号”。 -#### 持续时间 +#### 持续时间（Duration） 参数值为秒数并被格式化为持续的时间段。 例如， @@ -330,19 +379,19 @@ To get a list of options available for locale you're using check echo \Yii::t('app', 'You are here for {n, duration} already!', ['n' => 47]); ``` -Duration supports more ways of formatting: +持续时间支持更多格式化方法： ```php // may produce 130:53:47 echo \Yii::t('app', '{n,duration,%in-numerals}', ['n' => 471227]); ``` -Note that there should be no space after `duration,` and before `%`. +请注意，在 `duration,` 之后和 `%` 之前不应该有空格。 -To get a list of options available for locale you're using check -"Numbering schemas, Duration" at [http://intl.rmcreative.ru/](http://intl.rmcreative.ru/). +要获取您正在使用的区域设置的可用选项列表，请查看 +[http://intl.rmcreative.ru/](http://intl.rmcreative.ru/) 上的“编号模式，持续时间”。 -#### 复数 +#### 复数（Plural） 不同的语言有不同的方式来表示复数。 Yii 提供一个便捷的途径， 即使是非常复杂的规则也使翻译消息时不同的复数形式行之有效。 @@ -369,13 +418,13 @@ echo \Yii::t('app', 'There {n, plural, =0{are no cats} =1{is one cat} other{are 而不是一个原始消息，除非设置应用程序的 [[yii\base\Application::$sourceLanguage|源语言]] 为 `ru-RU`。 -> Note: The above example Russian message is mainly used as a translated message, not an original message, unless you set -> the [[yii\base\Application::$sourceLanguage|source language]] of your application as `ru-RU` and translating from Russian. +> Note: 除非您将应用程序的 [[yii\base\Application::$sourceLanguage|源语言]] +> 设置为“RU-RU”，并且从以下语言转换而来，上面的示例俄语消息主要用作翻译的消息，而不是原始消息俄语。 > -> When a translation is not found for an original message specified in `Yii::t()` call, the plural rules for the -> [[yii\base\Application::$sourceLanguage|source language]] will be applied to the original message. +> 当在 `Yii::t()` 调用中指定的原始消息未找到翻译时， +> [[yii\base\Application::$sourceLanguage|源语言]] 复数规则将应用于原始消息。 -There's an `offset` parameter for the cases when the string is like the following: +对于字符串如下所示的情况，有一个 `offset` 参数： ```php $likeCount = 2; @@ -392,10 +441,10 @@ echo Yii::t('app', 'You {likeCount,plural, // You and one other person liked this ``` -#### Ordinal selection +#### 序数选择（Ordinal selection） -The parameter type of `selectordinal` is meant to choose a string based on language rules for ordinals for the -locale you are translating to: +`selectordinal` 的参数类型旨在为您所翻译的语言环境选择一个基于语序规则的字符串： +一个基于语序规则的字符串： ```php $n = 3; @@ -410,11 +459,11 @@ echo Yii::t('app', 'You are the {n,selectordinal,one{#st} two{#nd} few{#rd} othe // Вы 3-й посетитель ``` -The format is very close to what's used for plurals. To learn which arguments you should specify for a particular locale, -please refer to "Plural Rules, Ordinal" at [http://intl.rmcreative.ru/](http://intl.rmcreative.ru/). -Alternatively you can refer to [rules reference at unicode.org](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html). +格式与复数使用的格式非常接近。 要了解您应为特定语言环境指定哪些参数，请参阅 +[http://intl.rmcreative.ru/](http://intl.rmcreative.ru/) 上的“复数规则，序数”。 +或者，您可以参考 [unicode.org上的规则参考](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html)。 -#### 选择 +#### 选择（Selection） 可以使用 `select` 参数类型来选择基于参数值的短语。例如， @@ -431,9 +480,10 @@ echo \Yii::t('app', '{name} is a {gender} and {gender, select, female{she} male{ 应指定一个短语并把它放在在一对大括号中。 -### 指定默认翻译 +### 指定默认翻译（Specifying default message source） -你可以指定使用默认的翻译，该翻译将作为一个类别，用于不匹配任何其他翻译的后备。这种翻译应标有 `*` 。 +你可以指定使用默认的翻译，该翻译将作为一个类别，用于不匹配任何其他翻译的后备。 +这种翻译应标有 `*` 。 为了做到这一点以下内容需要添加到应用程序的配置： ```php @@ -457,7 +507,7 @@ echo Yii::t('not_specified_category', 'message from unspecified category'); 该消息将来自 `@app/messages//not_specified_category.php` 。 -### 翻译模块消息 +### 翻译模块消息（Translating module messages） 如果你想翻译一个模块的消息，并避免使用单一翻译文件的所有信息，你可以按照下面的方式来翻译： @@ -504,7 +554,7 @@ class Module extends \yii\base\Module 现在你可以直接使用 `Module::t('validation', 'your custom validation message')` 或 `Module::t('form', 'some form label')`。 -### 翻译小部件消息 +### 翻译小部件消息（Translating widgets messages） 上述模块的翻译规则也同样适用于小部件的翻译规则，例如： @@ -557,7 +607,7 @@ class Menu extends Widget > Tip: 对于小部件也可以使用 i18n 视图，并一样以控制器的规则来应用它们。 -### 翻译框架信息 +### 翻译框架信息（Translating framework messages） Yii 自带了一些默认的信息验证错误和其他一些字符串的翻译。 这些信息都是在 `yii` 类别中。有时候你想纠正应用程序的默认信息翻译。 @@ -577,7 +627,7 @@ Yii 自带了一些默认的信息验证错误和其他一些字符串的翻译 现在可以把你修改过的翻译放在 `@app/messages//yii.php`。 -### 处理缺少的翻译 +### 处理缺少的翻译（Handling missing translations） 如果翻译的消息在消息源文件里找不到，Yii 将直接显示该消息内容。这样一来当你的原始消息是一个有效的冗长的文字时会很方便。 然而，有时它是不能实现我们的需求。你可能需要执行一些自定义处理的情况， @@ -629,7 +679,7 @@ class TranslationEventHandler > 你应该给它们每一个消息源指定相应的事件处理程序。 -### 使用 `message` 命令 +### 使用 `message` 命令（Using the `message` command） 翻译储存在 [[yii\i18n\PhpMessageSource|php 文件]]，[[yii\i18n\GettextMessageSource|.po 文件] 或者 [[yii\i18n\DbMessageSource|数据库]]。具体见类的附加选项。 @@ -644,31 +694,31 @@ class TranslationEventHandler * `languages`: 代表你的应用程序应该被翻译成什么语言的一个数组; * `messagePath`: 存储消息文件的路径，这应与配置中 `i18n` 的 `basePath` 参数一致。 -You may also use './yii message/config' command to dynamically generate configuration file with specified options via cli. -For example, you can set `languages` and `messagePath` parameters like the following: +您也可以使用 './yii message/config' 命令通过 cli 动态生成带有指定选项的配置文件。 +例如，你可以像下面这样设置 `languages` 和 `messagePath` 参数： ```bash ./yii message/config --languages=de,ja --messagePath=messages path/to/config.php ``` -To get list of available options execute next command: +要获取可用选项列表，请执行下一个命令： ```bash ./yii help message/config ``` -Once you're done with the configuration file you can finally extract your messages with the command: +一旦你完成了配置文件，你最终可以用命令提取你的消息： ```bash ./yii message path/to/config.php ``` -Also, you may use options to dynamically change parameters for extraction. +另外，您可以使用选项来动态更改提取参数。 然后你会发现你的文件（如果你已经选择基于文件的翻译）在 `messagePath` 目录。 -## 视图的翻译 +## 视图的翻译（View Translation） 有时你可能想要翻译一个完整的视图文件，而不是翻译单条文本消息。为了达到这一目的， 只需简单的翻译视图并在它子目录下保存一个名称一样的目标语言文件。 @@ -681,12 +731,12 @@ Also, you may use options to dynamically change parameters for extraction. 在翻译视图的存在下，将呈现原始视图。 -## 格式化日期和数字值 +## 格式化日期和数字值（Formatting Date and Number Values） 在 [格式化输出数据](output-formatting.md) 一节可获取详细信息。 -## 设置 PHP 环境 +## 设置 PHP 环境（Setting Up PHP Environment） Yii 使用 [PHP intl 扩展](http://php.net/manual/en/book.intl.php) 来提供大多数 I18N 的功能， 如日期和数字格式的 [[yii\i18n\Formatter]] 类和消息格式的 [[yii\i18n\MessageFormatter]] 类。