Zend Framework 1.7.9 Manual

次に行うのは、翻訳したい言語用の翻訳ソースを作成することです。 それぞれのアダプタには個別の方法があるので、それをここで説明します。 その前に、すべてのアダプタに共通する一般的な事項について説明しておきます。

どこに翻訳ソースファイルを保存すべきなのかを知っておきましょう。 Zend_Translate では特に制限はありませんが、 以下のような構造を推奨します。

• 単一構造のソース

  /application
  /languages
    lang.en
    lang.de
  /library

  利点: すべての言語のソースファイルを同じディレクトリに配置できます。 関連するファイルを分割する必要がありません。

• 言語ごとに分けた構造

  /application
  /languages
    /en
      lang.en
      other.en
    /de
      lang.de
      other.de
  /library

  利点: すべての言語がひとつのディレクトリにまとめられます。 各言語のチームは、ひとつのディレクトリを翻訳するだけですみます。 また、複数のファイルを透過的に使用できます。

• アプリケーションごとに分けた構造

  /application
    /languages
      lang.en
      lang.de
      other.en
      other.de

  利点: すべての言語のソースファイルを同じディレクトリに配置できます。 関連するファイルを分割する必要がありません。

  欠点: 同じ言語で複数のファイルを使用する場合に問題が発生します。

• Gettext 形式の構造

  /languages
    /de
      /LC_MESSAGES
        lang.mo
        other.mo
    /en
      /LC_MESSAGES
        lang.mo
        other.mo

  利点: 以前から使っている gettext 形式のソースを、 そのままの形式で使用できます。

  欠点: これまでに gettext を使ったことがない人たちにとって、 サブディレクトリの中にまたサブディレクトリという構造は不可解でしょう。

• ファイル構造のソース

  /application
    /models
      mymodel.php
      mymodel.de
      mymodel.en
    /views
    /controllers
      mycontroller.de
  /document_root
    /images
    /styles
    .htaccess
    index.php
    index.de
  /library
    /Zend

  利点: すべてのファイルについて、翻訳ソースを関連付けられます。

  欠点: 小さな翻訳ファイルがあちこちに散らばってしまうので、翻訳が面倒です。 また、すべてのファイルに対して翻訳ソースを追加する必要があります。

Zend_Translate で最も便利なのは、単一構造か 言語ごとに分けた構造でしょう。

さあ、これでどんな構造でいくかが決まりました。 次に翻訳ソースファイルを作っていきましょう。

Array ソースファイルは、単なる配列です。 しかし、専用のツールはないので自分でそれを定義しなければなりません。 とは言え、この配列は非常にシンプルです。 コードが期待通りに動作しているかを確認するのにも最も手っ取り早いでしょう。 翻訳作業を始めるにあたっては、一般的に最適なアダプタであるといえます。

$english = array('message1' => 'message1',
                 'message2' => 'message2',
                 'message3' => 'message3');
$german = array('message1' => 'Nachricht1',
                'message2' => 'Nachricht2',
                'message3' => 'Nachricht3');

$translate = new Zend_Translate('array', $english, 'en');
$translate->addTranslation($deutsch, 'de');

リリース 1.5 以降では、配列を外部のファイルに含めることもサポートしています。 ファイル名を指定すると、Zend_Translate が自動的にそれをインクルードして配列を探します。 詳細は、次の例を参照ください。

// myarray.php
return array(
    'message1' => 'Nachricht1',
    'message2' => 'Nachricht2',
    'message3' => 'Nachricht3');

// コントローラ
$translate = new Zend_Translate('array', 'path/to/myarray.php', 'de');

Note:

配列を返さないファイルはインクルードできません。 また、このファイル内での出力はすべて無視されます。

Gettext ソースファイルは、GNU の gettext ライブラリで作成します。 あなたのコードをパースして gettext ソースファイルを作成してくれるツールが、 フリーで公開されています。このファイルは、 *.mo のような名前のバイナリファイルとなります。 ファイルを作成するためのフリーソフトウェアのひとつに » poEdit があります。これは、ファイルの作成だけでなく翻訳作業自体もサポートしています。

