国際化と地域化¶

言語ファイル¶

翻訳はアプリケーションの中にある言語ファイルを使って有効になります。 CakePHP 翻訳ファイルのデフォルトの形式は、 Gettext です。ファイルは resources/locales/ 以下に置かれる必要があります。各言語用のサブフォルダーは 以下のようになっている必要があります。

/resources
    /locales
        /en_US
            default.po
        /en_GB
            default.po
            validation.po
        /es
            default.po

デフォルトのドメインは 'default' です。ロケールフォルダーは上記のように少なくとも default.po ファイルを含まなくてはなりません。ドメインは翻訳メッセージの任意のグルーピングを参照します。 グループが使われていない場合、デフォルトのグループが選択されます。

CakePHP のライブラリーから抜き出されたコアの文字列は resources/locales/ 内の cake.po という名前の ファイルに分けて置かれます。 CakePHP localized library は、コア (Cake のドメイン) の中にクライエント・フェイシングな翻訳文字列を置いています。 これらのファイルを利用するには、期待された場所 resources/locales/<locale>/cake.po にリンク またはコピーをしてください。もし不完全または正しくない場合は、修正するためにこのリポジトリーに PR を送ってください。

プラグインは、翻訳ファイルをも含みます。プラグインの名前が under_scored なバージョンのものを、 翻訳メッセージのドメインとして利用する方法は以下の通りです。

MyPlugin
    /resources
        /locales
            /fr
                my_plugin.po
            /de
                my_plugin.po

翻訳フォルダーは、2文字または3文字の言語 ISO コード、または、言語及び話されている国を含む fr_FR, es_AR, da_DK のような完全なロケールの名称にしてください。

https://www.localeplanet.com/icu/ (参考)

翻訳ファイルの具体例は以下のようになります。

msgid "My name is {0}"
msgstr "Je m'appelle {0}"

msgid "I'm {0,number} years old"
msgstr "J'ai {0,number} ans"

I18n を利用して Pot ファイルを生成する¶

アプリケーション内の、 __() や他の国際化されたメッセージから pot ファイルを生成するためには、 i18n シェルを利用できます。より知りたい場合は、 次の章 を読んでください。

デフォルトのロケールを設定する¶

デフォルトのロケールは config/app.php ファイルの App.defaultLocale を以下のようにすることで設定できます。

'App' => [
    ...
    'defaultLocale' => env('APP_DEFAULT_LOCALE', 'en_US'),
    ...
]

これは、CakePHP が提供している地域化のライブラリーを使うと示されている場合いつでも、 デフォルトの翻訳言語、日付のフォーマット、番号のフォーマットおよび通貨を含む、 アプリケーションのいくつかの様相をコントロールします。

実行時にロケールを変更する¶

翻訳文字列の言語を変更する場合はこのメソッドを呼び出せます。

use Cake\I18n\I18n;

I18n::setLocale('de_DE');

地域化のツールを使うと、これは数字や日付がどのようにフォーマットされているかについても変更します。

翻訳メッセージで変数を利用する¶

翻訳関数を利用すると、メッセージの中あるいは翻訳された文字列の中で定義された特別なマーカーを 用いているメッセージの中で変数を補完することができます。

echo __("Hello, my name is {0}, I'm {1} years old", ['Sara', 12]);

マーカーは数値で、渡された配列のキーに対応します。関数に独立した引数として変数を渡すことも可能です。

echo __("Small step for {0}, Big leap for {1}", 'Man', 'Humanity');

あらゆる翻訳関数はプレースホルダーの置き換えに対応しています。

__d('validation', 'The field {0} cannot be left empty', 'Name');

__x('alphabet', 'He read the letter {0}', 'Z');

' (シングルクオーテーション) は、翻訳メッセージの中ではエスケープコードとして扱われます。 シングルクオーテーションの間の変数は、置き換えられませんし、文字通りのテキストとして扱われます。 例えば、

__("This variable '{0}' be replaced.", 'will not');

変数の中で2つ連続してクオーテーションを用いると適切に置き換えられます。

__("This variable ''{0}'' be replaced.", 'will');

これらの関数は ICU MessageFormatter を活用しています。そのためメッセージと地域化された日付や番号、通貨とを同時に翻訳することが可能です。

echo __(
    'Hi {0}, your balance on the {1,date} is {2,number,currency}',
    ['Charles', new FrozenTime('2014-01-13 11:12:00'), 1354.37]
);

// 結果
Hi Charles, your balance on the Jan 13, 2014, 11:12 AM is $ 1,354.37

プレースホルダーの中の数字は、出力のきめ細やかなコントロールによって、同様にフォーマットされます。

echo __(
    'You have traveled {0,number} kilometers in {1,number,integer} weeks',
    [5423.344, 5.1]
);

