Yii Framework 公式ガイド シリーズ サプリメント 48 - 特別トピック: 国際化 (I18N)

国際化 (翻訳者注: 国際化、I と n の間に 18 文字があるため、I18N と略されることが多い) は、主要なエンジニアリング変更を必要としないアプリケーション ソフトウェアを設計するプロセスを指します。さまざまな言語や地域に対応できるように作られています。 潜在的なユーザーが世界各地から来る可能性があるため、Web アプリケーションでは国際化が特に重要です。

Yii は、いくつかの側面で I18N のサポートを提供します。

• あらゆる可能な言語とバリアントのローカライズされたデータを提供します。

• 情報や文書の翻訳サービスを提供します。

• ローカリゼーションベースの日付と時刻の形式を提供します。

• 地元の方言に基づいたデジタル形式を提供します。

次のセクションでは、上記の側面について詳しく説明します。

1. 地域と言語

地域は、ユーザーの言語、ユーザーの国、およびユーザーがインターフェースに表示したいすべての特別なパラメーターを定義するパラメーターのセットです。 通常、言語 ID とロケール ID を組み合わせた ID によって識別されます。たとえば、ID en_US は英語地域と米国を表します。 一貫性を維持するために、Yii のすべてのリージョン ID は小文字の Language ID または Language ID_Region ID に正規化されます (例: en、en_us) コード>)。 <code>en_US 表示英语区域和美国。 为保持一致性，Yii 中所有的区域 ID 被规范为小写的 语言 ID 或 语言 ID_地区 ID（例如 en, en_us）。

区域数据由一个 CLocale 实例表示。它提供了基于区域的信息，包括货币符号，数字符号， 日期和时间格式以及日期相关的名称。由于语言信息已经由区域 ID 实现，因此 CLocale 不再提供。 同理，我们通常会变换地使用词语“区域”和“语言”。

通过一个区域 ID，就可以通过 CLocale::getInstance($localeID) 或者CApplication::getLocale($localeID) 获取相应的 CLocale 实例。

信息: Yii 包含几乎所有语言和区域的区域化数据。 这些数据来自于 Common Locale Data Repository(CLDR)。在每个区域中， 只提供了 CLDR 中的部分数据，因为原始的 CLDR 数据中包含了大量不太常用的信息。从版本 1.1.0 起， 用户也可以使用他们自定义的区域数据。只需要配置CApplication::localeDataPath 属性为包含了自定义区域数据的目录即可。 请参考位于framework/i18n/data 目录中的文件创建自定义的区域数据文件。

在一个 Yii 应用程序中，我们区分了它的 目标语言（target language） 和 源语言（source language）。目标语言是应用程序的目标用户的语言（区域）， 而源语言是指写在应用程序源代码中的语言（区域）。国际化仅会在这两种语言不同的情况下发生。

你可以设定 应用配置 中的 目标语言 ，或者在发生国际化之前动态设定此参数。

提示: 有时候，我们想要设置目标语言为用户所使用的语言（就是在用户的浏览器选项中指定的那个）。 只需使用 CHttpRequest::preferredLanguage 就可以获取到用户设定的语言。

2. 翻译

在 I18N 中用到的最多的可能就是翻译了，包括 信息翻译 和 视图翻译。 前者将一条文本信息翻译为期望的语言，后者将整合文件翻译为期望的语言。

一个翻译请求包含要被翻译的对象，对象所用的源语言，和对象所需要翻译到的目标语言。 在 Yii 中，源语言默认为 应用程序源语言 而目标语言默认为 应用程序语言。 如果两者语言相同，翻译将不会发生。

信息翻译

信息翻译是通过调用 Yii::t() 实现的。此方法会将信息从 源语言 翻译为 目标语言。

当翻译一条信息时，必须指定它的分类（category），因为一条信息在不同的分类或上下文中可能会有 不同的翻译。分类 yii 被保留为仅限 Yii 框架核心使用。

信息可以包含参数占位符，它们将会在调用 Yii::t() 时被实际的参数值取代。 例如，下面的信息翻译请求将会替换原始信息中的 {alias} 占位符为实际的别名（alias） 值。

Yii::t('app', 'Path alias "{alias}" is redefined.',
    array('{alias}'=>$alias))

注意: 要翻译的信息必须是常量字符串。它们不能包含可能会改变信息内容的变量 （例如"Invalid {$message} content."

