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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 21661 -->
<!-- Reviewed: 21049 -->
<sect1 id="zend.translate.additional">
    <title>Zusätzliche Features für Übersetzungen</title>

    <para>
        Es gibt verschiedene zusätzliche Features, welche von <classname>Zend_Translate</classname>
        unterstützt werden. Lesen Sie weiter für zusätzliche Informationen.
    </para>

    <sect2 id="zend.translate.additional.options">
        <title>Optionen für Adapter</title>

        <para>
            Optionen können bei allen Adaptern verwendet werden. Natürlich sind die Optionen für
            alle Adapter verschieden. Die Optionen können bei der Erstellung des Objekts gesetzt
            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. Andere Sprachen bleiben davon unberührt.
        </para>

        <para>
            Man kann Optionen temporär setzen, indem man Sie an die Funktion
            <methodname>addTranslation()</methodname> übergibt. Ausserdem kann die Methode
            <methodname>setOptions()</methodname> benutzt werden, um Optionen permanent zu setzen.
        </para>

        <example id="zend.translate..additional.options.example">
            <title>Benutzen von Übersetzungsoptionen</title>

            <programlisting language="php"><![CDATA[
// Definiere ':' als Trenner für die Quelldatei der Übersetzung
$translate = new Zend_Translate(
    array(
        'adapter' => 'csv',
        'content' => '/path/to/mytranslation.csv',
        'locale'  => 'de',
        'delimiter' => ':'
    )
);

...

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

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

        <table id="zend.translate.additional.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>adapter</entry>
                        <entry>nur Zend_Translate</entry>

                        <entry>
                            Definiert den Adapter der für die Übersetzung verwendet wird. Diese
                            Option kann nur angegeben werden wenn eine neue Instanz von
                            <classname>Zend_Translate</classname> erstellt wird. Wenn Sie im
                            Nachhinein gesetzt wird, dann wird Sie ignoriert
                        </entry>

                        <entry>
                            <emphasis>Muss gesetzt werden da es keinen Standardwert gibt</emphasis>
                        </entry>
                    </row>

                    <row>
                        <entry>clear</entry>
                        <entry>Alle</entry>

                        <entry>
                            Wenn <constant>TRUE</constant> 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><constant>FALSE</constant></emphasis></entry>
                    </row>

                    <row>
                        <entry>content</entry>
                        <entry>Alle</entry>

                        <entry>
                            Setzt den Inhalt für den Übersetzungs-Adapter. Das könnte ein Array,
                            ein Dateiname oder ein Verzeichnis sein. Welche Art an Inhalt
                            unterstützt wird hängt vom verwendeten Adapter ab.
                        </entry>

                        <entry>
                            <emphasis>Der Standardwert hängt vom verwendeten Adapter ab</emphasis>
                        </entry>
                    </row>

                    <row>
                        <entry>disableNotices</entry>
                        <entry>Alle</entry>

                        <entry>
                            Wenn es auf <constant>TRUE</constant> gesetzt wird, werden alle Notizen
                            betreffend nicht vorhandenen Übersetzungen ausgeschaltet. Man sollte
                            diese Option in einer Produktivumgebung auf <constant>TRUE</constant>
                            setzen.
                        </entry>

                        <entry><emphasis><constant>FALSE</constant></emphasis></entry>
                    </row>

                    <row>
                        <entry>ignore</entry>
                        <entry>Alle</entry>

                        <entry>
                            Alle Verzeichnisse und Dateien, die mit diesem Präfix beginnen, werden
                            bei der Suche nach Dateien ignoriert. Der Standardwert ist
                            <emphasis>'.'</emphasis> was zu dem Verhalten führt das
                            alle versteckten Dateien ignoriert werden. Wenn dieser Wert auf
                            <code>'tmp'</code> gesetzt wird, werden Verzeichnisse und
                            Dateien wie z.B. <code>'tmpImages'</code> und <code>'tmpFiles'</code>,
                            sowie alle darunter liegenden Verzeichnisse ignoriert. Diese Option
                            akzeptiert auch ein Array welches verwendet werden kann wenn man mehr
                            als einen Präfix ignorieren will.
                        </entry>

                        <entry><emphasis>.</emphasis></entry>
                    </row>

                    <row>
                        <entry>log</entry>
                        <entry>Alle</entry>

                        <entry>
                            Eine Instanz von <classname>Zend_Log</classname>, wohin nicht
                            übersetzbare Meldungen und Notizen geschrieben werden
                        </entry>

                        <entry><emphasis><constant>NULL</constant></emphasis></entry>
                    </row>

                    <row>
                        <entry>logMessage</entry>
                        <entry>Alle</entry>
                        <entry>Die Nachricht, die in das Log geschrieben werden soll</entry>

                        <entry>
                            <emphasis>Untranslated message within '%locale%': %message%</emphasis>
                        </entry>
                    </row>

                    <row>
                        <entry>logUntranslated</entry>
                        <entry>Alle</entry>

                        <entry>
                            Wenn diese Option auf <constant>TRUE</constant> gesetzt wird, werden
                            alle Nachrichten-Ids, die nicht übersetzt werden können, in das
                            angehängte Log geschrieben.
                        </entry>

                        <entry><emphasis><constant>FALSE</constant></emphasis></entry>
                    </row>

                    <row>
                        <entry>reload</entry>
                        <entry>Alle</entry>

                        <entry>
                            Wenn diese Option auf <constant>TRUE</constant> gesetzt wird, werden die
                            Dateien in den Cache nachgeladen. Diese Option kann verwendet werden, um
                            den Cache wieder herzustellen oder Übersetzungen zu bereits gecachten
                            Daten hinzuzufügen, nachdem der Cache bereits erstellt wurde.
                        </entry>

                        <entry><emphasis><constant>FALSE</constant></emphasis></entry>
                    </row>

                    <row>
                        <entry>scan</entry>
                        <entry>Alle</entry>

                        <entry>
                            Wenn <constant>NULL</constant> gesetzt wird, wird die Verzechnisstruktur
                            nicht gescannt. Wenn
                            <constant>Zend_Translate::LOCALE_DIRECTORY</constant> gesetzt wird,
                            wird das Gebietsschema im Verzeichnis gesucht. Wenn
                            <constant>Zend_Translate::LOCALE_FILENAME</constant> gesetzt wird,
                            wird das Gebietsschema im Dateinamen gesucht. Siehe
                            <xref linkend="zend.translate.additional.detection" /> für Details
                        </entry>

                        <entry><emphasis><constant>NULL</constant></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>;</emphasis></entry>
                    </row>

                    <row>
                        <entry>enclosure</entry>
                        <entry>Csv</entry>

                        <entry>
                            Definiert die maximale Länge einer CSV Zeile. Auf 0 gesetzt wird sie
                            automatisch erkannt
                        </entry>

                        <entry><emphasis>"</emphasis></entry>
                    </row>

                    <row>
                        <entry>length</entry>
                        <entry>Csv</entry>

                        <entry>
                            Definiert das zu verwendende Einschließungszeichen. Standard ist das
                            doppelte Hochkomma
                        </entry>

                        <entry><emphasis>0</emphasis></entry>
                    </row>

                    <row>
                        <entry>useId</entry>
                        <entry>Xliff und Tmx</entry>

                        <entry>
                            Wenn diese Option auf <constant>FALSE</constant> gesetzt wird, dann wird
                            die originale Zeichenfolge als Message-Id verwendet. Der Standardwert dieser
                            Option ist <constant>TRUE</constant>, was bedeutet, dass die Id des
                            trans-unit Elements als Message-Id verwendet wird.
                        </entry>

                        <entry><emphasis><constant>TRUE</constant></emphasis></entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Wenn man selbstdefinierte Optionen haben will, können diese auch in allen Adaptern
            verwendet werden. Die Methode <methodname>setOptions()</methodname>  kann verwendet
            werden, um die eigene Option zu definieren. <methodname>setOptions()</methodname>
            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,
            dass keine existierende Option überschrieben wird, die von einem Adapter verwendet wird.
        </para>

        <para>
            Um die Option zurückzugeben, kann die Methode <methodname>getOptions()</methodname>
            verwendet werden. Wenn <methodname>getOptions()</methodname> ohne einen Parameter
            aufgerufen wird, gibt sie alle Optionen zurück. Wenn der optionale Parameter angegeben
            ist, wird nur die dadurch bestimmte Option zurückgegeben.
        </para>
    </sect2>

    <sect2 id="zend.translate.additional.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 Methode <methodname>getLocale()</methodname> 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 Methode <methodname>setLocale()</methodname> setzt eine neue Standardsprache für
            Übersetzungen. Das verhindert, dass der optionale Sprachparameter der
            Methode <methodname>translate()</methodname> mehr als einmal gesetzt werden muß. Wenn
            die angegebene Sprache nicht existiert oder keine übersetzten Daten für diese Sprache
            vorhanden sind, versucht <methodname>setLocale()</methodname> 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 Methode <methodname>isAvailable()</methodname> prüft, ob eine angegebene Sprache
            bereits vorhanden ist. Es wird <constant>TRUE</constant> zurückgegeben, wenn Daten für
            die angegebene Sprache existieren.
        </para>

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

        <example id="zend.translate.additional.languages.example">
            <title>Handhabung von Sprachen mit Adaptern</title>

            <programlisting language="php"><![CDATA[
// gibt die aktuell gesetzte Sprache zurück
$actual = $translate->getLocale();

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

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

        <sect3 id="zend.translate.additional.languages.automatic">
            <title>Automatische Handhabung von Sprachen</title>

            <para>
                Es gilt zu beachten, dass solange man neue Sprachquellen mit der
                <methodname>addTranslation()</methodname> 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 <methodname>setLocale()</methodname> 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.additional.languages.automatic.example">
                <title>Automatische Erkennen der Sprache</title>

                <programlisting language="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(
    array(
        'adapter' => 'gettext',
        'content' => 'my_it.mo',
        'locale'  => 'auto',
        'scan'    => Zend_Translate::LOCALE_FILENAME
    )
);

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

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

// Beispiel 4:
// Gibt 'it' als Übersetzungsquelle zurück und überschreibt
// die automatischen Eigenschaften
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => 'my_it.mo',
        'locale'  => 'auto',
        'scan'    => Zend_Translate::LOCALE_FILENAME
    )
);

$translate->addTranslation(array('content' => 'my_ru.mo', 'locale' => 'ru'));
$translate->setLocale('it_IT');
]]></programlisting>
            </example>

            <para>
                Nachdem eine Sprache von Hand mit der Methode <methodname>setLocale()</methodname>
                gesetzt wurde, wird die automatische Erkennung ausgeschaltet und übergangen.
            </para>

            <para>
                Wenn man sie wieder verwenden will, kann die Sprache
                <emphasis>auto</emphasis> mit <methodname>setLocale()</methodname> 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 language="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(array('adapter' => 'gettext', 'content' => '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.additional.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 gleiche wie beim Initiieren einer einzelnen
            Übersetzungsquelle mit einem Unterschied. Es darf statt einer Datei nur
            ein Verzeichnis angegeben werden, welches gescannt werden soll.
        </para>

        <example id="zend.translate.additional.languages.directory.example">
            <title>Scannen nach Quellen in einer Verzeichnisstruktur</title>

            <programlisting language="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(
    array('adapter' => 'tmx', 'content' => '/language')
);
]]></programlisting>
        </example>

        <para>
            <classname>Zend_Translate</classname> muß also nicht nur das angegebene Verzeichnis
            nach Dateien für Übersetzungen durchsuchen, sondern auch alle Unterverzeichnisse. 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, dass 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, welche nachfolgend beschrieben werden:
        </para>

        <sect3 id="zend.translate.additional.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, dass es die Namen aller Verzeichnisse nach Sprachen durchsuchen soll. Siehe
                das folgende Beispiel für Details:
            </para>

            <example id="zend.translate.additional.detection.directory.example">
                <title>Verzeichnisse nach Sprachen durchsuchen</title>

                <programlisting language="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(
    array(
        'adapter' => 'gettext',
        'content' => '/language',
        'scan'    => Zend_Translate::LOCALE_DIRECTORY
    )
);
]]></programlisting>
            </example>

            <note>
                <para>
                    Das funktioniert nur für Adapter, welche 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 aufpassen, wenn man verschiedene 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.additional.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 beim Initiieren gesetzt werden. Es gibt verschiedene
                Wege die Quelldateien zu benennen, welche im folgenden beschrieben werden:
            </para>

            <example id="zend.translate.additional.detection.filename.example">
                <title>Suchen nach Sprachen im Dateinamen</title>

                <programlisting language="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(
    array(
        'adapter' => 'gettext',
        'content' => '/language',
        'scan'    => Zend_Translate::LOCALE_FILENAME
    )
);
]]></programlisting>
            </example>

            <sect4 id="zend.translate.additional.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.additional.detection.filename.extension">
                <title>Dateierweiterung</title>

                <para>
                    Ein anderer einfacher Weg ist die Verwendung der Dateierweiterung 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.additional.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 wählt, 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>

        <sect3 id="zend.translate.additional.detection.ignore">
            <title>Spezielle Dateien und Verzeichnisse ignorieren</title>

            <para>
                Manchmal ist es nützlich Dateien oder sogar Verzeichnisse davon auszunehmen das Sie
                automatisch hinzugefügt werden. Hierfür kann man die Option
                <property>ignore</property> verwenden welche 3 mögliche Verwendungen anbietet.
            </para>

            <sect4 id="zend.translate.additional.detection.ignore.string">
                <title>Ein spezielles Verzeichnis oder eine Datei ignorieren</title>

                <para>
                    Standardmäßig ist <classname>Zend_Translate</classname> so gesetzt dass alle
                    Dateien und Verzeichnisse welche mit <emphasis>'/.'</emphasis> beginnen
                    ignoriert werden. Dies bedeutet dass <acronym>SVN</acronym> Dateien ignoriert
                    werden.
                </para>

                <para>
                    Man kann eine eigene Syntax setzen indem ein String für die Option
                    <property>ignore</property> angegeben wird. Der Verzeichnis Separator wird
                    automatisch angehängt wenn er nicht angegeben wurde.
                </para>

                <programlisting><![CDATA[
$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'ignore'  => 'test'
    )
);
]]></programlisting>

                <para>
                    Das obige Beispiel ignoriert alle Dateien und Verzeichnisse welche mit
                    <emphasis>test</emphasis> beginnen. Das bedeutet zum Beispiel
                    <filename>/test/en.mo</filename>, <filename>/testing/en.mo</filename> und
                    <filename>/dir/test_en.mo</filename>. Aber es würde trotzdem
                    <filename>/mytest/en.mo</filename> oder <filename>/dir/atest.mo</filename>
                    hinzufügen.
                </para>

                <note>
                    <title>Verhindern das SVN Dateien gesucht werden</title>

                    <para>
                        Wenn man diese Option setzt dann wird das Standardmäßige
                        <emphasis>'/.'</emphasis> gelöscht. Dies bedeutet dass
                        <classname>Zend_Translate</classname> dann alle Dateien von den versteckten
                        <acronym>SVN</acronym> Verzeichnissen hinzugefügt werden. Wenn man mit
                        <acronym>SVN</acronym> arbeitet, dann sollte man die Array Syntax verwenden
                        welche im nächsten Abschnitt beschrieben wird.
                    </para>
                </note>
            </sect4>

            <sect4 id="zend.translate.additional.detection.ignore.array.files">
                <title>Verschiedene Verzeichnisse oder Dateien ignorieren</title>

                <para>
                    Man kann auch verschiedene Dateien und Verzeichnisse ignorieren. Statt eines
                    Strings muss man einfach ein Array mit den gewünschten Namen angeben welche
                    ignoriert werden sollen.
                </para>

                <programlisting><![CDATA[
$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'ignore'  => array('.', 'test', 'old')
    )
);
]]></programlisting>

                <para>
                    Im obigen Fall werden alle 3 Syntax ignoriert. Aber trotzdem müssen Sie mit der
                    Syntax beginnen um erkannt und ignoriert zu werden.
                </para>
            </sect4>

            <sect4 id="zend.translate.additional.detection.ignore.array.names">
                <title>Spezifische Namen ignorieren</title>

                <para>
                    Um Dateien und Verzeichnisse zu ignorieren welche nicht mit einer definierten
                    Syntax beginnen, aber eine spezielle Syntax irgendwo in Ihrem Namen haben, kann
                    man einen regulären Ausdruck verwenden.
                </para>

                <para>
                    Um einen regulären Ausdruck zu verwenden muss der Array-Schlüssel der Option
                    <property>ignore</property> mit <emphasis>regex</emphasis> beginnen.
                </para>

                <programlisting><![CDATA[
$options = array('ignore' => array('regex' => '/test/u', 'regex_2' => '/deleted$/u'));
$translate = new Zend_Translate(
    array(
        'adapter' => $adapter,
        'content' => $content,
        'locale'  => $locale,
        'ignore'  => array('regex' => '/test/u', 'regex_2' => '/deleted$/u')
    )
);
]]></programlisting>

                <para>
                    Im obigen Fall haben wir 2 reguläre Ausdrücke definiert. Die Dateien und
                    Verzeichnisse werden immer mit allen angegebenen regulären Ausdrücken gesucht.
                    In unserem Fall bedeutet dies dass jede Datei welche irgendwo in Ihrem Namen
                    <emphasis>test</emphasis> enthält ignoriert wird. Zusätzlich werden alle Dateien
                    und Verzeichnisse welche mit <emphasis>deleted</emphasis> enden nicht als
                    Übersetzung hinzugefügt.
                </para>
            </sect4>
        </sect3>
    </sect2>

    <sect2 id="zend.translate.additional.combination">
        <title>Mehrere Übersetzungs-Quellen kombinieren</title>

        <para>
            Wenn man mit mehreren Übersetzungen arbeitet kann es zu Situationen kommen in denen man
            unterschiedliche Quell-Typen verwenden will. Zum Beispiel die Ressource Dateien welche
            vom Framework angeboten werden und eigene Übersetzungen welche durch Verwendung des
            Gettext Adapters vorhanden sind.
        </para>

        <para>
            Durch Kombination mehrerer Übersetzungs-Adapter kann man diese in einer Instanz
            verwenden. Siehe das folgende Beispiel:
        </para>

        <programlisting><![CDATA[
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => '\path\to\translation.mo',
        'locale'  => 'en'
    )
);