// 結果
You have traveled 5,423.34 kilometers in 5 weeks

echo __('There are {0,number,#,###} people on earth', 6.1 * pow(10, 8));

// 結果
There are 6,100,000,000 people on earth

以下は、 number という言葉の後に続けられるフォーマット修飾子のリストです:

• integer: 小数の部分を取り除く

• currency: 地域の通貨、を利用し、小数点以下を丸めます

• percent: パーセントとして数をフォーマットします

日付は、プレースホルダーの数値の後に date という語を利用することによってフォーマットされます。 以下は特別なオプションのリストです:

• short

• medium

• long

• full

プレースホルダーの数値の後に time という語も使用でき、 date と同じオプションとして認識されます。

複数形¶

見せる言語によって、メッセージを正しく複数形にすることは、アプリケーションの国際化において 重要な部分のひとつです。CakePHP はメッセージの中の複数形を正しく選択するいつかの方法を提供しています。

msgid "{0,plural,=0{No records found} =1{Found 1 record} other{Found # records}}"
msgstr "{0,plural,=0{Ningún resultado} =1{1 resultado} other{# resultados}}"

msgid "{placeholder,plural,=0{No records found} =1{Found 1 record} other{Found {1} records}}"
msgstr "{placeholder,plural,=0{Ningún resultado} =1{1 resultado} other{{1} resultados}}"

__('{0,plural,=0{No records found }=1{Found 1 record} other{Found # records}}', [0]);

// 引数 {0} を 0 として "Ningún resultado" を返します。

__('{0,plural,=0{No records found} =1{Found 1 record} other{Found # records}}', [1]);

// 引数 {0} は 1 なので "1 resultado" を返します。

__('{placeholder,plural,=0{No records found} =1{Found 1 record} other{Found {1} records}}', [0, 'many', 'placeholder' => 2])

// 引数 {placeholder} は 2 で、引数 {1} は 'many' なので
// "many resultados" を返します。

{ [count placeholder],plural, case1{message} case2{message} case3{...} ... }

msgid "search.results"
msgstr "{0,plural,=0{Ningún resultado} =1{1 resultado} other{{1} resultados}}"

__('search.results', [2, 2]);

// 戻り値: "2 resultados"

=0{No results} =1{...} other{...}

zero{No Results} one{One result} few{...} many{...} other{...}

# One message identifier for singular
msgid "One file removed"
# Another one for plural
msgid_plural "{0} files removed"
# Translation in singular
msgstr[0] "Un fichero eliminado"
# Translation in plural
msgstr[1] "{0} ficheros eliminados"

// 戻り値: "10 ficheros eliminados"
$count = 10;
__n('One file removed', '{0} files removed', $count, $count);

// ドメインの中でそれを使うことが可能です。
__dn('my_plugin', 'One file removed', '{0} files removed', $count, $count);

msgid "One file removed"
msgid_plural "{0} files removed"
msgstr[0] "{0} datoteka je uklonjena"
msgstr[1] "{0} datoteke su uklonjene"
msgstr[2] "{0} datoteka je uklonjeno"

メッセージのパーサーを作成する¶

CakePHP が利用しているものと同じやり方を使い続けることもできますが、 PoFileParser 以外のメッセージパーサーを利用してみてください。たとえば、 YAML を用いた翻訳メッセージを 読み込みたい場合、まずはじめにパーサークラスを作成する必要があります。

namespace App\I18n\Parser;

class YamlFileParser
{
    public function parse($file)
    {
        return yaml_parse_file($file);
    }
}

アプリケーションの src/I18n/Parser ディレクトリー内にこのファイルを作成してください。 続いて、 resources/locales/fr_FR/animals.yaml として翻訳ファイルを作ります。

Dog: Chien
Cat: Chat
Bird: Oiseau

最後に、翻訳を読み込むドメインと場所を設定します。

use Cake\I18n\MessagesFileLoader as Loader;

I18n::setTranslator(
    'animals',
    new Loader('animals', 'fr_FR', 'yaml'),
    'fr_FR'
);

包括的な翻訳機構を作成する¶

対応が必要なドメインおよび場所ごとに、 I18n::translator() を呼び出して翻訳機構を設定するのは、 非常に面倒です。わずかな違いで対応が必要な場合は特にです。この問題を避けるために、CakePHP では ドメインごとに包括的な翻訳機構のローダーを定義することができます。

デフォルトのドメインとあらゆる言語のすべての翻訳を、外部のサービス読み込みたいときのことを 想像してみてください。

use Cake\I18n\Package;
// Prior to 4.2 you need to use Aura\Intl\Package

