repo_zf1/documentation/manual/de/module_specs/Zend_Translate-Using.xml

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

    <title>Benutzen von Übersetzungs Adaptoren</title>

    <para>
        Der nächste Schritt ist die Benutzung des Adapters im eigenen Code.
    </para>

    <example id="zend.translate.using.example1">
        <title>Beispiel eines einsprachigen PHP Codes</title>
        <programlisting role="php"><![CDATA[
print "Beispiel\n";
print "========\n";
print "Hier steht Zeile eins\n";
print "Heute ist der " . date("d.m.Y") . "\n";
print "\n";
print "Hier ist Zeile zwei\n";
]]></programlisting>
    </example>

    <para>
        Das obige Beispiel zeigt eine Ausgabe ohne Unterstützung für Übersetzungen. Der Code wird
        üblicherweise in der eigenen Muttersprache geschrieben. Üblicherweise muß nicht nur die
        Ausgabe übersetzt werden, sondern auch Fehler- und Logmeldungen.
    </para>

    <para>
        Der nächste Schritt ist also die Integration von Zend_Translate in den eigenen Code.
        Natürlich ist das viel einfacher wenn der Code bereits so geschrieben wird das er
        übersetzbar ist, anstatt Ihn im Nachhinein dafür zu ändern.
    </para>

    <example id="zend.translate.using.example2">
        <title>Beispiel für mehrsprachigen PHP Code</title>
        <programlisting role="php"><![CDATA[
$translate = new Zend_Translate(
    'gettext',
    '/path/to/translation/source-de.mo',
    'de'
);
$translate->addTranslation('//my/path/fr-source.mo', 'fr');

print $translate->_("Beispiel") . "\n";
print "========\n";
print $translate->_("Hier steht Zeile eins") . "\n";
printf($translate->_("Heute ist der %1\$s") . "\n", date('d.m.Y'));
print "\n";

$translate->setLocale('fr');
print $translate->_("Hier ist Zeile zwei") . "\n";
]]></programlisting>
    </example>

    <para>
        Jetzt schauen wir uns genauer an, was getan wurde, und wie <classname>Zend_Translate</classname> in
        den eigenen Code integriert wird.
    </para>

    <para>
        Erstelle ein neues <classname>Zend_Translate</classname> Objekt und definiere den Basis Adapter:

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

        In diesem Beispiel haben wir den <emphasis role="strong">Gettext Adapter</emphasis>
        ausgewählt. Die Übersetzungsdatei <emphasis role="strong">source-de.mo</emphasis> wird im
        Verzeichnis <emphasis role="strong">/path/to/translation</emphasis> platziert. Diese
        Gettext Datei beinhaltet eine deutsche Übersetzung und es steht auch eine zweite
        Sprachquelle für Französisch zur Verfügung.
    </para>

    <para>
        Der nächste Schritt besteht darin alle Strings zu ummanteln die übersetzt werden sollen.
        Die einfachste Möglichkeit besteht wenn nur einfache Strings oder Sätze vorhanden sind
        wie zum Beispiel:

        <programlisting role="php"><![CDATA[
print $translate->_("Beispiel") . "\n";
print "========\n";
print $translate->_("Hier ist die Zeile Eins") . "\n";
]]></programlisting>

        Einige Strings müssen nicht übersetzt werden. Die Trennlinie wird immer eine Trennlinie sein,
        auch in den anderen Sprachen.
    </para>

    <para>
        Variable Werte in eine Übersetzung zu integrieren wird aber auch unterstützt durch die
        Verwendung von eingebetteten Parametern.

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

        Statt <code>print()</code> wird die <code>printf()</code> Funktion benutzt
        und alle variablen Parameter mit <code>%1\$s</code> Blöcken ersetzt.
        Der erste ist <code>%1\$s</code>, der zweite ist <code>%2\$s</code>, und so weiter.
        Auf diesen Weg kann übersetzt werden ohne den exakten Wert zu wissen. In unserem
        Beispiel ist das Datum immer der aktuelle Tag, aber der String kann übersetzt
        werden ohne über den aktuellen Tag bescheid zu wissen.
    </para>

    <para>
        Jeder String wird im Übersetzungsspeicher identifiziert durch seine Message ID.
        Man könnte diese Message IDs statt des Strings im Code wie folgt verwenden:

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

        Allerdings hat dies mehrere grobe Nachteile:
    </para>

    <para>
        Es ist nicht erkennbar was der Code ausgeben sollte indem man ihn betrachtet.
    </para>

    <para>
        Es werden auch Probleme auftreten wenn einige Strings nicht übersetzt worden sind. Man muß
        sich immer vor Augen halten wie Übersetzungen funktionieren. Zuerst prüft
        <classname>Zend_Translate</classname> ob in der gesetzten Sprache, für die angegebene Message ID oder
        den String, eine Übersetzung vorhanden ist. Wenn kein Übersetzung gefunden wurde, wird in
        der nächsten tiefer gelegenen Sprache gesucht wie in <classname>Zend_Locale</classname> definiert.
        "<emphasis role="strong">de_AT</emphasis>" wird also zu
        "<emphasis role="strong">de</emphasis>". Wenn auch hier keine Übersetzung in der Sprache
        "<emphasis role="strong">de</emphasis>" gefunden wurde, wird der Original String zurück
        gegeben. Das bedeutet also das immer eine Ausgabe existiert, selbst wenn für eine Message
        ID keine Übersetzung in der Quelle vorhanden ist. <classname>Zend_Translate</classname> wird niemals
        eine Exception oder einen Fehler ausgeben wenn ein String übersetzt werden soll.
    </para>

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

        <title>Strukturen für Übersetzungdateien</title>

        <para>
            Der nächste Schritt besteht in der Erstellung der Übersetzungsdateien für die
            verschiedenen Sprachen welche übersetzt werden sollen. Jeder Adapter wird auf seine
            eigene Weise, wie hier beschrieben, erstellt aber es gibt ein paar generelle Features
            die für alle Adapter relevant sind.
        </para>

        <para>
            Zuerst muß entschieden werden wo die Übersetzung Dateien zu speichern sind. Bei der
            Verwendung von <classname>Zend_Translate</classname> gibt es keinerlei Einschränkungen. Aber die
            folgenden Strukturen bevorzugt verwendet werden:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Einzeln strukturierte Quellen
                </para>

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

                <para>
                    Positiv: Alle Quell Dateien, für jede Sprache, werden in einem einzelnen
                    Verzeichnis gespeichert. Keine Aufteilung der betreffenden Dateien.
                </para>
            </listitem>
            <listitem>
                <para>
                    Sprachlich stukturierte Quellen
                </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>
                    Positiv: Jede Sprache wird in Ihrem eigenen Verzeichnis gespeichert. Einfache
                    Übersetzung, da jedes Übersetzungsteam nur ein einzelnes Verzeichnis zu
                    übersetzen hat. Und die Verwendung Verwendung von mehreren Dateien genauso
                    transparent.
                </para>
            </listitem>
            <listitem>
                <para>
                    Applikations strukturierte Quellen
                </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>
                    Positiv: Alle Quelldateien, für jede Sprache, werden in einem einzelnen
                    Verzeichnis gespeichert. Keine Aufteilung der betreffenden Dateien.
                </para>

                <para>
                    Negativ: Die Benutzung von mehreren Datein für die selbe Sprache kann
                    problematisch sein.
                </para>
            </listitem>
            <listitem>
                <para>
                    Gettext strukturierte Quellen
                </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>
                    Positiv: Bestehende Gettext Quellen können, ohne Veränderung der Struktur,
                    benutzt werden.
                </para>

                <para>
                    Negativ: Die Benutzung von Sub-Sub Verzeichnissen ist für Personen, die Gettext
                    noch nie benutzt haben, verwirrend.
                </para>
            </listitem>
            <listitem>
                <para>
                    Datei strukturierte Quellen
                </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>
                    Positiv: Übersetzungsdateien sind in der Nähr Ihrer Quelle zu finden.
                </para>

                <para>
                    Negativ: Zu viele und auch kleine Übersetzungsdateien führen zu einer
                    schwierigen und langwierigen Übersetzung. Es muß auch jede Datei als
                    Übersetzungsquelle hinzugefügt werden.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Einzeln strukturierte und sprachlich strukturierte Quell Dateien sind
            für <classname>Zend_Translate</classname> am besten benutzbar.
        </para>

        <para>
            Also jetzt, da bekannt ist welche Struktur verwendet wird,
            müssen die einzelnen Übersetzungs Dateien erstellt werden.
        </para>

    </sect2>

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

        <title>Erstellung von Array Quelldateien</title>

        <para>
            Array Quelldateien sind einfache Arrays. Sie müssen aber per Hand 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 role="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 einbauen und nach dem Array schauen. Siehe das folgende Beispiel
            für Details:
        </para>

        <programlisting role="php"><![CDATA[
// myarray.php
<?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.using.source.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 role="strong">*.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 role="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 role="strong">array</emphasis> zu
            <emphasis role="strong">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 <code>getAdapterInfo()</code> 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 role="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.using.source.tmx">

        <title>Erstellung von TMX Quellen</title>

        <para>
            TMX Quellen sind der neue Industrie Standard. Sie haben den Vorteil das 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 erhältlichen Tools die Erstellung von TMX Quellen nicht
            frei erhältlich.
        </para>

        <example id="zend.translate.using.source.tmx.example">
            <title>Beispiel einer TMX Datei</title>
            <programlisting role="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 role="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 <code>addLanguage()</code> ergänzt werden.
        </para>

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

    <sect2 id="zend.translate.using.source.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.using.source.csv.example">
            <title>Beispiel CSV Datei</title>
            <programlisting><![CDATA[
#Example csv file
message1;Nachricht1
message2;Nachricht2
]]></programlisting>

            <programlisting role="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.using.source.csv.example2">
            <title>Zweites Beispiel für CSV Dateien</title>
            <programlisting><![CDATA[
# Example CSV file
"message,1",Nachricht1
message2,"Nachricht,2"
"message3,",Nachricht3
]]></programlisting>

            <programlisting role="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>Erstellung von INI Quelldateien</title>

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

        <example id="zend.translate.using.source.ini.example">
            <title>Beispiel einer INI Datei</title>
            <programlisting><![CDATA[
[Test]
;TestPage Comment
Message_1="Nachricht 1 (de)"
Message_2="Nachricht 2 (de)"
Message_3="Nachricht :3 (de)"
]]></programlisting>

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

        <para>
            INI 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 INI Dateien verwendet werden dürfen. Diese enthalten: <code>null</code>,
            <code>yes</code>, <code>no</code>, <code>true</code> und <code>false</code>. Die Werte
            <code>null</code>, <code>no</code> und <code>false</code> führen zu <code>""</code>,
            <code>yes</code> und <code>true</code> 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>

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

        <title>Optionen für Adapter</title>

        <para>
            Optionen können bei allen Adaptoren verwendet werden. Natürlich sind die Optionen für
            alle Adaptoren verschieden. Die Optionen können bei Erstellung des Objekts miterstellt
            werden. Zur Zeit gibt es nur eine Option die für alle Adaptoren verfügbar ist:
            '<code>clear</code>' setzt, ob die neuen Übersetzungsdaten zu den bestehenden
            hinzugefügt werden sollen oder ob Sie diese überschreiben. Das Standardverhalten ist
            das Hinzufügen von neuen Übersetzungsdaten zu den Bestehenden. Aber das wird immer nur
            für die aktuelle Sprache gemacht. Anderen Sprachen bleiben davon unberührt.
        </para>

        <para>
            Man kann Optionen temporär setzen indem man die Funktion
            <code>addTranslation($data, $locale, array $options = array())</code> als dritten und
            optionalen Parameter benutzt. Ausserdem kann die Methode <code>setOptions()</code>
            benutzt werden um Optionen permanent zu setzen.
        </para>

        <example id="zend.translate.using.options.example">
            <title>Benutzen von Übersetzungsoptionen</title>
            <programlisting role="php"><![CDATA[
// Definiere ':' als Trenner für die Quelldatei der Übersetzung
$options = array('delimiter' => ':');
$translate = new Zend_Translate(
    'csv',
    '/path/to/mytranslation.csv',
    'de',
    $options);

...

// Lösche die definierte Sprache und verwende die neuen Übersetzungsdaten
$options = array('clear' => true);
$translate->addTranslation('/path/to/new.csv', 'fr', $options);
]]></programlisting>
        </example>

        <para>
            Hier können alle vorhandenen Optionen für die verschiedenen Adapter gefunden werden mit einer
            Beschreibung Ihrer Verwendung:
        </para>

        <table id="zend.translate.using.options.alloptions">
            <title>Optionen für Übersetzungs-Adapter</title>
            <tgroup cols="4">
                <thead>
                    <row>
                        <entry>Option</entry>
                        <entry>Adapter</entry>
                        <entry>Beschreibung</entry>
                        <entry>Standardwert</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>clear</entry>
                        <entry>all</entry>
                        <entry>
                            Wenn true gesetzt wird, werden bereits gelesene Übersetzungen entfernt.
                            Das kann statt dem Erstellen einer neuen Instanz verwendet werden wenn
                            neue Übersetzungsdaten gelesen werden
                        </entry>
                        <entry><emphasis role="strong">false</emphasis></entry>
                    </row>
                    <row>
                        <entry>disableNotices</entry>
                        <entry>all</entry>
                        <entry>
                            Wenn es auf true gesetzt wird, werden alle Notizen betreffend nicht
                            vorhandenen Übersetzungen ausgeschaltet. Man sollte diese Option in
                            einer Produktionsumgebung auf true setzen
                        </entry>
                        <entry><emphasis role="strong">false</emphasis></entry>
                    </row>
                    <row>
                        <entry>ignore</entry>
                        <entry>all</entry>
                        <entry>
                            Alle Verzeichnisse und Dateien die mit diesem Präfix beginnen werden
                            bei der Suche nach Dateien ignoriert. Der Standardwert ist
                            <emphasis role="strong">'.'</emphasis> was zu dem Verhalten führt das
                            alle versteckten Dateien ignoriert werden. Wenn dieser Wert auf
                            <code>'tmp'</code> gesetzt wird, bedeutet das, Verzeichnisse und
                            Dateien wie z.B. <code>'tmpImages'</code> und <code>'tmpFiles'</code>,
                            sowie alle darunter liegenden Verzeichnisse, werden ignoriert.
                        </entry>
                        <entry><emphasis role="strong">.</emphasis></entry>
                    </row>
                    <row>
                        <entry>log</entry>
                        <entry>all</entry>
                        <entry>
                            Eine Instanz von <classname>Zend_Log</classname> wohin nicht übersetzbare Meldungen und
                            Notizen geschrieben werden
                        </entry>
                        <entry><emphasis role="strong">null</emphasis></entry>
                    </row>
                    <row>
                        <entry>logMessage</entry>
                        <entry>all</entry>
                        <entry>
                            Die Nachricht die in das Log geschrieben werden soll
                        </entry>
                        <entry><emphasis role="strong">Untranslated message within '%locale%': %message%</emphasis></entry>
                    </row>
                    <row>
                        <entry>logUntranslated</entry>
                        <entry>all</entry>
                        <entry>
                            Wenn diese Option auf true gesetzt wird, werden alle Nachrichten Id's
                            die nicht übersetzt werden können in das angehängte Log geschrieben
                        </entry>
                        <entry><emphasis role="strong">false</emphasis></entry>
                    </row>
                    <row>
                        <entry>scan</entry>
                        <entry>all</entry>
                        <entry>
                            Wenn null gesetzt wird, wird die Verzechnisstruktur nicht gescannt.
                            Wenn <classname>Zend_Translate::LOCALE_DIRECTORY</classname> gesetzt wird, wird
                            das Gebietsschema im Verzeichnis gesucht. Wenn
                            <classname>Zend_Translate::LOCALE_FILENAME</classname> gesetzt wird, wird das
                            Gebietsschema im Dateinamen gesucht. Siehe
                            <xref linkend="zend.translate.using.detection" /> für Details
                        </entry>
                        <entry><emphasis role="strong">null</emphasis></entry>
                    </row>
                    <row>
                        <entry>delimiter</entry>
                        <entry>Csv</entry>
                        <entry>Definiert welches Zeichen als Trenner für Quelle und Übersetzung verwendet wird</entry>
                        <entry><emphasis role="strong">;</emphasis></entry>
                    </row>
                    <row>
                        <entry>length</entry>
                        <entry>Csv</entry>
                        <entry>Definiert die maximale Länge einer CSV Zeile. Auf 0 gesetzt wird sie automatisch erkannt</entry>
                        <entry><emphasis role="strong">0</emphasis></entry>
                    </row>
                    <row>
                        <entry>enclosure</entry>
                        <entry>Csv</entry>
                        <entry>Definiert das zu verwendende Einschließungszeichen. Standard ist das doppelte Hochkomma</entry>
                        <entry><emphasis role="strong">"</emphasis></entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Wenn man selbstdefinierte Optionen haben will, können diese auch in allen Adaptern
            verwendet werden. Die <code>setOptions()</code> Methode kann verwendet werden um die
            eigene Option zu definieren. <code>setOptions()</code> benötigt ein Array mit den
            Optionen die gesetzt werden sollen. Wenn eine angegebene Option bereits existiert wird
            diese überschrieben. Es können beliebig viele Optionen definiert werden da diese nicht
            vom Adapter geprüft werden. Man muß nur Sicherstellen das keine existierende Option
            überschrieben werden die von einem Adapter verwendet wird.
        </para>

        <para>
            Um die Option zurückzugeben kann die Methode <code>getOptions()</code> verwendet
            werden. Wenn <code>getOptions()</code> ohne einen Parameter aufgerufen wird, gibt Sie
            alle Optionen zurück. Wenn der optionale Parameter angegeben wird, wird nur die
            spezifizierte Option zurückgegeben.
        </para>

    </sect2>

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

        <title>Mit Sprachen arbeiten</title>

        <para>
            Wenn mit verschiedenen Sprachen gearbeitet wird gibt es ein paar Methoden die nützlich
            sind.
        </para>

        <para>
            Die <code>getLocale()</code> Methode kann verwendet werden um die aktuell gesetzte
            Sprache zu erhalten. Sie kann entweder eine Instanz von <classname>Zend_Locale</classname> oder
            den Bezeichner des Gebietsschemas enthalten.
        </para>

        <para>
            Die <code>setLocale()</code> Methode setzt eine neue Standardsprache für Übersetzungen.
            Das verhindert das der optionale Sprachparameter der <code>translate()</code> Methode
            mehr als einmal gesetzt werden muß. Wenn die angegebene Sprache nicht existiert, oder
            keine Übersetzten Daten für diese Sprache vorhanden sind, versucht
            <code>setLocale()</code> auf die Sprache ohne Region downzugraden wenn diese angegeben
            wurde. Die Sprache <code>en_US</code> würde zum Beispiel zu  <code>en</code>
            downgegradet werden. Wenn sogar nach dem Downgraden die Sprache nicht gefunden werden
            konnte, wird eine Ausnahme geworfen.
        </para>

        <para>
            Die <code>isAvailable()</code> Methode prüft ob eine angegebene Sprache bereits
            vorhanden ist. Es wird <code>true</code> zurückgegeben wenn Daten für die angegebene
            Sprache existieren.
        </para>

        <para>
            Und letztendlich kann die <code>getList()</code> Methode verwendet werden um alle
            aktuell gesetzten Sprachen für einen Adapter als Array zu erhalten.
        </para>

        <example id="zend.translate.using.languages.example">
            <title>Handhabung von Sprachen mit Adaptern</title>
            <programlisting role="php"><![CDATA[
// gibt die aktuell gesetzte Sprache zurück
$actual = $translate->getLocale();

// der optionale Parameter kann wärend der Übersetzung verwendet werden
echo $translate->_("mein_Text", "fr");
// oder setze eine neue Standardsprache
$translate->setLocale("fr");
echo $translate->_("mein_Text");
// zur Basissprache referieren
// fr_CH wird zu fr downgegradet
$translate->setLocale("fr_CH");
echo $translate->_("mein_Text");

// Prüft ob die Sprache existiert
if ($translate->isAvailable("fr")) {
    // Sprache existiert
}
]]></programlisting>
        </example>

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

            <title>Automatische Handhabung von Sprachen</title>

            <para>
                Es gilt zu beachten das, solange man neue Sprachquellen mit der
                <code>addTranslation()</code> Methode hinzufügt, <classname>Zend_Translate</classname>
                automatisch die am besten passende Sprache für die eigene Umgebung auswählt wenn
                man eine der automatischen Gebietsschemata verwendet die '<code>auto</code>' oder
                '<code>browser</code>' sein können. Man muß normalerweise also
                <code>setLocale()</code> nicht aufrufen. Das sollte nur in Verbindung mit der
                automatischen Erkennung von Quellen verwendet werden.
            </para>

            <para>
                Der Algorithmus sucht nach dem am besten passenden Gebietsschema abhängig vom
                Browser des Benutzers und der eigenen Umgebung. Siehe das folgende Beispiel für
                Details:
            </para>

            <example id="zend.translate.using.languages.automatic.example">
                <title>Automatische Erkennen der Sprache</title>
                <programlisting role="php"><![CDATA[
// Angenommen der Browser gibt folgende Spracheneinstellungen zurück:
// HTTP_ACCEPT_LANGUAGE = "de_AT=1;fr=1;en_US=0.8";

// Beispiel 1:
// Wenn keine passende Sprache gefunden wird, wird die MessageID zurückgegeben
$translate = new Zend_Translate(
    'gettext',
    '\my_it.mo',
    'auto',
    array('scan' => Zend_Translate::LOCALE_FILENAME));

// Beispiel 2:
// Die am besten passende Sprache ist 'fr'
$translate = new Zend_Translate(
    'gettext',
    '\my_fr.mo',
    'auto',
    array('scan' => Zend_Translate::LOCALE_FILENAME));

// Beispiel 3:
// Die am besten passende Sprache ist 'de' ('de_AT' wird degradiert)
$translate = new Zend_Translate(
    'gettext',
    '\my_de.mo',
    'auto',
    array('scan' => Zend_Translate::LOCALE_FILENAME));

// Beispiel 4:
// Gibt 'it' als Übersetzungsquelle zurück und überschreibt
// die automatischen Eigenschaften
$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>
                Nachdem eine Sprache per Hand mit der <code>setLocale()</code> Methode gesetzt
                wurde, wird die automatische Erkennung ausgeschaltet und übergangen.
            </para>

            <para>
                Wenn man Sie wieder verwenden will, kann die Sprache
                <emphasis role="strong">auto</emphasis> mit <code>setLocale()</code> gesetzt
                werden, was die automatische Erkennung für <classname>Zend_Translate</classname> wieder
                reaktiviert.
            </para>

            <para>
                Seit dem Zend Framework 1.7.0 unterstützt <classname>Zend_Translate</classname> auch die
                Verwendung eines Anwendungsweiten Gebietsschemas. Man kann einfach eine
                <classname>Zend_Locale</classname> Instanz in der Registry setzen wie unten gezeigt. Mit
                dieser Schreibweise kann man das manuelle Setzen eines Gebietsschemas mit jeder
                Instanz komplett vergessen wenn man das gleiche Gebietsschema mehrere Male
                verwenden will.
            </para>

            <programlisting role="php"><![CDATA[
// In der Bootstrap Datei
$locale = new Zend_Locale();
Zend_Registry::set('Zend_Locale', $locale);

// Standardsprache wenn die angefragte Sprache nicht vorhanden ist
$defaultlanguage = 'en';

// Irgendwo in der Anwendung
$translate = new Zend_Translate('gettext', 'my_de.mo');

if (!$translate->isAvailable($locale->getLanguage())) {
    // Nicht vorhandene Sprache werden auf eine andere Sprache geroutet
    $translate->setLocale($defaultlanguage);
}

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

        </sect3>

    </sect2>

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

        <title>Automatische Erkennung von Quellen</title>

        <para>
            <classname>Zend_Translate</classname> kann Übersetzungsquellen automatisch erkennen. Es muß also
            nicht jede Quelldatei manuell deklariert werden. Man kann diesen Job
            <classname>Zend_Translate</classname> überlassen welches die komplette Verzeichnisstruktur nach
            Quelldateien durchsucht.
        </para>

        <note>
            <para>
                Automatische Erkennung der Quellen ist seit Zend Framework Version 1.5 vorhanden.
            </para>
        </note>

        <para>
            Die Verwendung ist fast die selbe wie bei der Initiierung einer einzelnen
            Übersetzungsquelle mit einem Unterschied. Es darf nur ein Verzeichnis angegeben werden,
            statt einer Datei, welches gescannt werden soll.
        </para>

        <example id="zend.translate.using.languages.directory.example">
            <title>Scannen nach Quellen in einer Verzeichnisstruktur</title>
            <programlisting role="php"><![CDATA[
// Angenommen wir haben die folgende Struktur
//  /language/
//  /language/login/login.tmx
//  /language/logout/logout.tmx
//  /language/error/loginerror.tmx
//  /language/error/logouterror.tmx

$translate = new Zend_Translate('tmx', '/language');
]]></programlisting>
        </example>

        <para>
            <classname>Zend_Translate</classname> muß also nicht nur das angegebene Verzeichnis durchsuchen,
            sondern auch alle Unterverzeichnisse nach Dateien für Übersetzungen. Das macht die
            Verwendung sehr einfach. Aber <classname>Zend_Translate</classname> wird alle Dateien ignorieren,
            welche keine Quellen sind, oder wärend des Einlesens der Übersetzungsdaten Fehler
            produzieren. Man sollte also sicherstellen das alle Übersetzungsquellen korrekt sind
            und gelesen werden können weil man keinen Fehler erhält wenn eine Datei fehlerhaft ist
            oder nicht gelesen werden kann.
        </para>

        <note>
            <para>
                Abhängig davon wie tief die Verzeichnisstruktur ist und wieviele Dateien innerhalb
                dieser Struktur vorhanden sind, kann es eine sehr lange Zeit dauern bis
                <classname>Zend_Translate</classname> fertig ist.
            </para>
        </note>

        <para>
            In unserem Beispiel haben wir das TMX Format verwendet welches die Sprache enthält die
            innerhalb der Quelle verwendet wird. Aber viele der anderen Quellformate sind nicht
            dazu fähig die Sprache in der Datei selbst zu inkludieren. Aber auch diese quellen
            können mit der automatischen Erkennung verwendet werden wenn ein paar Dinge
            berücksichtigt werden die anbei beschrieben sind:
        </para>

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

            <title>Sprachen durch die Benennung von Verzeichnissen</title>

            <para>
                Ein Weg, die automatische Spracherkennung zu inkludieren, ist es die Verzeichnisse
                relativ zur Sprache zu benennen, welche in den Quellen des betreffenden
                Verzeichnisses verwendet wird. Das ist der einfachste Weg und wird zum Beispiel in
                Standard Gettext Implementationen verwendet.
            </para>

            <para>
                <classname>Zend_Translate</classname> benötigt die '<code>scan</code>' Option um zu wissen
                das es die Namen aller Verzeichnisse nach Sprachen durchsuchen soll. Siehe das
                folgende Beispiel für Details:
            </para>

            <example id="zend.translate.using.detection.directory.example">
                <title>Verzeichnisse nach Sprachen durchsuchen</title>
                <programlisting role="php"><![CDATA[
// Angenommen wir haben die folgende Struktur
//  /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(
    'gettext',
    '/language',
    null,
    array('scan' => Zend_Translate::LOCALE_DIRECTORY));
]]></programlisting>
            </example>

            <note>
                <para>
                    Das funktioniert nur für Adapter die die Sprache nicht in der Quelldatei
                    enthalten. Die Verwendung dieser Option wird zum Beispiel mit TMX ignoriert.
                    Sprachdefinitionen im Dateinamen werden bei der Verwendung dieser Option
                    ignoriert.
                </para>
            </note>

            <note>
                <para>
                    Man sollte acht geben wenn man verschiedenen Unterverzeichnisse in der gleichen
                    Struktur hat. Angenommen wir haben eine Struktur wie
                    <code>/language/module/de/en/file.mo</code>. In diesem Fall enthält der Pfad
                    mehrere Strings die als Gebietsschema erkannt werden würden. Das könnte
                    entweder <code>de</code> oder <code>en</code> sein. In solch einem Fall ist das
                    Verhalten nicht definiert und es wird empfohlen die Dateierkennung zu
                    verwenden.
                </para>
            </note>

        </sect3>

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

            <title>Sprache durch Dateinamen</title>

            <para>
                Ein anderer Weg um die Sprache automatisch zu erkennen ist die Verwendung von
                speziellen Dateienamen. Man kann entweder die komplette Datei oder Teile der
                Datei nach der verwendeten Sprache benennen. Um diese Option zu Verwenden muß die
                '<code>scan</code>' Option bei der Initiierung gesetzt werden. Es gibt verschiedene
                Wege die Quelldateien zu benennen welche im folgenden beschrieben werden:
            </para>

            <example id="zend.translate.using.detection.filename.example">
                <title>Suchen nach Sprachen im Dateinamen</title>
                <programlisting role="php"><![CDATA[
// Angenommen wir haben die folgende Struktur
//  /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>Komplette Dateinamen</title>

                <para>
                    Die komplette Datei nach der Sprache zu benennen ist der einfachste Weg, aber
                    nur praktikabel wenn man nur eine Datei pro Verzeichnis verwendet.
                </para>

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

            </sect4>

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

                <title>Erweiterung der Datei</title>

                <para>
                    Ein anderer einfacher Weg ist die Verwendung der Dateiextension für die
                    Spracherkennung. Aber das kann verwirrend sein weil man keine Idee mehr hat
                    welche Erweiterung die Datei ursprünglich hatte.
                </para>

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

            </sect4>

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

                <title>Teile von Dateinamen</title>

                <para>
                    <classname>Zend_Translate</classname> kann die Sprache auch erkennen wenn Sie im Dateinamen enthalten
                    ist. Aber wenn man diesen Weg nimmt, muß die Sprache mit einem Trennzeichen
                    seperiert werden. Es gibt drei unterstützte Trennzeichen welche verwendet
                    werden können. Ein Punkt '.', ein Unterstrich '_', oder ein Bindestrich '-'.
                </para>

                <programlisting><![CDATA[
/languages/
/languages/view_en.mo -> erkennt englisch
/languages/view_de.mo -> erkennt deutsch
/languages/view_it.mo -> erkennt italienisch
]]></programlisting>

                <para>
                    Das erste gefundene String der von einem Trennzeichen getrennt wird das als
                    Gebietsschema interpretiert werden kann, wird verwendet. Siehe das folgende
                    Beispiel für Details.
                </para>

                <programlisting><![CDATA[
/languages/
/languages/view_en_de.mo -> erkennt englisch
/languages/view_en_es.mo -> erkennt englisch und überschreibt die erste Datei
/languages/view_it_it.mo -> erkennt italienisch
]]></programlisting>

                <para>
                    Alle drei Trennzeichen werden verwendet um das Gebietsschema zu erkennen. Wenn
                    der Dateiname mehrere Trennzeichen enthält, hängt das erste gefundene
                    Trennzeichen von der Reihenfolge der Trennzeichen ab die verwendet werden.
                    Siehe das folgende Beispiel für Details.
                </para>

                <programlisting><![CDATA[
/languages/
/languages/view_en-it.mo -> erkennt englisch weil '_' vor '-' verwendet wird
/languages/view-en_it.mo -> erkennt italienisch weil '_' vor '-' verwendet wird
/languages/view_en.it.mo -> erkennt italienisch weil '.' vor '_' verwendet wird
]]></programlisting>

            </sect4>

        </sect3>

    </sect2>

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

        <title>Prüfen von Übersetzungen</title>

        <para>
            Normalerweise wird Text ohne Berechnungen übersetzt. Aber manchmal ist es notwendig
            zu wissen, ob ein Text in der Quelle übersetzt ist oder nicht, und hierfür kann die
            Methode <code>isTranslated()</code> verwendet werden.
        </para>

        <para>
            <code>isTranslated($messageId, $original = false, $locale = null)</code> nimmt den Text
            bzw die Id von der man wissen will ob sie Übersetzbar ist, als ersten Parameter, und
            als optionalen dritten Parameter das Gebietsschema für das man die Prüfung durchführen
            will. Der optionale zweite Parameter definiert ob die Übersetzung fix für die
            definierte Sprache ist oder ob ein kleineres Set von Übersetzungen verwendet werden
            kann. Wenn ein Text, welcher für 'en' zurückgegeben werden kann, aber nicht für
            'en_US', dann wird die Übersetzung normalerweise zurückgegeben, aber wenn
            <code>$original</code> auf true gesetzt ist, gibt die <code>isTranslated()</code>
            Methode in solche Fällen false zurück.
        </para>

        <example id="zend.translate.using.istranslated.example">
            <title>Prüfen ob ein Text übersetzbar ist</title>
            <programlisting role="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' kann übersetzt werden";
}

if (!($translate->isTranslated('message1', true, 'de'))) {
    print "'message1' kann nicht in 'de' übersetzt werden da es "
        . "nur in 'de_AT' vorhanden ist";
}

if ($translate->isTranslated('message1', false, 'de')) {
    print "'message1' kann in 'de_AT' übersetzt werden " .
    "da es zu 'de' zurückfällt";
}
]]></programlisting>
        </example>

    </sect2>

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

        <title>Wie können nicht gefundene Übersetzungen geloggt werden</title>

        <para>
            Wenn man eine größere Site hat, oder man die Übersetzungsdateien manuell erstellt hat man oft
            das Problem das einige Meldungen nicht übersetzt werden. Aber es gibt eine einfache Lösung wenn
            man <classname>Zend_Translate</classname> verwendet.
        </para>

        <para>
            Man muß den folgenden zwei oder drei einfachen Schritten folgen. Erstens, muß man eine Instanz von
            <classname>Zend_Log</classname> erstellen. Und dann muß man diese Instanz an <classname>Zend_Translate</classname>
            übergeben. Siehe das folgende Beispiel:
        </para>

        <example id="zend.translate.using.logging.example">
            <title>Übersetzungen loggen</title>
            <programlisting role="php"><![CDATA[
$translate = new Zend_Translate('gettext', $path, 'de');

// Eine Log Instanz erstellen
$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
$log    = new Zend_Log($writer);

// Diese der Übersetzungs-Instanz hinzufügen
$translate->setOptions(array(
    'log'             => $log,
    'logUntranslated' => true));

$translate->translate('unbekannter String');
]]></programlisting>
        </example>

        <para>
            Jetzt steht im Log eine neue Notiz:
            <code>Untranslated message within 'de': unbekannter String</code>.
        </para>

        <note>
            <para>
                Man sollte beachten das jede Übersetzung die nicht gefunden wird mitgeloggt wird.
                Das bedeutet alle Übersetzungen wenn ein Benutzer eine nicht unterstützte Sprache
                anfragt. Aber auch jede Anfrage für eine Nachricht die nicht übersetzt werden kann
                wird mitgeloggt. Es ist zu beachten das, 100 Personen die die gleiche Übersetzung
                anfragen, auch zu 100 geloggten Notizen führen.
            </para>
        </note>

        <para>
            Dieses Feature kann nicht nur verwendet werden um Nachrichten zu Loggen sondern auch um
            diese nicht übersetzen Nachrichten in eine leere Übersetzungsdatei zu schreiben. Um das
            zu ermöglichen muß man seinen eigenen Log Writer erstellen der das Format schreibt das
            man haben will und das führende "Untranslated message" herausschneidet.
        </para>

        <para>
            Wenn man seine eigene Logmeldung haben will, kann man auch die Option
            '<code>logMessage</code>' setzen. Das '<code>%message%</code>' Token ist für die
            Platzierung der messageId in der eigenen Logmeldung zu verwenden, und das
            '<code>%locale%</code>' Token für das angefragte Gebietsschema. Siehe das folgende
            Beispiel für ein Beispiel einer selbst definierten Logmeldung:
        </para>

        <example id="zend.translate.using.logging.example2">
            <title>Selbstdefinierte Logmeldungen</title>
            <programlisting role="php"><![CDATA[
$translate = new Zend_Translate('gettext', $path, 'de');

// Eine Loginstanz erstellen
$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
$log    = new Zend_Log($writer);

// Diese der Übersetzungsinstanz hinzufügen
$translate->setOptions(array(
    'log'             => $log,
    'logMessage'      => "Fehlende '%message%' im Gebietsschema '%locale%'",
    'logUntranslated' => true));

$translate->translate('unknown string');
]]></programlisting>
        </example>

    </sect2>

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

        <title>Zugang zu Quelldaten</title>

        <para>
            Manchmal ist es nützlich, Zugang zu den übersetzten Quelldaten zu erhalten. Hierfür
            werden die folgenden zwei Methoden angeboten.
        </para>

        <para>
            Die <code>getMessageIds($locale = null)</code> Methode gibt alle bekannten Ids für
            Übersetzungen als Array zurück.
        </para>

        <para>
            Die <code>getMessages($locale = null)</code> Methode gibt die komplette
            Übersetzungs-Quelle als Array zurück. Die Ids der Übersetzungen werden als Schlüssel
            und die Übersetzten Daten als Wert verwendet.
        </para>

        <para>
            Beide Methoden akzeptieren einen optionalen Parameter <code>$locale</code> welcher,
            wenn er gesetzt wird, die Übersetzungsdaten für die spezifizierte Sprache, zurückgibt.
            Wenn dieser Parameter nicht angegeben wird, wird die aktuell gesetzte Sprache
            verwendet. Es ist zu beachten das normalerweise alle Übersetzungen in allen Sprachen
            vorhanden sein sollten. Das bedeutet das man in einer normalen Situation diesen
            Parameter nicht angeben muß.
        </para>

        <para>
            Zusätzlich kann die <code>getMessages()</code> Methode verwendet werden um das
            komplette Übersetzungsverzeichnis, mit dem Pseudo-Gebietsschema 'all', zurückgeben.
            Das gibt alle vorhandenen Übersetzungsdaten für jedes hinzugefügte Gebietsschema
            zurück.
        </para>

        <note>
            <para>
                Achtung: Das zurückgegebene Array kann
                <emphasis role="strong">sehr groß</emphasis> sein, abhängig von der Anzahl an
                hinzugefügten Gebietsschemata und der Anzahl an Übersetzungsdaten.
            </para>
        </note>

        <example id="zend.translate.using.sourcedata.example">
            <title>Handhabung von Quelldaten</title>
            <programlisting role="php"><![CDATA[
// gibt alle bekannten Übersetzungs Ids zurück
$messageIds = $translate->getMessageIds();
print_r($messageIds);

// oder nur die spezifizierte Sprache
$messageIds = $translate->getMessageIds('en_US');
print_r($messageIds);

// gibt die kompletten Übersetzungs Daten zurück
$source = $translate->getMessages();
print_r($source);
]]></programlisting>
        </example>

    </sect2>

</sect1>