$translate_second = new Zend_Translate(
    array(
        'adapter' => 'array',
        'content' => '\resources\languages\en\Zend_Validate.php',
        'locale'  => 'en'
    )
);

$translate->addTranslation(array('content' => $translate_second));
]]></programlisting>

        <para>
            Jetzt enthält die erste Instanz alle Übersetzungen der zweiten Instanz und man kann Sie
            in der Anwendung sogar dann verwenden wenn unterschiedliche Quell-Typen verwendet
            werden.
        </para>

        <note>
            <title>Speicher sparen</title>

            <para>
                Wie man sehen kann wird die zweite Instanz nicht länger verwendet sobald man Sie der
                ersten Instanz hinzugefügt hat. Um etwas Speicher zu sparen kan man Sie entfernen
                (unset).
            </para>
        </note>

        <para>
            Wenn man Verzeichnisse scannt kann es sein dass man nur eine definierte Sprache
            verwenden will. Die vordefinierten Ressourcen zum Beispiel sind in mehr als 10 Sprachen
            vorhanden. Aber die eigene Sprache ist nicht in allen dieser Sprachen erhältlich.
            Deshalb kann man auch nur eine Sprache vom zweiten Adapter hinzufügen.
        </para>

        <programlisting><![CDATA[
$translate->addTranslation(
    array(
        'content' => $translate_second,
        'locale' => 'en'
    )
);
]]></programlisting>

        <para>
            Das erlaubt es trotzdem durch die Verzeichnisse zu scannen und nur jene Sprachen hinzu
            zu fügen welche für die eigene Anwendung relevant sind.
        </para>
    </sect2>

    <sect2 id="zend.translate.additional.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 <methodname>isTranslated()</methodname> verwendet werden.
        </para>

        <para>
            <methodname>isTranslated($messageId, $original = false, $locale = null)</methodname>
            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
            auf die definierte Sprache festgelegt ist oder ob eine kleinere Menge 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
            <varname>$original</varname> auf <constant>TRUE</constant> gesetzt ist, gibt die
            <methodname>isTranslated()</methodname> Methode in solche Fällen
            <constant>FALSE</constant> zurück.
        </para>

        <example id="zend.translate.additional.istranslated.example">
            <title>Prüfen ob ein Text übersetzbar ist</title>

            <programlisting language="php"><![CDATA[
$english = array(
    'message1' => 'Nachricht 1',
    'message2' => 'Nachricht 2',
    'message3' => 'Nachricht 3');

$translate = new Zend_Translate(
    array(
        'adapter' => 'array',
        'content' => $english,
        'locale'  => '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.additional.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, dass 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. Zuerst muß man eine
            Instanz von <classname>Zend_Log</classname> erstellen. Anschliessend muß man diese Instanz an
            <classname>Zend_Translate</classname> übergeben. Siehe das folgende Beispiel:
        </para>

        <example id="zend.translate.additional.logging.example">
            <title>Übersetzungen loggen</title>

            <programlisting language="php"><![CDATA[
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => $path,
        'locale'  => '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, dass 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, dass 100 Personen, welche 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.additional.logging.example2">
            <title>Selbstdefinierte Logmeldungen</title>

            <programlisting language="php"><![CDATA[
$translate = new Zend_Translate(
    array(
        'adapter' => 'gettext',
        'content' => $path,
        'locale'  => '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'      => "'%message%' fehlt im Gebietsschema '%locale%'",
        'logUntranslated' => true
    )
);

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

    <sect2 id="zend.translate.additional.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 <methodname>getMessageIds($locale = null)</methodname> Methode gibt alle bekannten
            Ids für Übersetzungen als Array zurück.
        </para>

        <para>
            Die <methodname>getMessages($locale = null)</methodname> Methode gibt die komplette
            Übersetzungsquelle 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 <varname>$locale</varname>
            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, dass normalerweise alle Übersetzungen in allen
            Sprachen vorhanden sein sollten. Das bedeutet, dass man in einer normalen Situation diesen
            Parameter nicht angeben muß.
        </para>

        <para>
            Zusätzlich kann die <methodname>getMessages()</methodname> 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>sehr groß</emphasis> sein, abhängig von der Anzahl an
                hinzugefügten Gebietsschemata und der Anzahl an Übersetzungsdaten.
            </para>
        </note>

        <example id="zend.translate.additional.sourcedata.example">
            <title>Handhabung von Quelldaten</title>

            <programlisting language="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 Übersetzungsdaten zurück
$source = $translate->getMessages();
print_r($source);
]]></programlisting>
        </example>
    </sect2>
</sect1>