repo_zf1Php7/documentation/manual/ja/module_specs/Zend_Translate-Using.xml

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

    <title>翻訳アダプタの使用法</title>

    <para>
        次は、アダプタをコード内で使用する方法です。
    </para>

    <example id="zend.translate.using.example1">
        <title>単一言語の PHP コードの例</title>
        <programlisting language="php"><![CDATA[
print "Example\n";
print "=======\n";
print "Here is line one\n";
print "Today is the " . date("d.m.Y") . "\n";
print "\n";
print "Here is line two\n";
]]></programlisting>
    </example>

    <para>
        上の例の出力は、翻訳に対応していません。
        おそらく実際はあなたの母国語でコードを書くでしょう。
        翻訳しなければならないのは、普通は出力内容だけではありません。
        たとえばエラーメッセージやログメッセージなども対象となります。
    </para>

    <para>
        次のステップは、既存のコードに Zend Translate を組み込むことです。
        もちろん、あとからコードを変更するよりも
        最初から翻訳を意識したコードを書くほうがずっと簡単です。
    </para>

    <example id="zend.translate.using.example2">
        <title>多言語対応の PHP コードの例</title>
        <programlisting language="php"><![CDATA[
$translate = new Zend_Translate('gettext', '/my/path/source-de.mo', 'de');
$translate->addTranslation('/path/to/translation/fr-source.mo', 'fr');

print $translate->_("Example") . "\n";
print "=======\n";
print $translate->_("Here is line one") . "\n";
printf($translate->_("Today is the %1\$s") . "\n", date('d.m.Y'));
print "\n";

$translate->setLocale('fr');
print $translate->_("Here is line two") . "\n";
]]></programlisting>
    </example>

    <para>
        では、何が起こっているのか、そしてどうやって
        <classname>Zend_Translate</classname> をコードに組み込むのかについて
        もうすこし詳しく見ていきましょう。
    </para>

    <para>
        新しい <classname>Zend_Translate</classname> オブジェクトを作成し、もととなるアダプタを定義します。

        <programlisting language="php"><![CDATA[
$translate = new Zend_Translate
    'gettext',
    '/path/to/translation/source-de.mo',
    'de'
);
]]></programlisting>

        この例では、
        <emphasis>Gettext アダプタ</emphasis>
        を使うことにしました。
        <emphasis>source-de.mo</emphasis> というファイルを
        <emphasis>/path/to/translation</emphasis> に置いています。
        この gettext ファイルにはドイツ語の翻訳が含まれています。
        また、その後で別途フランス語のファイルも追加しています。
    </para>

    <para>
        次に行うのは、翻訳対象の文字列をすべてラップすることです。
        一番シンプルな手法は、このように文字列や文章を囲むことです。

        <programlisting language="php"><![CDATA[
print $translate->_("Example") . "\n";
print "=======\n";
print $translate->_("Here is line one") . "\n";
]]></programlisting>

        中には翻訳する必要のない文字列もあるでしょう。
        区切り線などは、たとえ言語が何であっても同じです。
    </para>

    <para>
        データの値を翻訳文字列に組み込むこともできます。
        この場合は埋め込みパラメータを使用します。

        <programlisting language="php"><![CDATA[
printf($translate->_("Today is the %1\$s") . "\n", date("d.m.Y"));
]]></programlisting>

        <code>print()</code> の代わりに <code>printf()</code> 関数を使用し、
        すべてのパラメータを <code>%1\$s</code> のように置き換えます。
        最初のパラメータが <code>%1\$s</code>、その次が <code>%2\$s</code>、
        といったようになります。
        これにより、実際の値を知らなくても翻訳を進めることができます。
        今回の例では、日付は常に今日の日付になります。
        しかし、文字列を翻訳する際には、実際の日付が何であるかを知る必要はありません。
    </para>

    <para>
        各文字列は、メッセージ ID によって識別します。
        文字列の代わりに、コード内でメッセージ ID を指定することもできます。
        その場合は、このようになります。

        <programlisting language="php"><![CDATA[
print $translate->_(1) . "\n";
print "=======\n";
print $translate->_(2) . "\n";
]]></programlisting>

        しかし、この方法にはいくつか欠点があります。
    </para>

    <para>
        コードを見ただけでは、そこでどんな内容が出力されるのかがわかりません。
    </para>

    <para>
        また、文字列の一部が翻訳されていない場合にも問題が起こるでしょう。
        翻訳の動作原理について考えてみましょう。
        まず <classname>Zend_Translate</classname> は、指定した ID あるいは文字列に対応する翻訳が
        その言語に存在するかどうかを探します。
        翻訳文字列が見つからない場合は、<classname>Zend_Locale</classname>
        で定義されているその次の言語の翻訳を探します。
        つまり "<emphasis>de_AT</emphasis>" の場合は
        "<emphasis>de</emphasis>" のみで探します。
        "<emphasis>de</emphasis>" の翻訳も見つからない場合は、
        もとのメッセージをそのまま返します。
        このようにして、たとえ翻訳文字列がなくても何らかの出力を得ることになっています。
        <classname>Zend_Translate</classname> は、文字列の翻訳の際に
        エラーや例外を発生させることはありません。
    </para>

    <sect2 id="zend.translate.using.structure">

        <title>翻訳ソースの構造</title>

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

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

        <itemizedlist>
            <listitem>
                <para>
                    単一構造のソース
                </para>

                <programlisting><![CDATA[
/application/
/languages/
/languages/lang.en
/languages/lang.de
/library/
]]></programlisting>

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

                <programlisting><![CDATA[
/application/
/languages/
/languages/en/
/languages/en/first.en
/languages/en/second.en
/languages/de/
/languages/de/first.de
/languages/de/second.de
/library
]]></programlisting>

                <para>
                    利点: すべての言語がひとつのディレクトリにまとめられます。
                    各言語のチームは、ひとつのディレクトリを翻訳するだけですみます。
                    また、複数のファイルを透過的に使用できます。
                </para>
            </listitem>
            <listitem>
                <para>
                    アプリケーションごとに分けた構造
                </para>

                <programlisting><![CDATA[
/application/
/application/languages/
/application/languages/first.en
/application/languages/first.de
/application/languages/second.en
/application/languages/second.de
/library/
]]></programlisting>

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

                <para>
                    欠点: 同じ言語で複数のファイルを使用する場合に問題が発生します。
                </para>
            </listitem>
            <listitem>
                <para>
                    Gettext 形式の構造
                </para>

                <programlisting><![CDATA[
/application/
/languages/
/languages/de/
/languages/de/LC_MESSAGES/
/languages/de/LC_MESSAGES/first.mo
/languages/de/LC_MESSAGES/second.mo
/languages/en/
/languages/en/LC_MESSAGES/
/languages/en/LC_MESSAGES/first.mo
/languages/en/LC_MESSAGES/second.mo
/library/
]]></programlisting>

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

                <para>
                    欠点: これまでに gettext を使ったことがない人たちにとって、
                    サブディレクトリの中にまたサブディレクトリという構造は不可解でしょう。
                </para>
            </listitem>
            <listitem>
                <para>
                   ファイル構造のソース
                </para>

                <programlisting><![CDATA[
/application/
/application/models/
/application/models/MyModel.php
/application/models/MyModel.de
/application/models/MyModel.en
/application/controllers/
/application/controllers/MyController.php
/application/controllers/MyController.de
/application/controllers/MyController.en
/library/
]]></programlisting>
                <para>
                    利点: すべてのファイルについて、翻訳ソースを関連付けられます。
                </para>

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

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

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

    </sect2>

    <sect2 id="zend.translate.using.source.array">

        <title>Array ソースファイルの作成</title>

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

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

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

        <programlisting language="php"><![CDATA[
// myarray.php
return array(
    'message1' => 'Nachricht1',
    'message2' => 'Nachricht2',
    'message3' => 'Nachricht3');

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

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

        </note>

    </sect2>

    <sect2 id="zend.translate.using.source.gettext">

        <title>Gettext ソースファイルの作成</title>

        <para>
            Gettext ソースファイルは、GNU の gettext ライブラリで作成します。
            あなたのコードをパースして gettext ソースファイルを作成してくれるツールが、
            フリーで公開されています。このファイルは、拡張子が
            <emphasis>*.mo</emphasis> のバイナリファイルとなります。
            ファイルを作成するためのフリーソフトウェアのひとつに
            <ulink url="http://sourceforge.net/projects/poedit/">poEdit</ulink>
            があります。これは、ファイルの作成だけでなく翻訳作業自体もサポートしています。
        </para>

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

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

        <note>
            <para>
                 ソースのエンコーディングには常に UTF-8
                 を使用しなければなりません。そうしないと、
                 複数のソースエンコーディングを使用することで問題が発生します。
                 たとえば、あるソースファイルは ISO-8815-11 でエンコードされており、
                 他のファイルは CP815 でエンコードされているとしましょう。
                 ソースファイルのエンコーディングはひとつしか指定できないので、
                 どちらか一方は正しく表示されなくなります。
            </para>
            <para>
                 UTF-8 は可搬性の高いフォーマットで、全言語をサポートしています。
                 すべての言語で UTF-8 を使用することで、
                 エンコーディングの非互換性による問題をなくすことができます。
            </para>
        </note>

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

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

    </sect2>

    <sect2 id="zend.translate.using.source.tmx">

        <title>TMX ソースファイルの作成</title>

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

        <example id="zend.translate.using.source.tmx.example">
            <title>TMX ファイルの例</title>
            <programlisting language="xml"><![CDATA[
<?xml version="1.0" ?>
<!DOCTYPE tmx SYSTEM "tmx14.dtd">
<tmx version="1.4">
 <header creationtoolversion="1.0.0" datatype="winres" segtype="sentence"
         adminlang="en-us" srclang="de-at" o-tmf="abc"
         creationtool="XYZTool" >
 </header>
 <body>
  <tu tuid='message1'>
   <tuv xml:lang="de"><seg>Nachricht1</seg></tuv>
   <tuv xml:lang="en"><seg>message1</seg></tuv>
  </tu>
  <tu tuid='message2'>
   <tuv xml:lang="en"><seg>message2</seg></tuv>
   <tuv xml:lang="de"><seg>Nachricht2</seg></tuv>
  </tu>
]]></programlisting>

            <programlisting language="php"><![CDATA[
$translate = new Zend_Translate('tmx', 'path/to/mytranslation.tmx', 'en');
]]></programlisting>
        </example>

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

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

    <sect2 id="zend.translate.using.source.csv">

        <title>CSV ソースファイルの作成</title>

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

        <example id="zend.translate.using.source.csv.example">
            <title>CSV ファイルの例</title>
            <programlisting><![CDATA[
# csv ファイルの例
message1;Nachricht1
message2;Nachricht2
]]></programlisting>

            <programlisting language="php"><![CDATA[
$translate = new Zend_Translate('csv', '/path/to/mytranslation.csv', 'de');
$translate->addTranslation('path/to/other.csv', 'fr');
]]></programlisting>
        </example>

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

        <para>
            CSV 文字列の標準の区切り文字は '<code>;</code>' 記号です
            <footnote>
                <para>
                    訳注: カンマ以外で区切ったら、もはや CSV でも何でもないのですが、
                    そのあたりはあまり気にしない方向で :-)
                </para>
            </footnote>。
            が、オプション '<code>delimiter</code>' を使用すると、
            別の区切り文字を使用することができます。
        </para>

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

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

        <example id="zend.translate.using.source.csv.example2">
            <title>CSV ファイルの例 その 2</title>
            <programlisting><![CDATA[
# csv ファイルの例
"message,1",Nachricht1
message2,"Nachricht,2"
"message3,",Nachricht3
]]></programlisting>

            <programlisting language="php"><![CDATA[
$translate = new Zend_Translate(
    'csv',
    '/path/to/mytranslation.csv',
    'de',
    array('delimiter' => ','));

$translate->addTranslation('/path/to/other.csv', 'fr');
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.translate.using.source.ini">

        <title>INI ソースファイルの作成</title>

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

        <example id="zend.translate.using.source.ini.example">
            <title>INI ファイルの例</title>
            <programlisting><![CDATA[
[Test]
;TestPage Comment
Message_1="Nachricht 1 (de)"
Message_2="Nachricht 2 (de)"
Message_3="Nachricht :3 (de)"
]]></programlisting>

            <programlisting language="php"><![CDATA[
$translate = new Zend_Translate('ini', '/path/to/mytranslation.ini', 'de');
$translate->addTranslation('/path/to/other.ini', 'it');
]]></programlisting>
        </example>

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

    </sect2>

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

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

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

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

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

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

        <table id="zend.translate.using.options.alloptions">
            <title>翻訳アダプタのオプション</title>
            <tgroup cols="4">
                <thead>
                    <row>
                        <entry>オプション</entry>
                        <entry>アダプタ</entry>
                        <entry>説明</entry>
                        <entry>デフォルト値</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>clear</entry>
                        <entry>すべて</entry>
                        <entry>
                            true にすると、既に読み込んでいる翻訳を消去します。
                            新しい翻訳データを読み込む際に、
                            新しいインスタンスを作成する代わりに使用します。
                        </entry>
                        <entry><emphasis>false</emphasis></entry>
                    </row>
                    <row>
                        <entry>disableNotices</entry>
                        <entry>すべて</entry>
                        <entry>
                            true に設定すると、翻訳が存在しないことについての注意メッセージを無効にします。
                            実運用環境ではこのオプションを true に設定しなければなりません。
                        </entry>
                        <entry><emphasis>false</emphasis></entry>
                    </row>
                    <row>
                        <entry>ignore</entry>
                        <entry>すべて</entry>
                        <entry>
                           このプレフィックスで始まるすべてのディレクトリとファイルが、
                           ファイルを探す際に無視されます。この値のデフォルトは
                           <emphasis>'.'</emphasis>
                           で、すべての隠しファイルを無視するようになります。
                           この値を 'tmp' に設定すると、たとえば 'tmpImages' や 'tmpFiles'
                           といった名前のファイルやディレクトリ
                           (とその配下のすべてのディレクトリ) を無視します。
                        </entry>
                        <entry><emphasis>.</emphasis></entry>
                    </row>
                    <row>
                        <entry>log</entry>
                        <entry>すべて</entry>
                        <entry>
                            未翻訳のメッセージや注意が書き込まれる
                            <classname>Zend_Log</classname> のインスタンス
                        </entry>
                        <entry><emphasis>null</emphasis></entry>
                    </row>
                    <row>
                        <entry>logMessage</entry>
                        <entry>all</entry>
                        <entry>
                            ログに書き込まれるメッセージ
                        </entry>
                        <entry><emphasis>Untranslated message within '%locale%': %message%</emphasis></entry>
                    </row>
                    <row>
                        <entry>logUntranslated</entry>
                        <entry>すべて</entry>
                        <entry>
                            このオプションを true に設定すると、翻訳できなかったすべてのメッセージ ID
                            が添付のログに書き込まれます。
                        </entry>
                        <entry><emphasis>false</emphasis></entry>
                    </row>
                    <row>
                        <entry>scan</entry>
                        <entry>すべて</entry>
                        <entry>
                            null にすると、ディレクトリ構造のスキャンを行いません。
                            <classname>Zend_Translate::LOCALE_DIRECTORY</classname> にすると、
                            ディレクトリからロケールを検出します。
                            <classname>Zend_Translate::LOCALE_FILENAME</classname> にすると、
                            ファイル名からロケールを検出します。
                            詳細は <xref linkend="zend.translate.using.detection" />
                            を参照ください。
                        </entry>
                        <entry><emphasis>null</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>
                </tbody>
            </tgroup>
        </table>

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

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

    </sect2>

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

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

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

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

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

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

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

        <example id="zend.translate.using.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.using.languages.automatic">

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

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

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

            <example id="zend.translate.using.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(
    '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');
]]></programlisting>
            </example>

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

            <para>
                自動検出を再度有効にしたい場合は、<code>setLocale()</code>
                で言語として <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('gettext', '\my_de.mo');
