Programmer's Reference Guide

翻訳用の追加機能

Zend_Translate がサポートする機能は他にもあります。ここに、追加情報をまとめました。

アダプタのオプション

すべてのアダプタで、オプションを使用できます。もちろん、アダプタによってオプションは異なります。アダプタを作成する際に、オプションを設定できます。すべてのアダプタで共通のオプションは 'clear' で、これは、翻訳データを既存のものに追記するのかしないのかを指定します。標準の動作は、新しい翻訳を既存の翻訳に追記します。しかし、これを指定すると、既存の翻訳データをいったん消去して新しいデータを追加します。消去されるのは選択した言語のみであり、その他の言語は影響を受けません。

オプションを一時的に設定するには、 addTranslation($data, $locale, array $options = array()) とオプションの三番目のパラメータを指定します。 setOptions() 関数でオプションを設定することもできます。

例1 翻訳オプションの使用

// ':' を、翻訳ソースファイルの区切り文字として指定します
$options = array('delimiter' => ':');
$translate = new Zend_Translate(
    'csv',
    '/path/to/mytranslation.csv',
    'de',
    $options);
 
...
 
// 定義されている言語を消去し、新しい翻訳データを使用します
$options = array('clear' => true);
$translate->addTranslation('/path/to/new.csv', 'fr', $options);

各アダプタで使用できるオプションについて、その使用法を以下にまとめます。

**翻訳アダプタのオプション**
オプション	アダプタ	説明	デフォルト値
clear	すべて	true にすると、既に読み込んでいる翻訳を消去します。新しい翻訳データを読み込む際に、新しいインスタンスを作成する代わりに使用します。	false
disableNotices	すべて	true に設定すると、翻訳が存在しないことについての注意メッセージを無効にします。実運用環境ではこのオプションを true に設定しなければなりません。	false
ignore	すべて	このプレフィックスで始まるすべてのディレクトリとファイルが、ファイルを探す際に無視されます。この値のデフォルトは '.' で、すべての隠しファイルを無視するようになります。この値を 'tmp' に設定すると、たとえば 'tmpImages' や 'tmpFiles' といった名前のファイルやディレクトリ (とその配下のすべてのディレクトリ) を無視します。	.
log	すべて	未翻訳のメッセージや注意が書き込まれる Zend_Log のインスタンス	null
logMessage	すべて	ログに書き込まれるメッセージ	Untranslated message within '%locale%': %message%
logUntranslated	すべて	このオプションを true に設定すると、翻訳できなかったすべてのメッセージ ID が添付のログに書き込まれます。	false
reload	すべて	このオプションを true に設定すると、ファイルはキャッシュに再読み込みされます。このオプションはキャッシュの再作成や、キャッシュが既に作成された後で、キャッシュ済みのデータに翻訳を追加するために使えます。	false
scan	すべて	null にすると、ディレクトリ構造のスキャンを行いません。 `Zend_Translate::LOCALE_DIRECTORY` にすると、ディレクトリからロケールを検出します。 `Zend_Translate::LOCALE_FILENAME` にすると、ファイル名からロケールを検出します。詳細は自動的なソースの検出を参照ください。	null
delimiter	Csv	ソースと翻訳を区切る際に使用する記号を指定します。	;
enclosure	Csv	値を囲むための文字を定義します。デフォルトはダブルクォートです。	"
length	Csv	CSV の行の長さの最大値を定義します。0 にすると、自動的に検出します。	0

自分でオプションを定義すれば、それをすべてのアダプタで使用できます。オプションを定義するには setOptions() メソッドを使用します。 setOptions() には、指定したいオプションの配列を渡します。指定したオプションがすでに存在する場合は、上書きされます。存在しないオプションを指定した場合はアダプタは何もしないので、必要となるであろうオプションはすべて指定しておけます。アダプタが使用している既存オプションは上書きされないことに注意してください。

現在設定されているオプションを取得するには getOptions() メソッドを使用します。 getOptions() をパラメータなしでコールすると、すべてのオプションを返します。オプションのパラメータを指定した場合は、特定のオプションの内容のみを返します。

