repo_zf1Php7/documentation/manual/de/module_specs/Zend_Translate-SourceCreation.xml

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

    <title>Erstellen von Quelldateien</title>

    <para>
        Anbei ist eine Beschreibung der unterschiedlichen Quellformate welche mit
        <classname>Zend_Translate</classname> verwendet werden können.
    </para>

    <note>
        <para>
            Es ist zu beachten das die meisten der beschriebenen Formate durch Verwendung eines
            Tools oder eines Erstellungs Prozesses erstellt werden sollten. Diese Tools und
            Prozesse sind nicht Teil vom Zend Framework und für die meisten der beschriebenen
            Formate gibt es kostenlose Tools.
        </para>
    </note>

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

        <title>Erstellung von Array Quelldateien</title>

        <para>
            Array Quelldateien sind reine Arrays. Sie müssen aber manuell definiert werden, da
            es hierfür keine Tools gibt die helfen könnten. Weil Sie so einfach zu handhaben sind,
            ist Ihre Verwendung auch der schnellste Weg um zu testen ob Nachrichten innerhalb des
            Codes wie erwartet arbeiten. Er ist generell der beste Adapter um mit Mehrsprachigkeit
            zu beginnen wenn man keine diesbezüglichen Kenntnisse hat.
        </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>
            Seit Release 1.5 wird es auch unterstützt, Arrays die in externen Dateien vorhanden
            sind einzubauen. Es ist der Dateiname anzugeben und
            <classname>Zend_Translate</classname> wird diesen automatisch inkludieren und nach dem
            Array schauen. Siehe das folgende Beispiel für Details:
        </para>

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