地域データは CLocale インスタンスによって表されます。通貨記号、数値記号、日付と時刻の形式、日付関連の名前など、ロケールベースの情報が提供されます。言語情報はすでにロケール ID によって実装されているため、CLocale は提供されなくなりました。 同じ理由で、私たちは「地域」と「言語」という言葉を同じ意味で使用することがよくあります。 🎜🎜地域 ID を使用すると、CLocale::getInstance($localeID) または CApplication::getLocale($localeID) を通じて、対応する CLocale インスタンスを取得できます。 🎜

🎜情報: Yii には、ほぼすべての言語と地域の地域化されたデータが含まれています。 このデータは Common Locale Data Repository (CLDR) から取得されます。元の CLDR データにはあまり一般的に使用されない情報が大量に含まれているため、各領域内では CLDR の部分データのみが提供されます。バージョン 1.1.0 以降、ユーザーは独自のカスタム ゾーン データを使用することもできます。カスタム ロケール データを含むディレクトリに CApplication::localeDataPath 属性を構成するだけで済みます。 カスタム ゾーン データ ファイルを作成するには、framework/i18n/data ディレクトリにあるファイルを参照してください。 🎜

🎜 Yii アプリケーションでは、ターゲット言語とソース言語を区別します。ターゲット言語はアプリケーションの対象ユーザーの言語 (地域) であり、ソース言語はアプリケーションのソース コードに記述された言語 (地域) を指します。国際化は、2 つの言語が異なる場合にのみ発生します。 🎜🎜アプリケーション構成でターゲット言語を設定することも、国際化が行われる前にこのパラメーターを動的に設定することもできます。 🎜

🎜ヒント: 場合によっては、ターゲット言語をユーザーが使用する言語 (ユーザーのブラウザ オプションで指定された言語) に設定したいことがあります。 ユーザーが設定した言語を取得するには、CHttpRequest::preferredLanguage を使用するだけです。 🎜

🎜2. 翻訳🎜🎜おそらく I18N で最もよく使用されるのは、情報翻訳とビュー翻訳を含む翻訳です。 前者はテキストメッセージを希望の言語に翻訳し、後者は統合されたドキュメントを希望の言語に翻訳します。 🎜🎜翻訳リクエストには、翻訳対象のオブジェクト、オブジェクトのソース言語、オブジェクトの翻訳先となるターゲット言語が含まれます。 Yii では、ソース言語はデフォルトでアプリケーションソース言語に設定され、ターゲット言語はデフォルトでアプリケーション言語に設定されます。 両方が同じ言語である場合、翻訳は行われません。 🎜

情報翻訳

🎜情報翻訳は Yii::t() を呼び出すことで実装されます。このメソッドは、情報をソース言語からターゲット言語に翻訳します。 🎜🎜メッセージはカテゴリやコンテキストによって異なる翻訳になる可能性があるため、メッセージを翻訳する場合は、そのカテゴリを指定する必要があります。カテゴリ yii は、Yii フレームワークコアのみが使用するために予約されています。 🎜🎜メッセージにはパラメーターのプレースホルダーを含めることができ、Yii::t() を呼び出すときに実際のパラメーター値に置き換えられます。 たとえば、次のメッセージ変換リクエストは、元のメッセージの {alias} プレースホルダーを実際のエイリアス値に置き換えます。 🎜🎜🎜🎜🎜🎜

Yii::t('Xyz.categoryName', '要翻译的信息');

🎜🎜

🎜注: 翻訳されるメッセージは定数文字列である必要があります。メッセージの内容を変更する可能性のある変数を含めることはできません (例: "Invalid {$message} content.")。一部のパラメータを使用してメッセージを変更する必要がある場合は、パラメータ プレースホルダを使用してください。 🎜

翻译过的信息会存储在一个叫做 信息源（message source） 的库中。 信息源是一个 CMessageSource 或其子类的实例。当 Yii::t() 被调用时， 它将从信息源中查找相应的信息，如果找到了，就会返回翻译后的版本。

Yii 含有如下几种信息源。你也可以扩展 CMessageSource 创建自己的信息源类型。

• CPhpMessageSource: 信息的翻译存储在一个 PHP 的 键值对 数组中。 原始信息为键，翻译后的信息为值。每个数组表示一个特定信息分类的翻译，分别存储在不同的 PHP 脚本文件中，文件名即分类名。 针对同一种语言的 PHP 翻译文件存储在同一个以区域 ID 命名的目录中。而所有的这些目录位于 basePath 指定的目录中。

• CGettextMessageSource: 信息的翻译存储在 GNU Gettext 文件中。

• CDbMessageSource: 信息的翻译存储在数据库的表中。