言語の処理

複数の言語を使用する場合に便利なメソッドを紹介します。

getLocale() メソッドを使用すると、実際に設定されている言語を取得できます。これは、Zend_Locale のインスタンスかロケール ID のいずれかとなります。

setLocale() メソッドは、翻訳用の新しい標準言語を設定します。これを使用すると、 translate() に毎回オプションの言語パラメータを指定する必要がなくなります。指定した言語が存在しない場合やその言語用の翻訳データがない場合、もし地域指定のない言語があれば setLocale() は代わりにそれを使用しようとします。つまり、たとえば en_US の場合だと代わりに en を使用するということです。これも見つからない場合は、例外をスローします。

isAvailable() メソッドは、指定した言語が既に存在するかどうかを調べます。指定した言語のデータが存在する場合に TRUE を返します。

また、 getList() メソッドを使用すると、そのアダプタに設定されている言語の一覧を配列で取得できます。

例2 アダプタの言語の処理

// 現在設定されている言語を返します
$actual = $translate->getLocale();
 
// 翻訳時にオプションのパラメータで言語を指定できます
echo $translate->_("my_text", "fr");
// あるいは新しい言語を設定することもできます
$translate->setLocale("fr");
echo $translate->_("my_text");
// 基底言語を参照します
// fr_CH は fr となります
$translate->setLocale("fr_CH");
echo $translate->_("my_text");
 
// この言語が存在するかどうかを調べます
if ($translate->isAvailable("fr")) {
    // 存在します
}

言語の自動処理

新しい翻訳ソースの追加を addTranslation() メソッドでのみ行っている場合は、自動ロケール 'auto' あるいは 'browser' を使用していれば Zend_Translate が環境にあわせて適切な言語を自動設定します。つまり、通常は setLocale() をコールする必要はありません。これは、自動ソース検出と組み合わせて使用しなければなりません。

ユーザのブラウザやサーバの環境に応じて、最適なロケールを探します。詳細は、以下の例を参照ください。

例3 言語の自動検出の動作例

// ブラウザから返される言語設定は次のようなものであると仮定します
// HTTP_ACCEPT_LANGUAGE = "de_AT=1;fr=1;en_US=0.8";
 
// 例 1:
// 適切な言語がみつからないので、メッセージ ID を返します
$translate = new Zend_Translate(
    'gettext',
    'my_it.mo',
    'auto',
    array('scan' => Zend_Translate::LOCALE_FILENAME));
 
// 例 2:
// 適切な言語は 'fr' となります
$translate = new Zend_Translate(
    'gettext',
    'my_fr.mo',
    'auto',
    array('scan' => Zend_Translate::LOCALE_FILENAME));
 
// 例 3:
// 適切な言語は 'de' となります。'de_AT' の代替言語は 'de' だからです
$translate = new Zend_Translate(
    'gettext',
    'my_de.mo',
    'auto',
    array('scan' => Zend_Translate::LOCALE_FILENAME));
 
// 例 4:
// 翻訳ソースとして 'it' を返し、自動設定を上書きします
$translate = new Zend_Translate(
    'gettext',
    'my_it.mo',
    'auto',
    array('scan' => Zend_Translate::LOCALE_FILENAME));
 
$translate->addTranslation('my_ru.mo', 'ru');
$translate->setLocale('it_IT');

setLocale() メソッドで言語を手動設定したら、自動設定機能は無効となります。

自動検出を再度有効にしたい場合は、 setLocale() で言語として auto を指定します。これにより、Zend_Translate の自動検出機能が再度有効になります。

Zend Framework 1.7.0 以降では、Zend_Translate はアプリケーション単位でのロケールの使用にも対応します。そのためには、Zend_Locale のインスタンスを以下のようにレジストリに登録します。このようにすれば、同じロケールを何度も使用したいときに各インスタンスで毎回ロケールを設定する手間を省けます。

