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

addTranslation()に与えることによって、 一時的にオプションをセットできます。 そして、オプションを固定で設定するには、メソッド setOptions()を使えます。

// ':' を、翻訳ソースファイルの区切り文字として指定します
$translate = new Zend_Translate(
    array(
        'adapter' => 'csv',
        'content' => '/path/to/mytranslation.csv',
        'locale'  => 'de',
        'delimiter' => ':'
    )
);

...

// 定義されている言語を消去し、新しい翻訳データを使用します
$translate->addTranslation(
    array(
        'content' => '/path/to/new.csv',
        'locale'  => 'fr',
        'clear'   => true
    )
);

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

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

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

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

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

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

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

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

// 現在設定されている言語を返します
$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")) {
    // 存在します
}

// ブラウザから返される言語設定は次のようなものであると仮定します
// HTTP_ACCEPT_LANGUAGE = "de_AT=1;fr=1;en_US=0.8";

// 例 1:
// 適切な言語がみつからないので、メッセージ ID を返します
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => 'my_it.mo',
        'locale'  => 'auto',
        'scan' => Zend_Translate::LOCALE_FILENAME
    )
);

// 例 2:
// 適切な言語は 'fr' となります
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => 'my_fr.mo',
        'locale'  => 'auto',
        'scan' => Zend_Translate::LOCALE_FILENAME
    )
);

// 例 3:
// 適切な言語は 'de' となります。'de_AT' の代替言語は 'de' だからです
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => 'my_de.mo',
        'locale'  => 'auto',
        'scan' => Zend_Translate::LOCALE_FILENAME
    )
);

// 例 4:
// 翻訳ソースとして 'it' を返し、自動設定を上書きします
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => 'my_it.mo',
        'locale'  => 'auto',
        'scan' => Zend_Translate::LOCALE_FILENAME
    )
);

$translate->addTranslation(array('content' => 'my_ru.mo', 'locale' => 'ru'));
$translate->setLocale('it_IT');

// 起動ファイルで
$locale = new Zend_Locale();
Zend_Registry::set('Zend_Locale', $locale);

// リクエストされた言語が存在しない場合のデフォルト言語
$defaultlanguage = 'en';

// アプリケーションのどこかで
$translate = new Zend_Translate(
    array('adapter' => 'gettext', 'content' => 'my_de.mo')
);

if (!$translate->isAvailable($locale->getLanguage())) {
    // 存在しない言語をリクエストされた場合はデフォルト設定を使用します
    $translate->setLocale($defaultlanguage);
}

$translate->getLocale();

$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => 'my_de.mo',
        'locale'  => 'US'
    )
);

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

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

// 以下のようなディレクトリ構造があることを想定しています
//  /language/
//  /language/login/login.tmx
//  /language/logout/logout.tmx
//  /language/error/loginerror.tmx
//  /language/error/logouterror.tmx

$translate = new Zend_Translate(
    array('adapter' => 'tmx', 'content' => '/language')
);

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

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

// 以下のようなディレクトリ構造があることを想定しています
//  /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(
    array(
        'adapter' => 'gettext',
        'content' => '/language',
        'scan' => Zend_Translate::LOCALE_DIRECTORY
    )
);

// 以下のようなディレクトリ構造があることを想定しています
//  /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(
    array(
        'adapter' => 'gettext',
        'content' => '/language',
        '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

/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 -> イタリア語となります

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

$options   = array('ignore' => 'test');
$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'ignore'  => 'test'
    )
);

$options = array('ignore' => array('.', 'test', 'old'));
$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'ignore'  => array('.', 'test', 'old')
    )
);

$options = array(
    'ignore' => array(
        'regex' => '/test/u',
        'regex_2' => '/deleted$/u'
    )
);
$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'ignore'  => array('regex' => '/test/u', 'regex_2' => '/deleted$/u')
    )
);

Not every message ID can be translated. But sometimes is can be useful to output the translation from another language instead of returning the message ID itself. You can archive this by using the route option.

You can add one route for every language. See the following example:

$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'route'   => array('fr' => 'en', 'de' => 'fr')
    )
);

The above returns a english translation for all messages which can not be translated to french. And it returns a french translation for all messages which can not be translated to german. It will even return an english translation for all messages which can wether be translated to german nor to french. So you can even define a complete translation chain.

This feature seems ot be interesting for anyone. But be aware that returning translations for wrong or other languages can be problematic when the user does not understand this language. So you should always use this feature sparingly.

When you are working with multiple translations you may come into a situation where you want to use different source types. For example the resource files which are provided by the framework and your own translations which are available by using the gettext adapter.

By combining multiple translation adapters you can use them within one instance. See the following example:

$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => '\path\to\translation.mo',
        'locale'  => 'en'
    )
);

$translate_second = new Zend_Translate(
    array(
        'adapter' => 'array',
        'content' => '\resources\languages\en\Zend_Validate.php',
        'locale'  => 'en'
    )
);

$translate->addTranslation(array('content' => $translate_second));

Now the first instance holds all translations from the second instance and you can use it within the application even if you used different source types.

When you are scanning for directories you may additionally want to use only one defined language. The predefined resources for example are available in more than 10 languages. But your application is not available in all of those language. Therefor you can also add only one language from the second adapter.

$translate->addTranslation(
    array(
        'content' => $translate_second,
        'locale'  => 'en'
    )
);

This allows you still to scan through the directories and still add only those languages which are relevant for your application.

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

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

$english = array(
    'message1' => 'Nachricht 1',
    'message2' => 'Nachricht 2',
    'message3' => 'Nachricht 3');

$translate = new Zend_Translate(
    array(
        'adapter' => 'array',
        'content' => $english,
        'locale' => '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 にアタッチします。 次の例を参照ください。

$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => $path,
        'locale' => '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 のような注意メッセージがログに記録されるようになるでしょう。

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

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

$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => $path,
        'locale'  => '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');

Additionally you are also able to change the priority which is used to write the message into the log. Per default the priority Zend_Log::NOTICE is used. It equals with 5. When you want to change the priority you can use any of Zend_Log's priorities. See the following example:

// Create a log instance
$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
$log    = new Zend_Log($writer);

$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => $path,
        'locale'  => 'de',
        'log'             => $log,
        'logMessage'      => "Missing '%message%' within locale '%locale%'",
        'logPriority'     => Zend_Log::ALERT,
        'logUntranslated' => true
    )
);

$translate->translate('unknown string');

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

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

When you want to know the message ID for a given translation then you can use the getMessageId() method.

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

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

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

// すべてのメッセージ ID を返します
$messageIds = $translate->getMessageIds();
print_r($messageIds);

// あるいは指定した言語の ID を返します
$messageIds = $translate->getMessageIds('en_US');
print_r($messageIds);

// すべての翻訳データを返します
$source = $translate->getMessages();
print_r($source);