diff --git a/docs/guide-ja/concept-di-container.md b/docs/guide-ja/concept-di-container.md index d04e94d08f..aaadc80f7e 100644 --- a/docs/guide-ja/concept-di-container.md +++ b/docs/guide-ja/concept-di-container.md @@ -91,7 +91,7 @@ $container->set('Foo', function () { $foo = $container->get('Foo'); ``` -新しいオブジェクトを構築するための複雑なロジックを隠蔽するために、PHP コーラブルを返すスタティックなクラスメソッドを使うことが出来ます。 +新しいオブジェクトを構築するための複雑なロジックを隠蔽するために、スタティックなクラスメソッドをコーラブルとして使うことが出来ます。 例えば、 ```php @@ -99,20 +99,17 @@ class FooBuilder { public static function build() { - return function () { - $foo = new Foo(new Bar); - // ... その他の初期化 ... - return $foo; - }; + $foo = new Foo(new Bar); + // ... その他の初期化 ... + return $foo; } } -$container->set('Foo', FooBuilder::build()); +$container->set('Foo', ['app\helper\FooBuilder', 'build']); $foo = $container->get('Foo'); ``` -ご覧のように、PHP コーラブルが `FooBuilder::build()` メソッドによって返されています。 このようにすれば、`Foo` クラスを構成しようとする人は、`Foo` がどのように構築されるかを気にする必要はもうなくなります。 diff --git a/docs/guide-ja/tutorial-i18n.md b/docs/guide-ja/tutorial-i18n.md index 2ec84489af..3dbf008420 100644 --- a/docs/guide-ja/tutorial-i18n.md +++ b/docs/guide-ja/tutorial-i18n.md @@ -1,70 +1,77 @@ 国際化 ====== -> Note|注意: この節はまだ執筆中です。 - 国際化 (I18N) とは、工学的な変更を伴わずにさまざまな言語と地域に順応できるように、ソフトウェアアプリケーションを設計するプロセスを指します。 潜在的なユーザが世界中にいるウェブアプリケーションにとっては、このことは特に重要な意味を持ちます。 +Yii は、全ての領域にわたる国際化機能を提供し、メッセージの翻訳、ビューの翻訳、日付と数字の書式設定をサポートします。 -Yii は、メッセージの翻訳、数字や日付の書式設定など、ウェブサイトの国際化を手助けするいくつかのツールを提供しています。 -ロケールと言語 --------------- +## ロケールと言語 -Yii のアプリケーションでは二つの言語が定義されます。 +ロケールとは、ユーザの言語、国、そして、ユーザが彼らのユーザインタフェイスにおいて目にすることを期待するすべての変異形式を定義する一連のパラメータです。 +ロケールは、通常、言語 ID と地域 ID から成るロケール ID によって定義されます。 +例えば、`en-US` は、英語とアメリカ合衆国のロケールを意味します。 +Yii アプリケーションで使用される全てのロケール ID は、一貫性のために、`ll-CC` の形式に正規化されなければなりません。 +ここで `ll` は [ISO-639](http://www.loc.gov/standards/iso639-2/) に従った小文字二つまたは三つの言語コードであり、`CC` は [ISO-3166](http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html) に従った二文字の国コードです。 +ロケールに関する更なる詳細は [ICU プロジェクトのドキュメント project](http://userguide.icu-project.org/locale#TOC-The-Locale-Concept) に述べられています。 + +Yii では、"言語" という用語でロケールに言及することがしばしばあります。 + +Yii のアプリケーションでは二つの言語を使用します。 すなわち、[[yii\base\Application::$sourceLanguage|ソース言語]] と [[yii\base\Application::$language|ターゲット言語]] です。 +前者はソースコード中のテキストメッセージが書かれている言語を意味し、後者はコンテントをエンドユーザに表示するのに使用されるべき言語を指します。 +いわゆるメッセージ翻訳サービスは、主として、テキストメッセージをソース言語からターゲット言語に翻訳するものです。 -ソース言語とは、次のように、コードに直接書かれているオリジナルのアプリケーションメッセージの言語です。 - -```php -echo \Yii::t('app', 'I am a message!'); -``` - -ターゲット言語は、現在のページを表示するのに使用されるべき言語、すなわち、オリジナルのメッセージの翻訳先となるべき言語です。 -これはアプリケーションの構成情報において、次のように定義されているものです。 +アプリケーションの言語は、アプリケーションの構成情報で次のように構成することが出来ます。 ```php return [ - 'id' => 'applicationID', - 'basePath' => dirname(__DIR__), - // ... - 'language' => 'ru-RU', // <- ここ ! - // ... -] + // ターゲット言語を日本語に設定 + 'language' => 'ja-JP', + + // ソース言語を英語に設定 + 'sourceLanguage' => 'en-US', + + ...... +]; ``` -> **Tip**|ヒント: [[yii\base\Application::$sourceLanguage|ソース言語]] のデフォルト値は英語であり、この値は変えないことが推奨されます。 -> 理由は、英語から他の言語への翻訳者を見つける方が、非英語から非英語への翻訳者を見つけるより簡単だからです。 +[[yii\base\Application::$sourceLanguage|ソース言語]] のデフォルト値は `en-US` であり、合衆国の英語を意味します。 +このデフォルト値は変えないことが推奨されます。 +なぜなら、通常は、英語から他の言語への翻訳者を見つける方が、非英語から非英語への翻訳者を見つけるより、はるかに簡単だからです。 -アプリケーションの言語を実行時に設定して、ユーザが選択した言語をターゲットにすることが可能です。 -この操作は、全ての出力に対して正しく効果を発揮するように、まだ出力が何も生成されていない時点で行われなければなりません。 -そのためには、アプリケーションのターゲット言語プロパティを望ましい値に変更するだけです。 +[[yii\base\Application::$language|ターゲット言語]] は、エンドユーザの言語選択など、さまざまな要因に基づいて、動的に設定しなければならないことがよくあります。 +アプリケーションの構成情報で構成するかわりに、次の文を使ってターゲット言語を変更することが出来ます。 ```php +// ターゲット言語を中国語に変更 \Yii::$app->language = 'zh-CN'; ``` -言語/ロケールの書式は `ll-CC` です。ここで `ll` は [ISO-639](http://www.loc.gov/standards/iso639-2/) に従った二文字または三文字の小文字の言語コードであり、`CC` は [ISO-3166](http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html) に従った国コードです。 -> **Note**|注意: ロケールの概念と構文に関する詳細な情報については、[ICU プロジェクトのドキュメント](http://userguide.icu-project.org/locale#TOC-The-Locale-Concept) を参照してください。 +## メッセージ翻訳 +メッセージ翻訳サービスは、テキストメッセージをある言語 (通常は [[yii\base\Application::$sourceLanguage|ソース言語]]) から別の言語 (通常は [[yii\base\Application::$language|ターゲット言語]]) に翻訳するものです。 +翻訳は、元のメッセージと翻訳されたメッセージを格納するメッセージソースの中から、翻訳対象となったメッセージを探すことにより行われます。 +メッセージが見つかれば、対応する翻訳されたメッセージが返されます。 +メッセージが見つからなければ、元のメッセージが翻訳されずに返されます。 -メッセージ翻訳 --------------- +メッセージ翻訳サービスを使用するためには、主として次の作業をする必要があります。 -メッセージ翻訳は、アプリケーションによって出力されたメッセージを別の言語に翻訳して、さまざまな国のユーザが自国語でアプリケーションを使えるようにするために使用されるものです。 +* 翻訳する必要のある全てのテキストメッセージを [[Yii::t()]] メソッドの呼び出しの中に包む。 +* メッセージ翻訳サービスが翻訳されたメッセージを探すことが出来る一つまたは複数のメッセージソースを構成する。 +* 翻訳者にメッセージを翻訳させて、それをメッセージソースに格納する。 -Yii におけるメッセージ翻訳機能は、ソース言語からターゲット言語へとメッセージの翻訳を探すという単純な動作をします。 -メッセージ翻訳機能を使うためには、オリジナルのメッセージ文字列を [[Yii::t()]] メソッドで包みます。 -このメソッドの最初のパラメータは、メッセージの生成元であるアプリケーションのさまざまな部分を区別するためのカテゴリであり、二番目のパラメータはメッセージそのものです。 +[[Yii::t()]] メソッドは次のように使います。 ```php echo \Yii::t('app', 'This is a string to translate!'); ``` -Yii は `i18n` [アプリケーションコンポーネント](structure-application-components.md) に定義されているメッセージソースの中から、現在の [[yii\base\Application::$language|アプリケーション言語]] に従って、適切な翻訳を読み込もうと試みます。 -メッセージソースは、翻訳メッセージを提供する一群のファイルまたはデータベースです。 -次の構成情報の例は、メッセージを PHP ファイルから取得するメッセージソースを定義するものです。 +ここで、二番目のパラメータが翻訳されるべきテキストメッセージを示し、最初のパラメータはメッセージを分類するのに使用されるカテゴリ名を示します。 + +[[Yii::t()]] メソッドは `i18n` [アプリケーションコンポーネント](structure-application-components.md) を呼んで実際の翻訳作業を実行します。 +このコンポーネントはアプリケーションの構成情報の中で次のようにして構成することが出来ます。 ```php 'components' => [ @@ -85,61 +92,105 @@ Yii は `i18n` [アプリケーションコンポーネント](structure-applica ], ``` -上記において `app*` は、このメッセージソースによって扱われるカテゴリを指定するパターンです。 -この例では、`app` から始まる全てのカテゴリをこのメッセージソースで処理します。 -メッセージファイルは `@app/messages`、すなわち、アプリケーションディレクトリの下の `messages` ディレクトリに配置されています。 -[[yii\i18n\PhpMessageSource::fileMap|fileMap]] 配列が、どのカテゴリに対してどのファイルが使われるべきかを定義しています。 -`fileMap` を構成する代りに、カテゴリ名をファイル名として使用する規約に依拠することも出来ます -(例えば、`app/error` というカテゴリは、[[yii\i18n\PhpMessageSource::basePath|basePath]] の下の `app/error.php` というファイル名に帰結します) 。 +上記のコードにおいては、[[yii\i18n\PhpMessageSource]] によってサポートされるメッセージソースが構成されています。 +`app*` は、`app` で始まる全てのメッセージカテゴリがこのメッセージソースを使って翻訳されるべきであることを示しています。 +[[yii\i18n\PhpMessageSource]] クラスは、メッセージ翻訳を格納するのに PHP ファイルを使用します。 +デフォルトでは、ファイル名はカテゴリ名と同じでなければなりません。 +ただし、[[yii\i18n\PhpMessageSource::fileMap|fileMap]] を構成して、別の命名方法によってカテゴリを PHP ファイルに割り付けることも可能です。 +上記の例では、(`ja-JP` がターゲット言語であると仮定すると) `app/error` のカテゴリは `@app/messages/ja-JP/error.php` という PHP ファイルに割り付けられます。 +`fileMap` を構成しなければ、このカテゴリは `@app/messages/ja-JP/app/error.php` に割り付けられることになります。 -`\Yii::t('app', 'This is a string to translate!')` というメッセージを翻訳するとき、アプリケーション言語が `ja-JP` である場合は、Yii は利用できるメッセージのリストを取得するために、まず `@app/messages/ja-JP/app.php` というファイルを探します。 -`ja-JP` ディレクトリにファイルが無い場合は、失敗であるとする前に、`ja` ディレクトリも探します。 +翻訳メッセージを格納するのには、PHP ファイル以外に、次のメッセージソースを使うことも可能です。 -メッセージを PHP ファイルに保存する [[yii\i18n\PhpMessageSource|PhpMessageSource]] に加えて、Yii は二つのクラスを提供しています。 - -- [[yii\i18n\GettextMessageSource]] - GNU Gettext の MO ファイルまたは PO ファイルを使用 -- [[yii\i18n\DbMessageSource]] - データベースを使用 +- [[yii\i18n\GettextMessageSource]] - 翻訳メッセージを保持するのに GNU Gettext の MO ファイルまたは PO ファイルを使用する +- [[yii\i18n\DbMessageSource]] - 翻訳メッセージを保存するのにデータベーステーブルを使用する -> Note|訳注: 以下においては、メッセージ書式の理解を助けるために、原文にはない日本語への翻訳例 (とその出力結果) をコードサンプルに追加しています。 +## メッセージのフォーマット -### 名前付きプレースホルダ +メッセージを翻訳するときには、プレースホルダを埋め込んで、動的なパラメータ値で実行時に置き換えさせることが出来ます。 +更には、パラメータ値をターゲット言語に応じてフォーマットさせるための特別なプレースホルダの構文を使うことも出来ます。 +この項では、メッセージをフォーマットする様々な方法を説明します。 -翻訳メッセージには、翻訳後に対応する値に置き換えられるパラメータを追加することが出来ます。 -このパラメータの形式は、次の例で示すように、パラメータ名を波括弧で囲むものです。 +> Note|訳注: 以下においては、メッセージフォーマットの理解を助けるために、原文にはない日本語への翻訳例 (とその出力結果) をコードサンプルに追加しています。 + +### メッセージパラメータ + +翻訳対象となるメッセージには、一つまたは複数のプレースホルダを埋め込んで、与えられたパラメータ値で置き換えられるようにすることが出来ます。 +様々なパラメータ値のセットを与えることによって、翻訳されるメッセージを動的に変化させることが出来ます。 +次の例では、`'Hello, {username}!'` というメッセージの中のプレースホルダ `{username}` が `'Alexander'` と `'Qiang'` にそれぞれ置き換えられます。 ```php $username = 'Alexander'; +// username が "Alexander" になった翻訳メッセージを表示 echo \Yii::t('app', 'Hello, {username}!', [ 'username' => $username, ]); -// 翻訳: '{username} さん、こんにちは!' +$username = 'Qiang'; +// username が "Qiang" になった翻訳メッセージを表示 +echo \Yii::t('app', 'Hello, {username}!', [ + 'username' => $username, +]); ``` -パラメータに値を代入するときには波括弧を使わないことに注意してください。 - -### 序数プレースホルダ +プレースホルダを持つメッセージを翻訳する時には、プレースホルダはそのままにしておかなければなりません。 +これは、プレースホルダは `Yii::t()` を呼んでメッセージを翻訳する時に、実際のパラメータ値に置き換えられるものだからです。 ```php -$sum = 42; -echo \Yii::t('app', 'Balance: {0}', $sum); - -// 翻訳: '差引残高: {0}' +// 日本語翻訳例: '{username} さん、こんにちは!' ``` -> **Tip**|ヒント: メッセージ文字列の意味が分らなくならないように、あまりに多くの序数プレースホルダを使うことは避けてください。 -> 翻訳者にはソース文字列しか無く、従って、各プレースホルダに何が入るのかが一見して明らかでなければならない、ということを忘れないでください。 +プレースホルダには、*名前付きプレースホルダ* と *序数プレースホルダ* のどちらかを使用する事が出来ます。 +ただし、一つのメッセージに両方を使うことは出来ません。 -### 高度なプレースホルダの書式設定 +上記の例は名前付きプレースホルダの使い方を示すものです。 +すなわち、各プレースホルダは `{パラメータ名}` という形式で書かれており、パラメータは連想配列で渡されます。 +このとき、配列のキーが(波括弧なしの)パラメータ名であり、配列の値が対応するパラメータ値です。 -この高度な機能を使うためには、[intl PHP 拡張](http://www.php.net/manual/ja/intro.intl.php) をインストールして有効にする必要があります。 -それをインストールして有効にして初めて、プレースホルダのための拡張構文を使うことが出来るようになります。 -すなわち、デフォルトの書式を使用する短い構文 `{プレースホルダ名, タイプ}`、あるいは、書式のスタイルを指定できる完全な構文 `{プレースホルダ名, タイプ, スタイル}` を使うことが出来るようになります。 +序数プレースホルダは、0 ベースの整数の序数をプレースホルダとして使います。 +このプレースホルダは、`Yii::t()` の呼び出しに出現する順序に従って、パラメータ値によって置き換えられます。 +次の例では、序数プレースホルダ `{0}`、`{1}` および `{2}` は、それぞれ、`$price`、`$count` および `$subtotal` の値によって置き換えられます。 -完全なリファレンスは [ICU ウェブサイト](http://icu-project.org/apiref/icu4c/classMessageFormat.html) で入手可能ですが、以下においてはいくつかの例を示します。 +```php +$price = 100; +$count = 2; +$subtotal = 200; +echo \Yii::t('app', 'Price: {0}, Count: {1}, Subtotal: {2}', $price, $count, $subtotal); +``` -#### 数値 +```php +// 日本語翻訳例: '価格: {0}, 数量: {1}, 小計: {2}' +``` + +> Tip|ヒント: たいていの場合は名前付きプレースホルダを使うべきです。 +> と言うのは、翻訳者にとっては、パラメータ名がある方が、翻訳すべきメッセージ全体をより良く理解できるからです。 + + +### パラメータのフォーマット + +メッセージのプレースホルダにフォーマットの規則を追加して指定し、パラメータ値がプレースホルダを置き換える前に適切にフォーマットされるようにすることが出来ます。 +次の例では、`price` のパラメータ値の型は数値として扱われ、通貨の形式でフォーマットされます。 + +```php +$price = 100; +echo \Yii::t('app', 'Price: {0, number, currency}', $price); +``` + +> Note|注意: パラメータのフォーマットには、[intl PHP 拡張](http://www.php.net/manual/ja/intro.intl.php) のインストールが必要です。 + +プレースホルダにフォーマット規則を指定するためには、短い構文または完全な構文のどちらかを使うことが出来ます。 + +``` +短い形式: {プレースホルダ名, パラメータの型} +完全な形式: {プレースホルダ名, パラメータの型, パラメータの形式} +``` + +このようなプレースホルダを指定する方法についての完全な説明は、[ICU ドキュメント](http://icu-project.org/apiref/icu4c/classMessageFormat.html) を参照してください。 + +以下では、よくある使用方法をいくつか示します。 + +#### 数値 ```php $sum = 42; @@ -149,7 +200,7 @@ echo \Yii::t('app', 'Balance: {0, number}', $sum); // 出力: '差引残高: 12,345' ``` -内蔵のスタイル (`integer`、`currency`、`percent`) の一つを指定することが出来ます。 +オプションで、パラメータの形式として、`integer`、`currency`、`percent` を指定することが出来ます。 ```php $sum = 42; @@ -159,7 +210,7 @@ echo \Yii::t('app', 'Balance: {0, number, currency}', $sum); // 出力: '差引残高: ¥ 12,345' ``` -または、カスタムパターンを指定することも出来ます。 +または、数値をフォーマットするカスタムパターンを指定することも出来ます。 ```php $sum = 42; @@ -171,7 +222,9 @@ echo \Yii::t('app', 'Balance: {0, number, ,000,000000}', $sum); [書式のリファレンス](http://icu-project.org/apiref/icu4c/classicu_1_1DecimalFormat.html). -#### 日付 +#### 日付 + +パラメータ値は日付としてフォーマットされます。例えば、 ```php echo \Yii::t('app', 'Today is {0, date}', time()); @@ -180,7 +233,7 @@ echo \Yii::t('app', 'Today is {0, date}', time()); // 出力: '今日は 2015/01/07 です。' ``` -内蔵の書式は、`short`、`medium`、`long`、そして `full` です。 +オプションで、パラメータの形式として、`short`、`medium`、`long`、そして `full` を指定することが出来ます。 ```php echo \Yii::t('app', 'Today is {0, date, short}', time()); @@ -189,7 +242,7 @@ echo \Yii::t('app', 'Today is {0, date, short}', time()); // 出力: '今日は 2015/01/07 です。' ``` -カスタムパターンを指定することも出来ます。 +日付の値をフォーマットするカスタムパターンを指定することも出来ます。 ```php echo \Yii::t('app', 'Today is {0, date, yyyy-MM-dd}', time()); @@ -200,7 +253,9 @@ echo \Yii::t('app', 'Today is {0, date, yyyy-MM-dd}', time()); [書式のリファレンス](http://icu-project.org/apiref/icu4c/classicu_1_1SimpleDateFormat.html). -#### 時刻 +#### 時刻 + +パラメータ値は時刻としてフォーマットされます。例えば、 ```php echo \Yii::t('app', 'It is {0, time}', time()); @@ -209,7 +264,7 @@ echo \Yii::t('app', 'It is {0, time}', time()); // 出力: '現在 22:37:47 です。' ``` -内蔵の書式は、`short`、`medium`、`long`、そして `full` です。 +オプションで、パラメータの形式として、`short`、`medium`、`long`、そして `full` を指定することが出来ます。 ```php echo \Yii::t('app', 'It is {0, time, short}', time()); @@ -218,7 +273,7 @@ echo \Yii::t('app', 'It is {0, time, short}', time()); // 出力: '現在 22:37 です。' ``` -カスタムパターンを指定することも出来ます。 +時刻の値をフォーマットするカスタムパターンを指定することも出来ます。 ```php echo \Yii::t('app', 'It is {0, date, HH:mm}', time()); @@ -230,43 +285,48 @@ echo \Yii::t('app', 'It is {0, date, HH:mm}', time()); [書式のリファレンス](http://icu-project.org/apiref/icu4c/classicu_1_1SimpleDateFormat.html). -#### 綴り +#### 綴り + +パラメータ値は数値として取り扱われ、綴りとしてフォーマットされます。例えば、 ```php -echo \Yii::t('app', '{n, number} is spelled as {n, spellout}', ['n' => 12345]); +// 出力例 : "42 is spelled as forty two" +echo \Yii::t('app', '{n, number} is spelled as {n, spellout}', ['n' => 42]); // 翻訳: '{n, number} は、文字で綴ると {n, spellout} です。' -// 出力: '12,345 は、文字で綴ると 一万二千三百四十五 です。' +// 出力: '12,345 は、文字で綴ると 四十二 です。' ``` -#### 序数 +#### 序数 + +パラメータ値は数値として取り扱われ、順序を表す文字列としてフォーマットされます。例えば、 ```php +// 出力例 : "You are the 42nd visitor here!" echo \Yii::t('app', 'You are the {n, ordinal} visitor here!', ['n' => 42]); ``` -これは、"You are the 42nd visitor here!" というメッセージになります。 - > Note|訳注: 上記のソースメッセージを、プレースホルダの書式指定を守って日本語に翻訳すると、'あなたはこのサイトの {n, ordinal} の訪問者です' となります。 > しかし、その出力結果は、'あなたはこのサイトの 第42 の訪問者です' となり、意味は通じますが、日本語としては若干不自然なものになります。 > -> プレースホルダの書式指定自体も、翻訳の対象として、より適切なものに変更することが可能です。 +> プレースホルダの書式指定自体も、翻訳の対象として、より適切なものに変更することが可能であることに注意してください。 > -> この場合も、'あなたはこのサイトの{n, plural, =1{最初} other{#番目}}の訪問者です' のように翻訳することが出来ます。 +> この場合も、'あなたはこのサイトの{n, plural, =1{最初} other{#番目}}の訪問者です' のように翻訳するほうが適切でしょう。 -#### 継続時間 +#### 継続時間 + +パラメータ値は秒数として取り扱われ、継続時間を表す文字列としてフォーマットされます。例えば、 ```php +// 出力例 : "You are here for 47 sec. already!" echo \Yii::t('app', 'You are here for {n, duration} already!', ['n' => 47]); ``` -これは、"You are here for 47 sec. already!" というメッセージになります。 - > Note|訳注: このソースメッセージを 'あなたはこのサイトに既に {n, duration} の間滞在しています' と翻訳した場合の出力結果は、'あなたはこのサイトに既に 47 の間滞在しています' となります。 > ICU ライブラリのバグでしょうか。これも、プレースホルダの書式設定も含めて全体を翻訳し直す方が良いようです。 -#### 複数形 +#### 複数形 言語によって、複数形の語形変化はさまざまに異なります。 Yii は、さまざまな形式の複数形語形変化に対応したメッセージ翻訳のための便利な方法を提供しています。 @@ -274,32 +334,28 @@ Yii は、さまざまな形式の複数形語形変化に対応したメッセ 語形変化の規則を直接に処理する代りに、特定の状況における語形変化した言葉の翻訳を提供するだけで十分です。 ```php +// $n = 0 の場合の出力例 : "There are no cats!" +// $n = 1 の場合の出力例 : "There is one cat!" +// $n = 42 の場合の出力例 : "There are 42 cats!" echo \Yii::t('app', 'There {n, plural, =0{are no cats} =1{is one cat} other{are # cats}}!', ['n' => $n]); ``` -結果は以下のようになります。 - -- `$n = 0` の場合は "There are no cats!" -- `$n = 1` の場合は "There is one cat!" -- そして `$n = 42` の場合は "There are 42 cats!" - 上記の複数形規則の引数において、`=0` はぴったりゼロ、`=1` はぴったり 1、そして `other` はそれ以外の数を表します。 `#` は `n` の値によって置き換えられます。 -英語以外の言語では、これほど単純ではありません。 -例えば、次はロシア語の例です。 + +複数形の規則が非常に複雑な言語もあります。 +例えば、次はロシア語の例では、`=1` が `n = 1` にぴったりと一致するのに対して、`one` が `21` や `101` などに一致します。 ``` Здесь {n, plural, =0{котов нет} =1{есть один кот} one{# кот} few{# кота} many{# котов} other{# кота}}! ``` -上の例について言及する価値があると思われるのは、`=1` が `n = 1` にぴったりと一致するのに対して、`one` が `21` や `101` などに一致する、ということです。 +注意して欲しいのは、上記のメッセージは主として翻訳メッセージとして使用される、という点です。 +アプリケーションの [[yii\base\Application::$sourceLanguage|ソース言語]] を `ru-RU` に設定しない限り、オリジナルのメッセージには使用されません。 -注意して欲しいのは、あなたの [[yii\base\Application::$sourceLanguage|ソース言語]] を `ru_RU` に設定しなければ、このロシア語のメッセージを `Yii::t()` の中に直接に書くことは出来ない、ということです。 -ただし、ソース言語を `ru_RU` に設定することは推奨されません。 -むしろ、このような文字列はメッセージファイルまたは (DB ソースが使われている場合は) メッセージデータベースに入れるべきです。 -Yii は翻訳された言語の文字列にある複数形規則を使います。翻訳が入手できない場合にはソース言語の複数形規則にフォールバックします。 +オリジナルのメッセージに対する翻訳が見つからない場合は、[[yii\base\Application::$sourceLanguage|ソース言語]] の複数形規則がオリジナルのメッセージに対して適用されます。 -あなたの言語について、どのような語形変化を指定すべきかを学習するためには、[unicode.org にある規則のリファレンス](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html) を参照してください。 +特定の言語について、どのような語形変化を指定すべきかを学習するためには、[unicode.org にある規則のリファレンス](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html) を参照してください。 > Note|訳注: 上記のソースメッセージの日本語翻訳は以下のようなものになります。 > @@ -308,28 +364,26 @@ Yii は翻訳された言語の文字列にある複数形規則を使います > 日本語では単数形と複数形を区別しませんので、たいていの場合、`=0` と `other` を指定するだけで事足ります。 > 横着をして、`{n, plural, ...}` を `{n, number}` に置き換えても、多分、大きな問題は生じないでしょう。 -#### 選択肢 +#### 選択肢 -キーワードに基づいて表現を選択することが出来ます。 -この場合のパターンは、キーワードに対する表現の割り当てを指定し、デフォルトの表現を提供するものです。 +パラメータの型として `select` を使うと、パラメータ値に基づいて表現を選択することが出来ます。例えば、 ```php +// 出力例 : "Snoopy is a dog and it loves Yii!" echo \Yii::t('app', '{name} is a {gender} and {gender, select, female{she} male{he} other{it}} loves Yii!', [ 'name' => 'Snoopy', 'gender' => 'dog', ]); ``` -これは "Snoopy is a dog and it loves Yii!" となります。 +上記の式の中で、`female` と `male` が `gender` が取り得る値であり、`other` がそれらに一致しない値を処理します。 +それぞれの取り得る値の後には、波括弧で囲んで対応する表現を指定します。 -式の中で、`female` と `male` が `gender` が取り得る値であり、`other` がそれらに一致しない値を処理します。 -波括弧の中の文字列は下位の式であり、単なる文字列でも、さらにプレースホルダを持つ文字列でも構いません。 - -> Note|訳注: 翻訳: '{name} は {gender} であり、{gender, select, female{彼女} male{彼} other{それ}}は Yii を愛しています。' +> Note|訳注: 日本語翻訳例: '{name} は {gender} であり、{gender, select, female{彼女} male{彼} other{それ}}は Yii を愛しています。' > -> 出力: 'Snoopy は dog であり、それは Yii を愛しています。' +> 日本語出力例: 'Snoopy は dog であり、それは Yii を愛しています。' -### デフォルトの翻訳を指定する +### デフォルトの翻訳を指定する 他の翻訳にマッチしないカテゴリのフォールバックとして使用されるデフォルトの翻訳を指定することが出来ます。 この翻訳は `*` によってマークされなければなりません。 @@ -356,7 +410,7 @@ echo Yii::t('not_specified_category', 'message from unspecified category'); この場合、メッセージは `@app/messages//not_specified_category.php` から読み込まれます。 -### モジュールのメッセージを翻訳する +### モジュールのメッセージを翻訳する モジュール用のメッセージを翻訳したいけれども、全てのメッセージに対して一つの翻訳ファイルを使うことは避けたい、という場合には、次のようにすることが出来ます。 @@ -403,7 +457,7 @@ class Module extends \yii\base\Module `fileMap` を使わずに、カテゴリを同じ名前のファイルにマップする規約を使って済ませることも出来ます。 以上のようにすれば、直接に `Module::t('validation', 'your custom validation message')` や `Module::t('form', 'some form label')` などを使用することが出来ます。 -### ウィジェットのメッセージを翻訳する +### ウィジェットのメッセージを翻訳する モジュールに適用できる同じ規則をウィジェットにも適用することが出来ます。例えば、 @@ -456,7 +510,7 @@ class Menu extends Widget > **Note**|注意: ウィジェットのためには i18n ビューも使うことが出来ます。コントローラのための同じ規則がウィジェットにも適用されます。 -### フレームワークメッセージを翻訳する +### フレームワークメッセージを翻訳する Yii には、検証エラーとその他いくつかの文字列に対するデフォルトの翻訳メッセージが付属しています。 これらのメッセージは、全て 'yii' というカテゴリの中にあります。 @@ -477,7 +531,7 @@ Yii には、検証エラーとその他いくつかの文字列に対するデ これで、あなたの修正した翻訳を `@app/messages//yii.php` に置くことが出来ます。 -### 欠落している翻訳の処理 +### 欠落している翻訳の処理 ソースに翻訳が欠落している場合でも、Yii はリクエストされたメッセージの内容を表示します。 この振舞いは、原文のメッセージが正当かつ詳細なテキストである場合には、非常に好都合です。 @@ -560,34 +614,31 @@ class TranslationEventHandler これで、(あなたがファイルベースの翻訳を選択していた場合は) `messagePath` ディレクトリにファイルが出現します。 -ビュー ------- +## ビューの翻訳 -前の項で説明したようなメッセージの翻訳の代りに、ビューで `i18n` を使ってさまざまな言語に対するサポートを提供することも出来ます。 -例えば、`views/site/index.php` というビューがあり、それのロシア語のための特別版を作りたい場合は、現在のコントローラ/ウィジェットのビューパスの下に `ru-RU` フォルダを作って、ロシア語のためのファイルを `views/site/ru-RU/index.php` として置きます。 -そうすると、Yii は、現在の言語のためのファイルが存在する場合はそれをロードし、何も見つからなかった場合はオリジナルのビューファイルにフォールバックします。 +個々のテキストメッセージを翻訳する代りに、ビュースクリプト全体を翻訳したい場合があるでしょう。 +この目的を達するためには、ビューを翻訳して、ターゲット言語と同じ名前のサブディレクトリに保存するだけで大丈夫です。 +例えば、`views/site/index.php` というビューをターゲット言語 `ru-RU` に翻訳したい場合は、翻訳したビューを `views/site/ru-RU/index.php` というファイルとして保存します。 +このようにすると、[[yii\base\View::renderFile()]] メソッド、または、このメソッドを呼び出す他のメソッド (例えば [[yii\base\Controller::render()]]) を呼んで `views/site/index.php` をレンダリングするたびに、翻訳された `views/site/ru-RU/index.php` が代りにレンダリングされるようになります。 -> **Note**|注意: 言語が `en-US` と指定されている場合、対応するビューが無いと、Yii は `en` の下でビューを探して、そこにも無ければ、オリジナルのビューを使います。 +> **Note**|注意: [[yii\base\Application::$language|ターゲット言語]] が [[yii\base\Application::$sourceLanguage|ソース言語]] と同じ場合は、翻訳されたビューの有無にかかわらず、オリジナルのビューがレンダリングされます。 -数値と日付の値を書式設定する ----------------------------- +## 数値と日付の値を書式設定する 詳細は [データフォーマッタ](output-formatting.md) の節を参照してください。 -PHP 環境をセットアップする --------------------------- +## PHP 環境をセットアップする Yii は、[[yii\i18n\Formatter]] クラスの数値や日付の書式設定や、[[yii\i18n\MessageFormatter]] を使うメッセージのフォーマッティングなど、ほとんどの国際化機能を提供するために [PHP intl 拡張](http://php.net/manual/ja/book.intl.php) を使います。 この二つのクラスは、`intl` がインストールされていない場合に備えて基本的な機能を提供するフォールバックを実装しています。 -だだし、このフォールバックの実装は、英語のサイトでのみ十分に機能するものであり、たとえ英語のサイトであっても、PHP intl 拡張によって利用可能になる一連の豊かな機能を提供できるものではありません。 -従って、PHP intl 拡張のインストールが強く推奨されます。 +だだし、このフォールバックの実装は、英語がターゲット言語である場合にのみ十分に機能するものす。 +従って、国際化機能が必要とされる場合は、`intl` をインストールすることが強く推奨されます。 [PHP intl 拡張](http://php.net/manual/ja/book.intl.php) は、さまざまに異なる全てのロケールについて知識と書式の規則を提供する [ICU ライブラリ](http://site.icu-project.org/) に基礎を置いています。 -この事実により、日付や数値の書式設定、また、メッセージのフォーマッティングで利用できる構文は、PHP バイナリとともにコンパイルされる ICU ライブラリのバージョンの違いによって異なってきます。 - -あなたのウェブサイトが全ての環境で同じ出力をすることを保証するためには、全ての環境において PHP intl 拡張をインストールし、PHP とともにコンパイルされた ICU ライブラリのバージョンが同一であることを確認することが推奨されます。 +ICU のバージョンが異なると、日付や数値のフォーマットの結果も異なる場合があります。 +あなたのウェブサイトが全ての環境で同じ出力をすることを保証するためには、全ての環境において同じバージョンの PHP intl 拡張 (従って同じバージョンの ICU) をインストールすることが推奨されます。 どのバージョンの ICU が PHP によって使われているかを知るために、次のスクリプトを走らせることが出来ます。 このスクリプトは、使用されている PHP と ICU のバージョンを出力します。 @@ -598,11 +649,12 @@ echo "PHP: " . PHP_VERSION . "\n"; echo "ICU: " . INTL_ICU_VERSION . "\n"; ``` -このドキュメントで説明されている全ての機能を使うことが出来るように、ICU のバージョンが 49 以上であることを推奨します。 -49 未満のバージョンに欠落している主要な機能の一つが、複数形規則における `#` プレースホルダです。 +さらに、バージョン 49 以上の ICU を使用する事も推奨されます。 +そうすることによって、このドキュメントで説明されている全ての機能を使うことが出来るようになります。 +例えば、49 未満の ICU は、複数形規則における `#` プレースホルダをサポートしていません。 入手できる ICU バージョン については、 を参照してください。 -バージョン番号の採番方式が 4.8 リリースの後に変更されて、最初の二つの数字が結合されたことに注意してください。 -すなわち、ICU 4.8、ICU 49、ICU 50 という順序です。 +バージョン番号の採番方式が 4.8 リリースの後に変更されたことに注意してください +(すなわち、ICU 4.8、ICU 49、ICU 50、等々となっています)。 これに加えて、ICU ライブラリとともに出荷されるタイムゾーンデータベースの情報も古くなっている可能性があります。 タイムゾーンデータベースの更新に関する詳細は [ICU マニュアル](http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data) を参照してください。