// 起動ファイルで
$locale = new Zend_Locale();
Zend_Registry::set('Zend_Locale', $locale);
 
// リクエストされた言語が存在しない場合のデフォルト言語
$defaultlanguage = 'en';
 
// アプリケーションのどこかで
$translate = new Zend_Translate('gettext', 'my_de.mo');
 
if (!$translate->isAvailable($locale->getLanguage())) {
    // 存在しない言語をリクエストされた場合はデフォルト設定を使用します
    $translate->setLocale($defaultlanguage);
}
 
$translate->getLocale();

自動的なソースの検出

Zend_Translate は、翻訳ソースを自動的に検出できます。つまり、各ソースファイルを手動で宣言する必要はないということです。そんな作業は Zend_Translate に任せてしまい、ディレクトリ内からソースファイルを見つけさせることができるのです。

注意: 自動的なソース検出機能は、Zend Framework バージョン 1.5 以降で使用可能です。

使用法は、翻訳ソースを個別に登録していくのとほとんど同じですが、ひとつだけ違う点があります。ファイル名の代わりに、ソースを探すディレクトリを指定するのです。

例4 ディレクトリを指定してソースを探す

// 以下のようなディレクトリ構造があることを想定しています
//  /language/
//  /language/login/login.tmx
//  /language/logout/logout.tmx
//  /language/error/loginerror.tmx
//  /language/error/logouterror.tmx
 
$translate = new Zend_Translate('tmx', '/language');

Zend_Translate は、指定したディレクトリだけでなくそのサブディレクトリすべてから翻訳ソースファイルを探します。おかげで、非常に簡単に使用できるようになっています。しかし、Zend_Translate ではソースを含まないファイルは無視します。また翻訳データの読み込みに失敗した場合もそのファイルを無視します。つまり、翻訳ソースが正しい形式であることと読み込み可能であることを確認しておく必要があります。ファイルの形式が間違っていたり読み込みに失敗したりした場合でもエラーは発生しないからです。

注意: ディレクトリ階層の深さやその中のファイルの数によっては、 Zend_Translate の処理に長い時間がかかることもあります。

この例では TMX フォーマットを使用しており、言語の情報をソース内に含んでいます。しかし、他のフォーマットの多くは言語の情報をファイル内に持たせられません。そんなソースであっても自動検索できます。ただし、次に示す条件を満たす必要があります。

ディレクトリ名からの言語の取得

自動的に言語を検出させる方法のひとつは、言語名を表すディレクトリの配下にソースファイルを配置することです。これはもっとも簡単な方法であり、標準的な gettext の実装でも用いられています。

Zend_Translate に 'scan' オプションを指定すると、ディレクトリ名から言語を検出できます。詳細は次の例を参照ください。

例5 ディレクトリ名による言語の検出

// 以下のようなディレクトリ構造があることを想定しています
//  /language/
//  /language/de/login/login.mo
//  /language/de/error/loginerror.mo
//  /language/en/login/login.mo
//  /language/en/error/loginerror.mo
 
$translate = new Zend_Translate(
    'gettext',
    '/language',
    null,
    array('scan' => Zend_Translate::LOCALE_DIRECTORY));

注意: これが動作するのは、ソースファイル中に言語情報を持たないフォーマットを使用している場合のみです。たとえば TMX などでこのオプションを使用しても、無視されます。また、このオプションを使用した場合はファイル名による言語の自動検出は無視されます。

注意: 同じ構造のもとで複数のサブディレクトリがある場合は注意が必要です。たとえば /language/module/de/en/file.mo のような構造を考えてみましょう。このパスには、ロケールと検出されうる文字列が複数含まれています。 de と en です。このような場合は、ファイル名による検出を用いることを推奨します。

ファイル名からの言語の取得

言語を自動検出するもうひとつの方法は、特別なファイル名を使用することです。ファイル名を言語名そのものにするか、あるいはその一部に言語名を含めます。この方式を使用する場合は、初期化時に 'scan' オプションを設定する必要があります。ファイル名のつけかたには、以下に示すようにいくつかの方法があります。