if (!$translate->isAvailable($locale->getLanguage())) {
    // 存在しない言語をリクエストされた場合はデフォルト設定を使用します
    $translate->setLocale($defaultlanguage);
}

$translate->getLocale();
]]></programlisting>

        </sect3>

    </sect2>

    <sect2 id="zend.translate.using.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.using.languages.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('tmx', '/language');
]]></programlisting>
        </example>

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

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

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

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

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

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

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

            <example id="zend.translate.using.detection.directory.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(
    'gettext',
    '/language',
    null,
    array('scan' => Zend_Translate::LOCALE_DIRECTORY));
]]></programlisting>
            </example>

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

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

        </sect3>

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

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

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

            <example id="zend.translate.using.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(
    'gettext',
    '/language',
    null,
    array('scan' => Zend_Translate::LOCALE_FILENAME));
]]></programlisting>
            </example>

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

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

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

                <programlisting><![CDATA[
/languages/
/languages/en.mo
/languages/de.mo
/languages/es.mo
]]></programlisting>

            </sect4>

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

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

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

                <programlisting><![CDATA[
/languages/
/languages/view.en
/languages/view.de
/languages/view.es
]]></programlisting>

            </sect4>

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

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

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

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

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

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

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

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

            </sect4>

        </sect3>

    </sect2>

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

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

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

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

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

    </sect2>

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

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

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

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

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

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

    </sect2>

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

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

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

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

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

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

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

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

        <example id="zend.translate.using.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:
-->