信息源是作为一个 应用程序组件 载入的。 Yii 预定义了一个名为 messages 的应用程序组件以存储用户程序中用到的信息。 默认情况下，此信息源的类型是 CPhpMessageSource ，而存储这些 PHP 翻译文件的目录是protected/messages。

总体来说，要实现信息翻译，需要执行如下几步：

1. 在合适的位置调用 Yii::t() ；

2. 以 protected/messages/LocaleID/CategoryName.php 的格式创建 PHP 翻译文件。 每个文件简单的返回一个信息翻译数组。 注意，这是假设你使用默认的 CPhpMessageSource 存储翻译信息。

3. 配置 CApplication::sourceLanguage 和 CApplication::language。

提示: 使用 CPhpMessageSource 作为信息源时，Yii 中的 yiic 工具可用于管理信息翻译。 它的message 命令可以自动从所选的源文件中提取要翻译的信息，并在需要时将其合并为现存的翻译。 关于使用 message 命令的更多信息，请执行 yiic help message。

从版本 1.0.10 起，当使用 CPhpMessageSource 管理信息源时， 扩展类（例如一个 widget 小物件，一个模块）中的信息可以以一种特殊的方式管理并使用。 具体来说，如果一条信息属于一个类名为 Xyz 的扩展，那么分类的名字可以以 Xyz.categoryName 的格式指定。 相应的信息文件就是BasePath/messages/LanguageID/categoryName.php ，其中 BasePath 是指包含此扩展类文件的那个目录。 当使用 Yii::t() 翻译一条扩展信息时，需要使用如下格式：

Yii::t('Xyz.categoryName', '要翻译的信息');

从 1.0.2 起，Yi 添加了对 choice format 的支持。Choice format 是指选择按照一个给定数字的值选择一条翻译。例如，在英语中，视不同的数量，单词 'book' 可以有一个单数形式或者一个复数形式。而在其他语言中， 这个词可能就没有不同的形式（例如汉语）或者有更复杂的复数规则（例如俄语）。 Choice format 以一种简单而又高效的方式解决了这个问题。

要使用 choice format，翻译的信息必须包含一个由 | 分割的 “表达式-信息” 对序列。如下所示：

'expr1#message1|expr2#message2|expr3#message3'

其中 exprN 表示一个有效的 PHP 表达式，它会计算出一个布尔型的值，以确定相应的信息是否应该被返回。 只有第一个返回值为 true 的表达式对应的信息会被返回。 一个表达式可以包含一个特殊的变量 n （注意，它不是$n），它带有通过第一个信息参数传递的数字的值。 例如，假设有如下一条翻译信息：

'n==1#one book|n>1#many books'

而我们在调用 Yii::t() 时在参数数组中传递了数字值 2 ， 我们就会得到 many books 作为最终的翻译信息。

作为一种简便写法，如果一个表达式是一个数字，它将被视为等同于 n==Number。因此，上面的翻译信息也可以写为如下格式：

'1#one book|n>1#many books'

ファイル翻訳

ファイルの翻訳は、CApplication::findLocalizedFile()を呼び出すことで完了します。 翻訳するファイルへのパスを指定すると、このメソッドは Zone ID サブディレクトリ内で同じファイル名のファイルを検索します。 見つかった場合は、このファイルへのパスが返され、見つからなかった場合は、元のファイルへのパスが返されます。 区域 ID 子目录中查找相同文件名的文件。 如果找到了，就会返回此文件的路径；否则，将返回原始文件的路径。

文件翻译主要用于渲染一个视图。 当在控制器或小物件中调用任一渲染方法时，视图文件将会被自动翻译。例如，如果 目标语言 是 zh_cn 而 源语言 是 en_us，渲染一个名为 edit 的视图时，程序将会查找protected/views/ControllerID/zh_cn/edit.php 视图文件。 如果此文件找到，就会通过此翻译版本渲染。否则，就会使用文件 protected/views/ControllerID/edit.php 渲染。

文件翻译也可以用于其他目的，例如，显示一个翻译过的图片，或者加载一个基于区域的数据文件。

关于信息翻译和文件翻译的实战示例可参考这篇文章：Yii框架中如何使用Yii::t()实现文本信息翻译和文件翻译

3. 日期和时间格式化

日期和时间在不同的国家和地区通常会有不同的格式。 日期和时间格式和的任务就是生成一个符合指定区域格式的日期或时间字符串。 为实现此目的，Yii 提供了CDateFormatter。

每个 CDateFormatter 实例关联到一个目标区域。要获取关联到整个应用程序的目标区域的格式器（formatter）， 只需简单的访问 应用程序的 dateFormatter 属性。

CDateFormatter 类主要提供了两个方法以格式化 UNIX 时间戳。