例6 ファイル名からの言語の取得

// 以下のようなディレクトリ構造があることを想定しています
//  /language/
//  /language/login/login_en.mo
//  /language/login/login_de.mo
//  /language/error/loginerror_en.mo
//  /language/error/loginerror_de.mo
 
$translate = new Zend_Translate(
    'gettext',
    '/language',
    null,
    array('scan' => Zend_Translate::LOCALE_FILENAME));

ファイル名全体

言語名そのものをファイル名にしてしまうのは一番シンプルな方法ですが、同一ディレクトリにソースファイルがひとつだけの場合にしか使用できません。

/languages/
/languages/en.mo
/languages/de.mo
/languages/es.mo

ファイルの拡張子

もうひとつのシンプルな方法としては、ファイル名の拡張子を用いて言語を検出させるというものがあります。しかしこの方法にも問題があり、本来の拡張子が何であったのかがわからなくなります。

/languages/
/languages/view.en
/languages/view.de
/languages/view.es

ファイル名の一部

Zend_Translate は、ファイル名の一部に言語名が含まれている場合にもそれを検出できます。しかし、この方式を使用する場合は言語名をトークンで分割する必要があります。トークンとしてサポートされているのは、小数点 '.' かアンダーライン '_'、あるいはハイフン '=' のいずれかです。

/languages/
/languages/view_en.mo -> 英語となります
/languages/view_de.mo -> ドイツ語となります
/languages/view_it.mo -> イタリア語となります

ロケールとして判断できる部分が複数あった場合は、最初に見つかったものを使用します。詳細は次の例でご確認ください。

/languages/
/languages/view_en_de.mo -> 英語となります
/languages/view_en_es.mo -> 英語となり、最初のファイルを上書きします
/languages/view_it_it.mo -> イタリア語となります

3 種類のトークンのどれを用いても言語を検出できます。まず最初に使用するのが小数点 '.'、次に使用するのがアンダーライン '_'、そして最後に使用するのがハイフン '-' となります。ひとつのファイル名の中に複数のトークンが用いられている場合、トークンの優先順位の順に調べて最初に見つかったものを使用します。詳細は次の例でご確認ください。

/languages/
/languages/view_en-it.mo -> 英語となります。'_' のほうが '-' より優先されるからです
/languages/view-en_it.mo -> イタリア語となります。'_' のほうが '-' より優先されるからです
/languages/view_en.it.mo -> イタリア語となります。'.' のほうが '_' より優先されるからです

翻訳の確認

通常は、テキストが翻訳されているかどうかを気にすることはありません。しかし、そのテキストが翻訳されているかどうかを、ソースコードから調べたいこともあるでしょう。そんな場合に使用するメソッドが isTranslated() です。

isTranslated($messageId, $original = false, $locale = null) の最初のパラメータには、翻訳されているかどうかを調べたいテキストを指定します。また、オプションの三番目のパラメータには、翻訳を調べたいロケールを指定します。オプションの二番目のパラメータで指定するのは、その言語に完全に一致した翻訳があるのか、あるいはもう少し広い範囲の翻訳を使用するのかという内容です。たとえば、あるテキストについて 'en' の翻訳はあるが 'en_US' の翻訳はないといった場合、通常は 'en' の翻訳を取得することになるでしょう。しかし $original を true にしておくと、このような場合は isTranslated() は false を返すようになります。

例7 テキストの翻訳が存在するかどうかの確認

$english = array(
    'message1' => 'Nachricht 1',
    'message2' => 'Nachricht 2',
    'message3' => 'Nachricht 3');
 
$translate = new Zend_Translate('array', $english, 'de_AT');
 
if ($translate->isTranslated('message1')) {
    print "'message1' の翻訳が存在します";
}
 
if (!($translate->isTranslated('message1', true, 'de'))) {
    print "'message1' は 'de' に翻訳することはできません。"
        . "'de_AT' 用の翻訳しかありません";
}
 
