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

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

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

    <para>
        <classname>Zend_Translate</classname> で使用できる
        さまざまなソース形式についての説明を以下で行います。
    </para>

    <note>
        <para>
            大半のフォーマットは、何らかのツールを用いて生成しなければならないことに注意しましょう。
            そのツールについては Zend Framework には含まれていません。
            ほとんどのフォーマットについてはフリーの生成ツールが存在します。
        </para>
    </note>

    <sect2 id="zend.translate.sourcecreation.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(
        'adapter' => 'array',
        'content' => $english,
        'locale'  => 'en'
    )
);
$translate->addTranslation(array('content' => $german, 'locale' => '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(
        'adapter' => 'array',
        'content' => '/path/to/myarray.php',
        'locale'  => 'de'
    )
);
]]></programlisting>

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

        </note>

    </sect2>

    <sect2 id="zend.translate.sourcecreation.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(
    array(
        'adapter' => 'gettext',
        'content' => '/path/to/english.mo',
        'locale'  => 'en'
    )
);
$translate->addTranslation(
    array(
        'content' => '/path/to/german.mo',
        'locale' => '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 アダプタは空の文字列の翻訳を行いません。
            これらの情報は翻訳テーブルからは削除され、かわりに
            <methodname>getAdapterInfo()</methodname> メソッドで取得できるようになります。
            このメソッドは、追加された gettext
            ファイルすべてから取得した情報を配列で返します。
            ファイル名を配列のキーとして使用します。
        </para>

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

    </sect2>

    <sect2 id="zend.translate.sourcecreation.tmx">

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

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

        <example id="zend.translate.sourcecreation.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="de"><seg>Nachricht2</seg></tuv>
           <tuv xml:lang="en"><seg>message2</seg></tuv>
       </tu>
   </body>
</tmx>
]]></programlisting>

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

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

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

        <!-- TODO : to be translated -->
        <note>
            <title>Option useId</title>

            <para>
                When you set the <emphasis>useId</emphasis> option to <constant>FALSE</constant>
                then the <emphasis>srclang</emphasis> header will be used to define the language
                which sets the message.
            </para>

            <para>
                In our example the message key would <emphasis>message1</emphasis> per default.
                When this option is set to <constant>FALSE</constant> the message key
                <emphasis>Nachricht1</emphasis> would be used.
            </para>

            <para>
                Note that the <emphasis>tuv</emphasis> entry which is related to the
                <emphasis>srclang</emphasis> entry must be the first
                <emphasis>tuv</emphasis> entry which is set like shown in the above example.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.translate.sourcecreation.csv">

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

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

        <example id="zend.translate.sourcecreation.csv.example">
            <title>CSV ファイルの例</title>

            <programlisting language="txt"><![CDATA[
# csv ファイルの例
message1;Nachricht1
message2;Nachricht2
]]></programlisting>

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

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

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

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

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

        <example id="zend.translate.sourcecreation.csv.example2">
            <title>CSV ファイルの例 その 2</title>

            <programlisting language="txt"><![CDATA[
# csv ファイルの例
"message,1",Nachricht1
message2,"Nachricht,2"
"message3,",Nachricht3
]]></programlisting>

            <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/other.csv',
        'locale' => 'fr'
    )
);
]]></programlisting>
        </example>

        <note>

            <para>
                CSV ファイルで非 ASCII 文字 (ウムラウトや UTF-8 文字など) を使用する場合は、
                値を囲んでおく必要があります。値を囲むのを省略すると、
                翻訳で文字が失われてしまったりする可能性があります。
            </para>

        </note>

    </sect2>

    <sect2 id="zend.translate.sourcecreation.ini">

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

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

        <example id="zend.translate.sourcecreation.ini.example">
            <title>INI ファイルの例</title>

            <programlisting language="txt"><![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(
    array(
        'adapter' => 'ini',
        'content' => '/path/to/mytranslation.ini',
        'locale'  => 'de'
    )
);
$translate->addTranslation(
    array(
        'content' => '/path/to/other.ini',
        'locale' => 'it'
    )
);
]]></programlisting>
        </example>

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

    </sect2>

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