repo_zf1/documentation/manual/ja/module_specs/Zend_Translate-Additional.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 22725 -->
<sect1 id="zend.translate.additional">

    <title>翻訳用の追加機能</title>

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

    <sect2 id="zend.translate.additional.options">

        <title>アダプタのオプション</title>

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

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

        <example id="zend.translate..additional.options.example">
            <title>翻訳オプションの使用</title>
            <programlisting language="php"><![CDATA[
// ':' を、翻訳ソースファイルの区切り文字として指定します
$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
    )
);
]]></programlisting>
        </example>

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

        <table id="zend.translate.additional.options.alloptions">
            <title>翻訳アダプタのオプション</title>
            <tgroup cols="4">
                <thead>
                    <row>
                        <entry>オプション</entry>
                        <entry>アダプタ</entry>
                        <entry>説明</entry>
                        <entry>デフォルト値</entry>
                    </row>
                </thead>
                <tbody>
                     <row>
                        <entry>adapter</entry>
                        <entry><classname>Zend_Translate</classname> only</entry>

                        <entry>
                            Defines the adapter which will be used for the translation. This option
                            can only be given when a new instance of
                            <classname>Zend_Translate</classname> is created. When it is set
                            afterwards, then it will be ignored
                        </entry>

                        <entry><emphasis>Must be set as it has no default value</emphasis></entry>
                    </row>

                    <row>
                        <entry>clear</entry>
                        <entry>すべて</entry>
                        <entry>
                            <constant>TRUE</constant> にすると、既に読み込んでいる翻訳を消去します。
                            新しい翻訳データを読み込む際に、
                            新しいインスタンスを作成する代わりに使用します。
                        </entry>
                        <entry><emphasis><constant>FALSE</constant></emphasis></entry>
                    </row>

                    <row>
                        <entry>cache</entry>
                        <entry>all</entry>

                        <entry>
                            Sets a cache for the translation adapter. This must be a instance of
                            <classname>Zend_Cache_Core</classname>
                        </entry>

                        <entry>
                            <emphasis>Per default no cache is set</emphasis>
                        </entry>
                    </row>

                    <row>
                        <entry>content</entry>
                        <entry>all</entry>

                        <entry>
                            Sets the content for the translation adapter. This could be an array,
                            a filename or a directory. Which type of content is supported depends
                            on the used adapter
                        </entry>

                        <entry>
                            <emphasis>The default value depends on the used adapter</emphasis>
                        </entry>
                    </row>

                    <row>
                        <entry>disableNotices</entry>
                        <entry>すべて</entry>
                        <entry>
                            <constant>TRUE</constant> に設定すると、翻訳が存在しないことについての注意メッセージを無効にします。
                            実運用環境ではこのオプションを <constant>TRUE</constant> に設定しなければなりません。
                        </entry>
                        <entry><emphasis><constant>FALSE</constant></emphasis></entry>
                    </row>
                    <row>
                        <entry>ignore</entry>
                        <entry>すべて</entry>
                        <entry>
                           このプレフィックスで始まるすべてのディレクトリとファイルが、
                           ファイルを探す際に無視されます。この値のデフォルトは
                           <emphasis>'.'</emphasis>
                           で、すべての隠しファイルを無視するようになります。
                           この値を <emphasis>'tmp'</emphasis> に設定すると、たとえば 'tmpImages' や 'tmpFiles'
                           といった名前のファイルやディレクトリ
                           (とその配下のすべてのディレクトリ) を無視します。
                           <!-- TODO : to be translated -->
                           This option also accepts an array which can be used when
                           you want to ignore more than one prefix.
                        </entry>
                        <entry><emphasis>.</emphasis></entry>
                    </row>
                    <row>
                        <entry>log</entry>
                        <entry>すべて</entry>
                        <entry>
                            未翻訳のメッセージや注意が書き込まれる
                            <classname>Zend_Log</classname> のインスタンス
                        </entry>
                        <entry><emphasis><constant>NULL</constant></emphasis></entry>
                    </row>
                    <row>
                        <entry>logMessage</entry>
                        <entry>すべて</entry>
                        <entry>
                            ログに書き込まれるメッセージ
                        </entry>
                        <entry>
                            <emphasis>Untranslated message within '%locale%': %message%</emphasis>
                        </entry>
                    </row>

                     <row>
                        <entry>logPriority</entry>
                        <entry>all</entry>
                        <entry>The priority which is used to write the message into the log</entry>

                        <entry>
                            <emphasis>5</emphasis>
                        </entry>
                    </row>

                    <row>
                        <entry>logUntranslated</entry>
                        <entry>すべて</entry>
                        <entry>
                            このオプションを <constant>TRUE</constant> に設定すると、翻訳できなかったすべてのメッセージ ID
                            が添付のログに書き込まれます。
                        </entry>
                        <entry><emphasis><constant>FALSE</constant></emphasis></entry>
                    </row>
                    <row>
                        <entry>reload</entry>
                        <entry>すべて</entry>
                        <entry>
                            このオプションを <constant>TRUE</constant> に設定すると、ファイルはキャッシュに再読み込みされます。
                            このオプションはキャッシュの再作成や、
                            キャッシュが既に作成された後で、キャッシュ済みのデータに翻訳を追加するために
                            使えます。
                        </entry>
                        <entry><emphasis><constant>FALSE</constant></emphasis></entry>
                    </row>

                     <row>
                        <entry>route</entry>
                        <entry>all</entry>

                        <entry>
                            This option allows to use reroute from non existing translations to
                            other languages. See the <link
                                linkend="zend.translate.additional.rerouting">Rerouting
                                Section</link> for details about this option.
                        </entry>

                        <entry><emphasis><constant>NULL</constant></emphasis></entry>
                    </row>

                    <row>
                        <entry>scan</entry>
                        <entry>すべて</entry>
                        <entry>
                            <constant>NULL</constant> にすると、ディレクトリ構造のスキャンを行いません。
                            <constant>Zend_Translate::LOCALE_DIRECTORY</constant> にすると、
                            ディレクトリからロケールを検出します。
                            <constant>Zend_Translate::LOCALE_FILENAME</constant> にすると、
                            ファイル名からロケールを検出します。
                            詳細は <link linkend="zend.translate.additional.detection">この章</link>
                            を参照ください。
                        </entry>
                        <entry><emphasis><constant>NULL</constant></emphasis></entry>
                    </row>

                     <row>
                        <entry>tag</entry>
                        <entry>all</entry>

                        <entry>
                            Sets an individual tag which is used for the attached cache. Using this
                            option allows to use and clear the cache for single instances. When this
                            option is not set, the attached cache is used for all instances combined
                        </entry>

                        <entry><emphasis><classname>Zend_Translate</classname></emphasis></entry>
                    </row>

                    <row>
                        <entry>delimiter</entry>
                        <entry>Csv</entry>
                        <entry>
                            ソースと翻訳を区切る際に使用する記号を指定します。
                        </entry>
                        <entry><emphasis>;</emphasis></entry>
                    </row>
                    <row>
                        <entry>enclosure</entry>
                        <entry>Csv</entry>
                        <entry>
                            値を囲むための文字を定義します。デフォルトはダブルクォートです。
                        </entry>
                        <entry><emphasis>"</emphasis></entry>
                    </row>
                    <row>
                        <entry>length</entry>
                        <entry>Csv</entry>
                        <entry>
                            CSV の行の長さの最大値を定義します。0 にすると、自動的に検出します。
                        </entry>
                        <entry><emphasis>0</emphasis></entry>
                    </row>
                    <row>
                        <entry>useId</entry>
                        <entry>Xliff 及び Tmx</entry>
                        <entry>
                            もしこのオプションを <constant>FALSE</constant> に設定すると、
                            ソースの文字列はメッセージ Id として使われます。
                            このオプションの既定値は <constant>TRUE</constant> で、
                            それは, 翻訳単位要素からの Id がメッセージ Id として使われることを意味します。
                        </entry>
                        <entry><emphasis><constant>TRUE</constant></emphasis></entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

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

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

    </sect2>

    <sect2 id="zend.translate.additional.languages">

        <title>言語の処理</title>

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

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

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

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

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

        <example id="zend.translate.additional.languages.example">
            <title>アダプタの言語の処理</title>
            <programlisting language="php"><![CDATA[
// 現在設定されている言語を返します
$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")) {
    // 存在します
}
]]></programlisting>
        </example>

        <sect3 id="zend.translate.additional.languages.automatic">

            <title>言語の自動処理</title>

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

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

            <example id="zend.translate.additional.languages.automatic.example">
                <title>言語の自動検出の動作例</title>
                <programlisting language="php"><![CDATA[
// ブラウザから返される言語設定は次のようなものであると仮定します
// 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');
]]></programlisting>
            </example>

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

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

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

            <programlisting language="php"><![CDATA[
// 起動ファイルで
$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();
]]></programlisting>

        </sect3>

        <sect3 id="zend.translate.additional.languages.territory">
            <title>Using a country as language</title>

            <para>
                You can also use a country as locale parameter. This could be useful when you
                provide your user with flags, which represent the country in which he lives, and
                when he selects his flag, he would automatically get the default language for this
                country.
            </para>

            <para>
                For example, when the user selected <emphasis>US</emphasis> then you would get
                <emphasis>en_US</emphasis> in return as locale which is being used. This leads
                automatically to the language <emphasis>en</emphasis> which is the default language
                for the country <emphasis>US</emphasis>.
            </para>

            <programlisting language="php"><![CDATA[
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => 'my_de.mo',
        'locale'  => 'US'
    )
);
]]></programlisting>

            <note>
                <title>Always uppercase countries</title>

                <para>
                    Using this syntax you should always uppercase the input when you know that it's
                    a country. The reason is that there are also languages which have the same
                    letters as a country. Take for example <emphasis>om</emphasis>. You could expect
                    to get <emphasis>ar_OM</emphasis> when you mean the country "Oman", or you could
                    expect the language "Oromo" which is spoken in Kenia for example.
                </para>

                <para>
                    As <classname>Zend_Translate</classname> is related to languages it will always
                    use the language in this case. Therefor always uppercase the locale when you
                    want it to be recognised as country.
                </para>
            </note>
        </sect3>
    </sect2>

    <sect2 id="zend.translate.additional.detection">

        <title>自動的なソースの検出</title>

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

        <note>
            <para>
                自動的なソース検出機能は、Zend Framework バージョン 1.5
                以降で使用可能です。
            </para>
        </note>

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

        <example id="zend.translate.additional.languages.directory.example">
            <title>ディレクトリを指定してソースを探す</title>
            <programlisting language="php"><![CDATA[
// 以下のようなディレクトリ構造があることを想定しています
//  /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')
);
]]></programlisting>
        </example>

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

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

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

        <sect3 id="zend.translate.additional.detection.directory">

            <title>ディレクトリ名からの言語の取得</title>

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

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

            <example id="zend.translate.additional.detection.directory.example">
                <title>ディレクトリ名による言語の検出</title>
                <programlisting language="php"><![CDATA[
// 以下のようなディレクトリ構造があることを想定しています
//  /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
    )
);
]]></programlisting>
            </example>

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

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

        </sect3>

        <sect3 id="zend.translate.additional.detection.filename">

            <title>ファイル名からの言語の取得</title>

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

            <example id="zend.translate.additional.detection.filename.example">
                <title>ファイル名からの言語の取得</title>
                <programlisting language="php"><![CDATA[
// 以下のようなディレクトリ構造があることを想定しています
//  /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
    )
);
]]></programlisting>
            </example>

            <sect4 id="zend.translate.additional.detection.filename.complete">

                <title>ファイル名全体</title>

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

                <programlisting language="txt"><![CDATA[
/languages/
/languages/en.mo
/languages/de.mo
/languages/es.mo
]]></programlisting>

            </sect4>

            <sect4 id="zend.translate.additional.detection.filename.extension">

                <title>ファイルの拡張子</title>

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

                <programlisting language="txt"><![CDATA[
/languages/
/languages/view.en
/languages/view.de
/languages/view.es
]]></programlisting>

            </sect4>

            <sect4 id="zend.translate.additional.detection.filename.token">

                <title>ファイル名の一部</title>

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

                <programlisting language="txt"><![CDATA[
/languages/
/languages/view_en.mo -> 英語となります
/languages/view_de.mo -> ドイツ語となります
/languages/view_it.mo -> イタリア語となります
]]></programlisting>

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

                <programlisting language="txt"><![CDATA[
/languages/
/languages/view_en_de.mo -> 英語となります
/languages/view_en_es.mo -> 英語となり、最初のファイルを上書きします
/languages/view_it_it.mo -> イタリア語となります
]]></programlisting>

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

                <programlisting language="txt"><![CDATA[
/languages/
/languages/view_en-it.mo -> 英語となります。'_' のほうが '-' より優先されるからです
/languages/view-en_it.mo -> イタリア語となります。'_' のほうが '-' より優先されるからです
/languages/view_en.it.mo -> イタリア語となります。'.' のほうが '_' より優先されるからです
]]></programlisting>

            </sect4>
        </sect3>

        <sect3 id="zend.translate.additional.detection.ignore">
            <title>Ignoring special files and directories</title>

            <para>
                Sometimes it is useful to exclude files or even directories from being added
                automatically. Therefor you can use the <property>ignore</property> option which
                accepts 3 possible usages.
            </para>

            <sect4 id="zend.translate.additional.detection.ignore.string">
                <title>Ignore a special directory or file</title>

                <para>
                    Per default <classname>Zend_Translate</classname> is set to ignore all
                    files and directories beginning with
                    <emphasis>'<filename>/.</filename>'</emphasis>. This means that
                    all <acronym>SVN</acronym> files will be ignored.
                </para>

                <para>
                    You can set your own syntax by giving a string for the
                    <property>ignore</property> option. The directory separator will be attached
                    automatically and has to be omitted.
                </para>

                <programlisting language="php"><![CDATA[
$options   = array('ignore' => 'test');
$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'ignore'  => 'test'
    )
);
]]></programlisting>

                <para>
                    The above example will ignore all files and directories beginning with
                    <emphasis>test</emphasis>. This means for example
                    <filename>/test/en.mo</filename>, <filename>/testing/en.mo</filename> and
                    <filename>/dir/test_en.mo</filename>. But it would still add
                    <filename>/mytest/en.mo</filename> or <filename>/dir/atest.mo</filename>.
                </para>

                <note>
                    <title>Prevent SVN files from being searched</title>

                    <para>
                        When you set this option, then the default
                        <emphasis>'<filename>/.</filename>'</emphasis> will
                        be erased. This means that <classname>Zend_Translate</classname> will then
                        add all files from the hidden <acronym>SVN</acronym> directories. When you
                        are working with <acronym>SVN</acronym>, then you should use the array
                        syntax described in the next section.
                    </para>
                </note>
            </sect4>

            <sect4 id="zend.translate.additional.detection.ignore.array.files">
                <title>Ignore several directories or files</title>

                <para>
                    You can also ignore several files and directories. Instead of a string,
                    you can simply give an array with all wished names which will be ignored.
                </para>

                <programlisting language="php"><![CDATA[
$options = array('ignore' => array('.', 'test', 'old'));
$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'ignore'  => array('.', 'test', 'old')
    )
);
]]></programlisting>

                <para>
                    In the above case all 3 syntax will be ignored. But still they have to
                    begin with the syntax to be detected and ignored.
                </para>
            </sect4>

            <sect4 id="zend.translate.additional.detection.ignore.array.names">
                <title>Ignore specific names</title>

                <para>
                    To ignore files and directories which are not beginning with a defined syntax
                    but have a special syntax anywhere within their name you can use a regular
                    expression.
                </para>

                <para>
                    To use a regular expression the array key of the <property>ignore</property>
                    option has to begin with <emphasis>regex</emphasis>.
                </para>

                <programlisting language="php"><![CDATA[
$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')
    )
);
]]></programlisting>

                <para>
                    In the above case we defined 2 regular expressions. The files and directories
                    will always being searched with all given regular expressions. In our example
                    this means that any files which contains <emphasis>test</emphasis> anywhere in
                    their name will be ignored. Additionally all files and directories which end
                    with <emphasis>deleted</emphasis> will not be added as translation.
                </para>
            </sect4>
        </sect3>
    </sect2>

    <sect2 id="zend.translate.additional.rerouting">
        <title>Routing for translations</title>

        <para>
            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 <property>route</property> option.
        </para>

        <para>
            You can add one route for every language. See the following example:
        </para>

        <programlisting language="php"><![CDATA[
$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'route'   => array('fr' => 'en', 'de' => 'fr')
    )
);
]]></programlisting>

        <para>
            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.
        </para>

        <para>
            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.
        </para>
    </sect2>

    <sect2 id="zend.translate.additional.combination">
        <title>Combining multiple translation sources</title>

        <para>
            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.
        </para>

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

        <programlisting language="php"><![CDATA[
$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));
]]></programlisting>

        <para>
            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.
        </para>

        <note>
            <title>Memory savings</title>

            <para>
                As you may have noted the second instance is no longer used as soon as it has been
                added to the first instance. To save some memory you may want to unset it.
            </para>
        </note>

        <para>
            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.
        </para>

        <programlisting language="php"><![CDATA[
$translate->addTranslation(
    array(
        'content' => $translate_second,
        'locale'  => 'en'
    )
);
]]></programlisting>

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

    <sect2 id="zend.translate.additional.istranslated">

        <title>翻訳の確認</title>

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

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

        <example id="zend.translate.additional.istranslated.example">
            <title>テキストの翻訳が存在するかどうかの確認</title>
            <programlisting language="php"><![CDATA[
$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' を使用できます";
}
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.translate.additional.logging">

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

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

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

        <example id="zend.translate.additional.logging.example">
            <title>翻訳のログ出力</title>
            <programlisting language="php"><![CDATA[
$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');
]]></programlisting>
        </example>

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

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

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

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

        <example id="zend.translate.additional.logging.example2">
            <title>自分で定義したログメッセージ</title>
            <programlisting language="php"><![CDATA[
$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');
]]></programlisting>
        </example>

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

        <example id="zend.translate.additional.logging.example3">
            <title>Self defined log priority</title>

            <programlisting language="php"><![CDATA[
// 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');
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.translate.additional.sourcedata">

        <title>ソースデータへのアクセス</title>

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

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

        <!-- TODO : to be translated -->
        <para>
            When you want to know the message ID for a given translation then you can use the
            <methodname>getMessageId()</methodname> method.
        </para>

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

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

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

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

        <example id="zend.translate.additional.sourcedata.example">
            <title>アダプタでの言語の処理</title>
            <programlisting language="php"><![CDATA[
// すべてのメッセージ ID を返します
$messageIds = $translate->getMessageIds();
print_r($messageIds);

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

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

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->