# Erstellen von Quelldateien

Anbei ist eine Beschreibung der unterschiedlichen Quellformate, welche mit Zend_Translate verwendet werden können.

Es ist zu beachten, dass die meisten der beschriebenen Formate durch Verwendung eines Tools oder eines Erzeugungsprozesses erstellt werden sollten. Diese Tools und Prozesse sind nicht Teil von Zend Framework und für die meisten der beschriebenen Formate sind kostenlose Tools verfügbar.

## Erstellung von Array-Quelldateien

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.

    $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'));

Seit Release 1.5 wird auch das Einbinden von externen Dateien unterstützt, welche Arrays beinhalten. Es ist der Dateiname anzugeben und Zend_Translate wird diesen automatisch inkludieren und den Array suchen. Siehe das folgende Beispiel für Details:

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

    // controller
    $translate = new Zend_Translate(
        array(
            'adapter' => 'array',
            'content' => '/path/to/myarray.php',
            'locale'  => 'de'
        )
    );

Bei Dateien, die kein Array zurückgeben, wird das inkludieren fehlschlagen. Auch jegliche Ausgabe innerhalb dieser Dateien wird ignoriert und unterdrückt.

## Erstellung von Gettext Quellen

Gettext-Quellen werden von der GNU 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 *.mo und sind binäre Dateien. Ein Open Source Tool für die Erstellung der Quellen ist poEdit. Dieses Tool unterstützt auch beim Übersetzungsprozess selbst.

    // Wir nehmen an das die mo Datien erstellt und übersetzt wurden
    $translate = new Zend_Translate(
        array(
            'adapter' => 'gettext',
            'content' => '/path/to/english.mo',
            'locale'  => 'en'
        )
    );
    $translate->addTranslation(
        array(
            'content' => '/path/to/german.mo',
            'locale'  => 'de'
        )
    );

Offensichtlich wird dieser Adapter bis auf einen kleinen Unterschied auf exakt die gleiche Art und Weise verwendet: array wird geändert zu gettext. Alle anderen Punkte werden in jedem anderen Adapter auf exakt die gleiche Weise verwendet. Mit diesem Gettext-Adapter muss nicht mehr auf die Standardverzeichnisstruktur von Gettext oder die Verwendung von bindtextdomain und textdomain geachtet werden. Nur der Pfad und der Dateiname muss dem Adapter übergeben werden.

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 Quelldateien verwenden und hierbei würde eine der gewünschten Sprachen nicht korrekt angezeigt werden.

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.

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 getAdapterInfo() Methode angeboten. Sie gibt die Adapterinformationen für alle hinzugefügten Gettextdateien als Array zurück, wobei der Dateiname als Schlüssel verwendet wird.

    // Informationen des Adapters bekommen
    $translate = new Zend_Translate(
        array(
            'adapter' => 'gettext',
            'content' => '/path/to/english.mo',
            'locale'  => 'en'
        )
    );
    print_r($translate->getAdapterInfo());

## Erstellung von TMX Quellen

TMX-Quellen sind der neue Industriestandard. Sie haben den Vorteil, dass sie XML 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 Tools für die Erstellung von TMX Quellen nicht frei erhältlich.

Beispiel einer TMX Datei

    <?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>

    $translate = new Zend_Translate(
        array(
            'adapter' => 'tmx',
            'content' => 'path/to/mytranslation.tmx',
            'locale'  => 'en'
        )
    );

TMX-Dateien können mehrere Sprachen in derselben Datei enthalten. Alle anderen in der Quelle enthaltenen Sprachen werden automatisch hinzugefügt und müssen nicht durch einen extra Aufruf von addLanguage() ergänzt werden.

Wenn man nur spezielle Sprachen aus der Quelle übersetzen will, kann die Option defined_language auf `TRUE` gesetzt werden. Mit dieser Option können gewünschte Sprachen explizit mit addLanguage() hinzugefügt werden. Der Standardwert für diese Option fügt alle Sprachen hinzu.

Option useId

Wenn man die Option useId auf `FALSE` setzt, dann wird der srclang-Header verwendet, um die Sprache zu definieren, welche die Meldung setzt.

In unserem Beispiel würde der Schlüssel der Meldung standardmäßig message1 sein. Wenn diese Option auf `FALSE` gesetzt wird, dann würde der Schlüssel Nachricht1 verwendet werden.

Es ist zu beachten, dass der Eintrag tuv, welcher dem Eintrag srclang entspricht, der erste tuv Eintrag sein muss, welcher gesetzt wird, wie im obigen Beispiel zu sehen ist.

## Erstellung von CSV-Quellen

CSV-Quellen sind sehr klein und von Menschen lesbar. Wenn ein Kunde selbst übersetzen will, ist die Verwendung des CSV-Adapters wahrscheinlich die beste Wahl.

Beispiel CSV Datei

    ﻿#Example csv file
    message1;Nachricht1
    message2;Nachricht2

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

Es gibt drei verschiedene Optionen für den CSV-Adapter. Es können delimiter, limit und enclosure gesetzt werden.

Das Standardtrennzeichen für CSV-Strings ist ';', aber es muss nicht dieses Zeichen sein. Mit der Option delimiter kann ein anderes verwendet werden.

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

Das standardmäßige Anführungszeichen für die Verwendung mit CSV-Dateien ist '"'. Man kann ein anderes setzen, indem die Option enclosure verwendet wird.

Zweites Beispiel für CSV-Dateien

    ﻿# Example CSV file
    "message,1",Nachricht1
    message2,"Nachricht,2"
    "message3,",Nachricht3

    $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'
        )
    );

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.

## Erstellung von INI-Quelldateien

INI-Quelldateien sind menschenlesbar, 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 INI-Adapter.

Beispiel einer INI-Datei

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

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

INI-Dateien haben verschiedene Einschränkungen. Wenn ein Wert in einer INI-Datei irgendein nicht alphanumerisches Zeichen enthält, muss er in doppelte Anführungszeichen (") eingeschlossen werden. Es gibt auch reservierte Wörter, welche nicht als Schlüssel für INI-Dateien verwendet werden dürfen. Diese enthalten: `NULL`, yes, no, `TRUE` und `FALSE`. Die Werte `NULL`, no und `FALSE` führen zu "", yes und `TRUE` resultieren in '1'. Die Zeichen {}|&~![()" 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.