• format: 此方法可通过一个自定义的模式格式化给定的 UNIX 时间戳为一个字符串 （例如 $dateFormatter->format('yyyy-MM-dd',$timestamp)）。

• formatDateTime: 此方法通过一个在目标区域数据中预定义的模式格式化给定的 UNIX 时间戳为一个字符串 （例如日期的 short 格式，时间的 long 格式）。

4. 数字格式化

与日期和时间类似，数字在不同的国家或地区之间也可能有不同的格式。 数字格式化包括十进制格式化，货币格式化和百分比格式化。Yii 提供了 CNumberFormatter 以完成这些任务。

要获取关联到整个应用程序的目标区域的格式器（formatter）， 只需简单的访问 应用程序的 numberFormatter属性。

CNumberFormatter 提供的如下方法可以用于格式化 integer 或 double 值

• format: 此方法通过一个自定义的模式格式化给定的数字为一个字符串 （例如 $numberFormatter->format('#,##0.00',$number)

  ファイル変換は主にビューをレンダリングするために使用されます。 コントローラーまたはウィジェットでレンダリング メソッドが呼び出されると、ビュー ファイルは自動的に変換されます。たとえば、ターゲット言語が zh_cn でソース言語が en_us の場合、edit という名前のビューをレンダリングするときに、プログラムは protected/views/ControllerID/zh_cn/edit.php ビュー ファイル。 このファイルが見つかった場合は、この翻訳されたバージョンを介してレンダリングされます。それ以外の場合、ファイル protected/views/ControllerID/edit.php がレンダリングに使用されます。
• ファイル翻訳は、翻訳された画像の表示や領域ベースのデータ ファイルのロードなど、他の目的にも使用できます。
  情報翻訳とファイル翻訳の実践例については、この記事を参照してください: Yii フレームワークでテキスト情報翻訳とファイル翻訳を実装するために Yii::t() を使用する方法

3. /h3>

• 日付と時刻は通常、国や地域によって形式が異なります。 日付と時刻の形式合計のタスクは、指定されたロケール形式に準拠する日付または時刻の文字列を生成することです。 この目的を達成するために、Yii は CDateFormatter を提供します。
  各 CDateFormatter インスタンスはターゲット領域に関連付けられます。アプリケーション全体のターゲット領域に関連付けられたフォーマッタを取得するには、アプリケーションの dateFormatter プロパティにアクセスするだけです。
• CDateFormatter クラスは、主に UNIX タイムスタンプをフォーマットする 2 つのメソッドを提供します。
format: このメソッドは、カスタム パターン (例: $dateFormatter->format( 'yyyy-MM-dd') を使用して、指定された UNIX タイムスタンプを文字列にフォーマットします。 、$タイムスタンプ))。

formatDateTime: このメソッドは、ターゲット ゾーン データで事前定義されたパターンを使用して、指定された UNIX タイムスタンプを文字列にフォーマットします (例: 日付の場合は short 形式、時間の場合は 形式) ）。

4. 数値の書式

🎜日付や時刻と同様、数値も国や地域によって書式が異なる場合があります。 数値の書式設定には、10 進数の書式設定、通貨の書式設定、パーセントの書式設定が含まれます。 Yii はこれらのタスクを実行するために CNumberFormatter を提供します。 🎜🎜アプリケーション全体のターゲット範囲に関連付けられたフォーマッタを取得するには、アプリケーションのnumberFormatterプロパティにアクセスするだけです。 🎜🎜CNumberFormatter は、整数または double 値の書式設定に使用できる次のメソッドを提供します。🎜

🎜🎜format: このメソッドは、カスタム パターン String を通じて指定された数値を文字に書式設定します。 (例: $numberFormatter->format('#,##0.00',$number))。 🎜🎜🎜🎜formatDecimal: このメソッドは、ターゲット範囲データ内の事前定義された小数パターンによって指定された数値をフォーマットします。 🎜🎜🎜🎜formatCurrency: このメソッドは、ターゲット地域のデータ内の事前定義された通貨パターンを使用して、指定された数値を書式設定します。 🎜🎜🎜🎜formatPercentage: このメソッドは、ターゲット領域データ内の事前定義されたパーセンテージ パターンを使用して、指定された数値をフォーマットします。 🎜🎜🎜🎜 上記は、Yii Framework 公式ガイド シリーズ サプリメント 48 - 特別トピック: 国際化 (I18N) の内容です。その他の関連コンテンツについては、PHP 中国語 Web サイト (www.php.cn) に注目してください。 🎜🎜🎜🎜🎜