I18n::config('default', function ($domain, $locale) {
    $locale = Locale::parseLocale($locale);
    $lang = $locale['language'];
    $messages = file_get_contents("http://example.com/translations/$lang.json");

    return new Package(
        'default', // フォーマット機構
        null, // フォールバック (デフォルトドメインにはありません)
        json_decode($messages, true)
    )
});

上記の例は、翻訳を含む JSON ファイルを読み込む外部のサービスの例です。 アプリケーション内で リクエストされたどの場所でも Package オブジェクトをビルドします。

特定のローダーが設定されていない全てのパッケージで、パッケージをロードする方法を変更したい場合、 _fallback パッケージを使用することによって、代替パッケージローダーに置き換えることができます。

I18n::config('_fallback', function ($domain, $locale) {
    // パッケージを生成するカスタムコードはこちら。
});

独自の翻訳機構における複数形と文脈について¶

setMessages() に用いられている配列は、異なるドメイン配下にメッセージを翻訳機構が置くために 指示をだす、または、Gettext の複数形選択のきっかけとなるために作成されます。 以下は、異なる文脈において同じキーを翻訳に設置する例です。

[
    'He reads the letter {0}' => [
        'alphabet' => 'Él lee la letra {0}',
        'written communication' => 'Él lee la carta {0}'
    ]
]

同様にして、メッセージの配列で用いられているGettextの複数形を、複数形ごとのキーを用いて ネストされた配列で表現することもできます。

[
    'I have read one book' => 'He leído un libro',
    'I have read {0} books' => [
        'He leído un libro',
        'He leído {0} libros'
    ]
]

異なるフォーマット機構を使う¶

前の例では最初の引数として default を用いるようにパッケージが作成されていました。そして、 これは使用されているフォーマット機構と対応するコメントを示します。 フォーマット機構は、翻訳メッセージに変数を渡す、そして正しい複数形を選択するクラスです。

もし、レガシーなアプリケーションを扱っている、あるいは ICU メッセージフォーマットが提供している機能が 必要ない場合、CakePHP は sprinf フォーマット機構も提供しています。

return Package('sprintf', 'fallback_domain', $messages);

翻訳されるメッセージは sprintf() 関数に引数を入れて引き渡されます。

__('Hello, my name is %s and I am %d years old', 'José', 29);

デフォルトのフォーマット機構を最初に使われる以前の CakePHP に作成されたすべての翻訳機構に 設置することができます。

これは、 translator() や config() メソッドを使って手で作成された翻訳機構を含みません。

I18n::defaultFormatter('sprintf');

地域化された日時データをパースする¶

リクエストから地域化されたデータを受け取る場合、ユーザーが地域化したフォーマットから日時の情報を 取得するのが良いでしょう。コントローラー、あるいは ミドルウェア では、 日付、時刻、そして日時の型が地域化のフォーマットをパースするために定義できます。

use Cake\Database\TypeFactory;

// デフォルトのロケールフォーマットのパースを有効化
TypeFactory::build('datetime')->useLocaleParser();

// カスタム datetime フォーマットパース書式の設定
TypeFactory::build('datetime')->useLocaleParser()->setLocaleFormat('dd-M-y');

// IntlDateFormatter 定数を使用することもできます。
TypeFactory::build('datetime')->useLocaleParser()
    ->setLocaleFormat([IntlDateFormatter::SHORT, -1]);

デフォルトでパースするフォーマットは、デフォルトの文字列のフォーマットと同じです。

リクエストデータをユーザーのタイムゾーンから変換する¶

様々なタイムゾーンのユーザーからのデータを扱う場合には、 リクエストデータにおける日時をアプリケーションのタイムゾーンへ変換する必要が出てきます。 この処理を簡単にするために、 コントローラーもしくは ミドルウェア の setUserTimezone() を使うことができます:

// ユーザーのタイムゾーンを設定する
TypeFactory::build('datetime')->setUserTimezone($user->timezone);

いったん設定をすると、アプリケーションがリクエストデータからエンティティーを作成もしくは更新をする時に、 ORM が日時の値をユーザーのタイムゾーンからアプリケーションのタイムゾーンへ自動で変換します。 これは、常にアプリケーションが App.defaultTimezone で定義されたタイムゾーンで動作することを保証します。

あなたのアプリケーションが様々なアクションにおける日時の情報を扱う場合、 ミドルウェアを使ってタイムゾーンの変換とロケールのパースの両方を設定することができます:

namespace App\Middleware;

use Cake\Database\TypeFactory;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

class DatetimeMiddleare implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        // リクエストからユーザーを取得
        // この例では、ユーザーエンティティーにタイムゾーン属性があるものと仮定
        $user = $request->getAttribute('identity');
        if ($user) {
            TypeFactory::build('datetime')
                ->useLocaleParser()
                ->setUserTimezone($user->timezone);
        }

        return $handler->handle($request);
    }
}