// mo ファイルを作成し、翻訳を済ませているものとします
$translate = new Zend_Translate('gettext', 'path/to/english.mo', 'en');
$translate->addTranslation('path/to/german.mo', 'de');

ご覧の通り、アダプタの使用法はまったく同じです。 違っているのはたったの一点だけ。 'array' が 'gettext' になっているということです。 その他の部分は、どのアダプタを使用してもまったく同じになります。 gettext アダプタを使用する際には、 gettext の標準的なディレクトリ構造や bindtextdomain、 textdomain にこだわる必要はありません。 単にパスとファイル名をアダプタに渡せばいいのです。

Note:

ソースのエンコーディングには常に UTF-8 を使用しなければなりません。そうしないと、 複数のソースエンコーディングを使用することで問題が発生します。 たとえば、あるソースファイルは ISO-8815-11 でエンコードされており、 他のファイルは CP815 でエンコードされているとしましょう。 ソースファイルのエンコーディングはひとつしか指定できないので、 どちらか一方は正しく表示されなくなります。

UTF-8 は可搬性の高いフォーマットで、全言語をサポートしています。 すべての言語で UTF-8 を使用することで、 エンコーディングの非互換性による問題をなくすことができます。

gettext エディタの多くは、 空の翻訳文字列という形式で追加情報を記録します。 そのため、gettext アダプタは空の文字列の翻訳を行いません。 これらの情報は翻訳テーブルからは削除され、かわりに getAdapterInfo() メソッドで取得できるようになります。 このメソッドは、追加された gettext ファイルすべてから取得した情報を配列で返します。 ファイル名を配列のキーとして使用します。

// アダプタの情報を取得する方法
$translate = new Zend_Translate('gettext', 'path/to/english.mo', 'en');
print_r $translate->getAdapterInfo();

TMX ソースファイルは、新しい業界標準です。 XML ファイルを使用しているので、どんなエディタでも読み込め、 かつ人間にも読める形式であるという利点があります。 TMX ファイルはテキストエディタで作成することもできますし、 ツールを用いて作成することもできます。しかし、 現在使用できる TMX ソースファイル作成ツールの多くは フリーソフトウェアではありません。

 

 
 
  
   Nachricht1
   message1
  
  
   message2
   Nachricht2
  

$translate = new Zend_Translate('tmx', 'path/to/mytranslation.tmx', 'en');
// TMX では、複数の言語をひとつの TMX ファイルに含めることができます

TMX ファイルには、同一ファイルに複数の言語を含めることができます。 含まれている言語はすべて自動的に追加されるので、 addLanguage() をコールする必要はありません。

ソース中の特定の言語のみを翻訳対象としたい場合は、オプション defined_language を true に設定します。このオプションを指定した場合は、 対象としたい言語を addLanguage() で明示的に指定します。このオプションのデフォルト設定は、 全言語を対象とするようになっています。

CSV ソースファイルは、サイズが小さく可読性があります。 顧客が自分で翻訳をしたいということなら、 おそらく CSV アダプタを使用することになるでしょう。

# csv ファイルの例
message1;Nachricht1
message2;Nachricht2

$translate = new Zend_Translate('csv', 'path/to/mytranslation.csv', 'de');
$translate->addTranslation('path/to/other.csv', 'fr');

CSV アダプタで使用できるオプションは、 'delimiter' と 'limit' そして 'enclosure' の 3 つです。

CSV 文字列の標準の区切り文字は ';' 記号です ^[1] 。 しかし、必ずこれでなければならないというわけではありません。 オプション 'delimiter' を使用すると、 別の区切り文字を使用することができます。

CSV ファイルのデフォルトの行長制限は '0' です。 この場合は、CSV ファイルの行末を自動的に検出します。 'limit' オプションに何らかの値を設定すると CSV ファイルの読み込みが高速になりますが、 その長さを超えた部分は切り捨てられます。