// controller
$translate = new Zend_Translate('array', '/path/to/myarray.php', 'de');
]]></programlisting>

        <note>
            <para>
                Bei Dateien die kein Array zurückgeben wird das inkludieren fehlschlagen. Auch
                jegliche Ausgabe innerhalb dieser Dateien wird ignoriert und unterdrückt.
            </para>
        </note>
    </sect2>

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

        <title>Erstellung von Gettext Quellen</title>

        <para>
            Gettext Quellen werden durch GNU's Gettext Bibliothek erstellt. Es gibt einige
            kostenlose Tools welche den Code parsen können und hierbei die gewünschten Gettext
            Quellen erstellen. Diese haben die Endung <emphasis>*.mo</emphasis> und
            sind binäre Dateien. Ein Open Source Tool für die Erstellung der Quellen ist
            <ulink url="http://sourceforge.net/projects/poedit/">poEdit</ulink>. Dieses Tool
            unterstützt auch beim Übersetzungs-Prozesses selbst.
        </para>

        <programlisting language="php"><![CDATA[
// Wir nehmen an das die mo Datien erstellt und übersetzt wurden
$translate = new Zend_Translate('gettext', '/path/to/english.mo', 'en');
$translate->addTranslation('/path/to/german.mo', 'de');
]]></programlisting>

        <para>
            Wie man sieht wird dieser Adapter auf exakt die gleiche Art und Weise verwendet mit
            einer kleinen Änderung: dem Wechsel von <emphasis>array</emphasis> zu
            <emphasis>gettext</emphasis>. Alle anderen Punkte werden in jedem anderen
            Adapter auf exakt die gleiche Weise verwendet. Mit diesem Gettext Adapter muß nicht
            mehr auf die geforderte Standard Verzeichnis Struktur von Gettext geachtet werden. Auch
            nicht auf bindtextdomain und textdomain. Nur der Pfad und der Dateiname muß dem Adapter
            übergeben werden.
        </para>

        <note>
            <para>
                 Man sollte immer UTF-8 als Quell Encoding verwenden. Man könnte sonst Probleme
                 bekommen wenn man zwei verschiedene Encodings verwendet. Wenn z.B. eine Quelldatei
                 mit ISO-8815-11 und eine andere mit CP815 encoded ist. Man kann
                 immer nur ein Encoding für alle Quell Dateien verwenden, und hierbei würde eine der
                 gewünschten Sprachen nicht korrekt angezeigt werden.
            </para>
            <para>
                 UTF-8 ist ein portables Format welches alle Sprachen unterstützt. Wenn UTF-8 für
                 alle Sprachen verwendet wird, eliminiert man die Probleme mit inkompatiblen
                 Encodings.
            </para>
        </note>

        <para>
            Viele Gettext Editoren fügen Informationen über den Adapter als Übersetzung eines
            leeren Strings hinzu. Das ist der Grund warum leere Strings nicht übersetzt werden wenn
            der Gettext Adapter verwendet wird. Stattdessen wird er von der Übersetzungstabelle
            gelöscht und von der <methodname>getAdapterInfo()</methodname> Methode angeboten. Sie
            gibt die Adapterinformationen für alle hinzugefügten Gettextdateien als Array zurück
            wobei der Dateiname als Schlüssel verwendet wird.
        </para>

        <programlisting language="php"><![CDATA[
// Informationen des Adapters bekommen
$translate = new Zend_Translate('gettext', '/path/to/english.mo', 'en');
print_r($translate->getAdapterInfo());
]]></programlisting>

    </sect2>

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

        <title>Erstellung von TMX Quellen</title>

        <para>
            TMX Quellen sind der neue Industrie Standard. Sie haben den Vorteil das sie
            <acronym>XML</acronym> Dateien sind und deswegen mit jedem Texteditor lesbar und
            natürlich auch von Menschen. Man kann TMX Dateien entweder per Hand erstellen oder man
            verwendet spezielle Tools dafür. Allerdings sind die meisten erhältlichen Tools die
            Erstellung von TMX Quellen nicht frei erhältlich.
        </para>

        <example id="zend.translate.sourcecreation.tmx.example">
            <title>Beispiel einer TMX Datei</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 Dateien können mehrere Sprachen in der selben Datei enthalten. Alle anderen in der
            Quelle enthaltenen Sprachen werden automatisch hinzugefügt und müssen nicht durch einen
            extra Aufruf von <methodname>addLanguage()</methodname> ergänzt werden.
        </para>

        <para>
            Wenn man nur spezielle Sprache aus der Quelle übersetzen will, kann die Option
            '<code>defined_language</code>' auf <constant>TRUE</constant> gesetzt werden. Mit dieser
            Option können gewünschte Sprachen explizit mit <methodname>addLanguage()</methodname>
            hinzugefügt werden. Der Standardwert für diese Option fügt alle Sprachen hinzu.
        </para>
    </sect2>

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

        <title>Erstellung von CSV Quellen</title>

        <para>
            CSV Quellen sind sehr klein und von Menschen lesbar. Wenn ein Kunde selbst übersetzen
            will, ist die Verwendung des CSV Adapters warscheinlich die beste Wahl.
        </para>

        <example id="zend.translate.sourcecreation.csv.example">
            <title>Beispiel CSV Datei</title>
            <programlisting language="txt"><![CDATA[
#Example csv file
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>
            Es gibt drei verschiedene Optionen für den CSV Adapter. Es können
            '<code>delimiter</code>', '<code>limit</code>' und '<code>enclosure</code>' gesetzt
            werden.
        </para>

        <para>
            Das Standard Trennzeichen für CSV Strings ist '<code>;</code>, aber es muß nicht dieses
            Zeichen sein. Mit der Option '<code>delimiter</code>' kann ein anderes verwendet
            werden.
        </para>

        <para>
            Das Standardlimit für eine Zeile in einer CSV Datei ist '<code>0</code>'. Das bedeutet
            dass das Ende der CSV Zeile automatisch gesucht wird. Wenn '<code>limit</code>' auf
            irgendeinen Wert gesetzt wird, dann wird die CSV Datei schneller gelesen, aber jede
            Zeile die dieses Limit überschreitet wird abgeschnitten.
        </para>

        <para>
            Das standardmäßige Anführungszeichen für die Verwendung mit CSV Dateien ist
            '<code>"</code>'. Man kann ein anderes Setzen indem die Option '<code>enclosure</code>'
            verwendet wird.
        </para>

        <example id="zend.translate.sourcecreation.csv.example2">
            <title>Zweites Beispiel für CSV Dateien</title>
            <programlisting language="txt"><![CDATA[
# Example CSV file
"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>

        <note>

            <para>
                Wenn nicht-ASCII Zeichen in der CSV Datei verwendet werden, wie z.B. Umlaute oder
                UTF-8 Zeichen, dann sollte man immer Hochkommas verwenden. Das Weglassen der
                Hochkommas kann zu fehlenden Zeichen in der Übersetzung führen.
            </para>

        </note>

    </sect2>

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

        <title>Erstellung von INI Quelldateien</title>

        <para>
            <acronym>INI</acronym> Quelldateien sind menschlich lesbar aber normalerweise nicht sehr
            klein da Sie neben der Übersetzung auch andere Daten enthalten. Wenn Sie Daten haben die
            von Ihrem Kunden zu bearbeitet sind, verwenden Sie den <acronym>INI</acronym> Adapter.
        </para>

        <example id="zend.translate.sourcecreation.ini.example">
            <title>Beispiel einer INI Datei</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('ini', '/path/to/mytranslation.ini', 'de');
$translate->addTranslation('/path/to/other.ini', 'it');
]]></programlisting>
        </example>

        <para>
            <acronym>INI</acronym> Dateien haben diverse Einschränkungen. Wenn ein Wert in einer INI
            Datei irgendein nicht alphanummerisches Zeichen enthält, muß er in doppelte
            Anführungszeichen (<code>"</code>) eingeklammert werden. Es gibt auch reservierte Wörter
            welche nicht als Schlüssel für <acronym>INI</acronym> Dateien verwendet werden dürfen.
            Diese enthalten: <constant>NULL</constant>, <code>yes</code>, <code>no</code>,
            <constant>TRUE</constant> und <constant>FALSE</constant>. Die Werte
            <constant>NULL</constant>, <code>no</code> und <constant>FALSE</constant> führen zu
            <code>""</code>, <code>yes</code> und <constant>TRUE</constant> resultieren in
            <code>1</code>. Die Zeichen <code>{}|&amp;~![()"</code> dürfen nirgendwo im Schlüssel
            verwendet werden und haben im Wert eine spezielle Bedeutung. Diese sollten nicht
            verwendet werden da Sie zu unerwartetem Verhalten führen.
        </para>

    </sect2>

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