if ($translate->isTranslated('message1', false, 'de')) {
    print "'message1' は 'de_AT' に翻訳できます。もし存在しない場合は代替として 'de' を使用できます";
}

見つからなかった翻訳をログに記録する方法

大規模なサイトを管理していたり翻訳ファイルを手作業で作ったりしている場合に、うまく翻訳ができないメッセージに悩まされることがよくあるでしょう。 Zend_Translate を使っていれば、こんなときにも簡単な解決方法があります。

そのためには、次の 2、3 のステップに従う必要があります。まず Zend_Log のインスタンスを作成します。そして、そのインスタンスを Zend_Translate にアタッチします。次の例を参照ください。

例8 翻訳のログ出力

$translate = new Zend_Translate('gettext', $path, 'de');
 
// log のインスタンスを作成します
$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
$log    = new Zend_Log($writer);
 
// それを translation インスタンスにアタッチします
$translate->setOptions(array(
    'log'             => $log,
    'logUntranslated' => true));
 
$translate->translate('unknown string');

これで、Untranslated message within 'de': unknown string のような注意メッセージがログに記録されるようになるでしょう。

注意: 翻訳が見つからなかったものがすべてログに記録されることに注意しましょう。つまり、サポートしていない言語でのリクエストがユーザからあった場合は、すべての翻訳がログに記録されるということです。また、翻訳不能なメッセージへのリクエストは毎回ログに記録されます。つまり、100 人の人が同じ翻訳をリクエストしたら、 100 件のログが記録されるというわけです。

この機能はメッセージのログ出力だけに使うことはできず、同時にこの「未翻訳」メッセージを空の翻訳ファイルにアタッチします。これを記録するには、好みの書式で書き出して先頭の "Untranslated message" を除去するログライターを自作しなければなりません。

'logMessage' オプションを設定すると、独自のログメッセージを使用できます。 '%message%' トークンはログメッセージ内で messageId に置き換えられ、'%locale%' トークンは要求されたロケールに置き換えられます。ログメッセージを自分で定義する方法については次の例を参照ください。

例9 自分で定義したログメッセージ

$translate = new Zend_Translate('gettext', $path, 'de');
 
// log のインスタンスを作成します
$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
$log    = new Zend_Log($writer);
 
// それを translation インスタンスにアタッチします
$translate->setOptions(array(
    'log'             => $log,
    'logMessage'      => "Missing '%message%' within locale '%locale%'",
    'logUntranslated' => true));
 
$translate->translate('unknown string');

ソースデータへのアクセス

時には、翻訳前のソースデータにアクセスしたいこともあるでしょう。そんなときのために２つのメソッドを用意しています。

getMessageIds($locale = null) メソッドは、すべてのメッセージの ID を配列で返します。

そして、 getMessages($locale = null) メソッドは翻訳前のソースを配列で返します。メッセージ ID がキー、それに対応するデータが値となります。

どちらのメソッドについても、オプションのパラメータ $locale を指定できます。これを指定すると、指定した言語についての翻訳情報を返します。このパラメータを省略した場合は、実際に設定されている言語を対象とします。注意してほしいのは、普通はすべての言語ですべての翻訳が存在すべきであるということです。つまり、通常はこのパラメータを指定する必要はないはずです。

さらに、 getMessages() メソッドで翻訳辞書全体を返すこともできます。その際には、疑似ロケール 'all' を指定します。これを指定すると、追加された各ロケールについてのすべての翻訳データを返します。

注意: 注意: 追加されているロケールの数や翻訳データの量によっては、返される配列は 非常に大きな ものとなります。

例10 アダプタでの言語の処理

// すべてのメッセージ ID を返します
$messageIds = $translate->getMessageIds();
print_r($messageIds);
 
// あるいは指定した言語の ID を返します
$messageIds = $translate->getMessageIds('en_US');
print_r($messageIds);
 
// すべての翻訳データを返します
$source = $translate->getMessages();
print_r($source);