CSV ファイルの値を囲む文字のデフォルトは '"' です。 別の文字を使用する場合は 'enclosure' オプションを設定します。

# csv ファイルの例
# 元メッセージは 'message,1'
"message,1",Nachricht1
# 翻訳は 'Nachricht,2'
message2,"Nachricht,2"
# 元メッセージは 'message3,'
"message3,",Nachricht3

$translate = new Zend_Translate('csv',
                                'path/to/mytranslation.csv',
                                'de',
                                array('delimiter' => ','));
$translate->addTranslation('path/to/other.csv', 'fr');

INI ソースファイルは可読性がありますが、 翻訳以外のデータを含めるとサイズはそれほど小さくなりません。 直接顧客に変更させるようなデータの場合にも INI アダプタが使えるでしょう。

[Test]
;TestPage Comment
Message_1="Nachricht 1 (de)"
Message_2="Nachricht 2 (de)"
Message_3="Nachricht :3 (de)"

$translate = new Zend_Translate('ini', 'path/to/mytranslation.ini', 'de');
$translate->addTranslation('path/to/other.ini', 'it');

INI にはいくつかの制約があります。 INI ファイルの値に非英数字が含まれる場合は、値をダブルクォート (") で囲まなければなりません。また、ini ファイルのキーとしては使えない予約語があります。 予約語には null, yes, no, true, そして false があります。 値に null, no および false を指定するとそれは "" と同じ扱いとなり、yes と true を指定するとそれは "1" と同じ扱いとなります。 {}|&~![()" といった文字はキーの中では使えず、 また値の中で使用すると特別な意味を持つことになります。 予期せぬ挙動を起こすようなら、このアダプタを使わないようにしましょう。

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

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

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

...

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

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

自分でオプションを定義すれば、それをすべてのアダプタで使用することができます。 オプションを定義するには 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");

...
// この言語が存在するかどうかを調べます
if ($translate->isAvailable("fr")) {
    // 存在します
}

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

// 例 1:
$translate = new Zend_Translate("gettext", "\my_it.mo", "it_IT");
$translate->addTranslation("\my_es.mo","es_UG");
// 適切な言語がみつからないので、メッセージ ID を返します

// 例 2:
$translate = new Zend_Translate("gettext", "\my_en.mo", "en_US");
$translate->addTranslation("\my_it.mo","it_IT");
// 適切な言語は "en_US" となります

// 例 3:
$translate = new Zend_Translate("gettext", "\my_it.mo", "it_IT");
$translate->addTranslation("\my_de.mo","de");
// 適切な言語は "de" となります。"de_AT" の代替言語は "de" だからです

// 例 4:
$translate = new Zend_Translate("gettext", "\my_it.mo", "it_IT");
$translate->addTranslation("\my_ru.mo","ru");
$translate->setLocale("it_IT");
$translate->addTranslation("\my_de.mo","de");
// 翻訳ソースとして "it_IT" を返します

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

// アプリケーションのどこかで
$translate = new Zend_Translate("gettext", "\my_de.mo");
$translate->getLocale();

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

Note:

自動的なソース検出機能は、Zend Framework バージョン 1.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('tmx', '/language');

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

Note:

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

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

// 以下のようなディレクトリ構造があることを想定しています
//  /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_DIRECTORY));

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

$translate = new Zend_Translate('gettext', '/language', null, array('scan' => Zend_Translate::LOCALE_FILENAME));

/languages
  en.mo
  de.mo
  es.mo

/languages
  view.en
  view.de
  view.es

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

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

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

通常は、テキストが翻訳されているかどうかを気にすることはありません。 しかし、そのテキストが翻訳されているかどうかを、ソースコードから調べたいこともあるでしょう。 そんな場合に使用するメソッドが 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', $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' を使用できます";
}

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

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

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

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

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

Note:

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

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

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

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