# Zusätzliche Features für Übersetzungen

Es gibt verschiedene zusätzliche Features, welche von `Zend_Translate` unterstützt werden. Lesen Sie weiter für zusätzliche Informationen.

## Optionen für Adapter

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: 'clear' 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.

Man kann Optionen temporär setzen, indem man sie an die Funktion `addTranslation()` übergibt. Außerdem kann die Methode `setOptions()` benutzt werden, um Optionen permanent zu setzen.

### Benutzen von Übersetzungsoptionen

    // 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
        )
    );

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

### Optionen für Übersetzungs-Adapter

Option | Adapter | Beschreibung | Standardwert
--- | --- | --- | ---
adapter | nur `Zend_Translate` | Definiert den Adapter, der für die Übersetzung verwendet wird. Diese Option kann nur angegeben werden, wenn eine neue Instanz von `Zend_Translate` erstellt wird. Wenn sie im Nachhinein gesetzt wird, dann wird sie ignoriert. | Muss gesetzt werden, da es keinen Standardwert gibt
clear | Alle | Wenn `TRUE` gesetzt wird, werden bereits gelesene Übersetzungen entfernt. Das kann statt dem Erstellen einer neuen Instanz verwendet werden, wenn neue Übersetzungsdaten gelesen werden. | `FALSE`
cache | Alle | Setzt einen Cache für den Übersetzungsadapter. Dieser muss eine Instanz von `Zend_Cache_Core` | Standardmäßig ist kein Cache gesetzt
content | Alle | Setzt den Inhalt für den Übersetzungsadapter. Das könnte ein Array, ein Dateiname oder ein Verzeichnis sein. Welche Art an Inhalt unterstützt wird, hängt vom verwendeten Adapter ab. | Der Standardwert hängt vom verwendeten Adapter ab
disableNotices | Alle | Wenn es auf `TRUE` gesetzt wird, werden alle Notizen betreffend nicht vorhandenen Übersetzungen ausgeschaltet. Man sollte diese Option in einer Produktivumgebung auf `TRUE` setzen. | `FALSE`

ignore

Alle

Alle Verzeichnisse und Dateien, die mit diesem Präfix beginnen, werden bei der Suche nach Dateien ignoriert. Der Standardwert ist '.' was zu dem Verhalten führt das alle versteckten Dateien ignoriert werden. Wenn dieser Wert auf 'tmp' gesetzt wird, werden Verzeichnisse und Dateien wie z.B. 'tmpImages' und 'tmpFiles', 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.

.

log | Alle | Eine Instanz von `Zend_Log`, wohin nicht übersetzbare Meldungen und Notizen geschrieben werden | `NULL`
logMessage | Alle | Die Nachricht, die in das Log geschrieben werden soll | Untranslated message within '%locale%': %message%
logPriority | Alle | Die Priorität, welche verwendet wird, wenn eine Nachricht in das Log geschrieben wird | 5
logUntranslated | Alle | Wenn diese Option auf `TRUE` gesetzt wird, werden alle Nachrichten-Ids, die nicht übersetzt werden können, in das angehängte Log geschrieben. | `FALSE`
reload | Alle | Wenn diese Option auf `TRUE` 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. | `FALSE`
route | all | Diese Option erlaubt das Umleiten von einer nicht existierenden Übersetzung zu anderen Sprachen. Siehe den Abschnitt für Umleitung über Details für diese Option. | `NULL`
scan | Alle | Wenn `NULL` gesetzt wird, wird die Verzeichnisstruktur nicht gescannt. Wenn `Zend_Translate::LOCALE_DIRECTORY` gesetzt wird, wird das Gebietsschema im Verzeichnis gesucht. Wenn `Zend_Translate::LOCALE_FILENAME` gesetzt wird, wird das Gebietsschema im Dateinamen gesucht. Siehe dieses Kapitel für Details | `NULL`
tag | Alle | Setzt ein individuelles Tag welche für den verknüpften Cache verwendet wird. Die Verwendung dieser Option erlaubt es den Cache für einzelne Instanzen zu verwenden und zu löschen. Wenn diese Option nicht gesetzt wird, dann wird der verknüpfte Cache kombiniert für alle Instanzen verwendet. | `Zend_Translate`
delimiter | Csv | Definiert, welches Zeichen als Trenner für Quelle und Übersetzung verwendet wird | ;
enclosure | Csv | Definiert die maximale Länge einer CSV Zeile. Auf 0 gesetzt wird sie automatisch erkannt | "
length | Csv | Definiert das zu verwendende Einschließungszeichen. Standard ist das doppelte Hochkomma | 0
useId | Xliff und Tmx | Wenn diese Option auf `FALSE` gesetzt wird, dann wird die originale Zeichenfolge als Message-Id verwendet. Der Standardwert dieser Option ist `TRUE`, was bedeutet, dass die Id des trans-unit Elements als Message-Id verwendet wird. | `TRUE`

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

Um die Option zurückzugeben, kann die Methode `getOptions()` verwendet werden. Wenn `getOptions()` 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.

## Mit Sprachen arbeiten

Wenn mit verschiedenen Sprachen gearbeitet wird, gibt es ein paar Methoden die nützlich sind.

Die Methode `getLocale()` kann verwendet werden, um die aktuell gesetzte Sprache zu erhalten. Sie kann entweder eine Instanz von `Zend_Locale` oder den Bezeichner des Gebietsschemas enthalten.

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

Die Methode `isAvailable()` prüft, ob eine angegebene Sprache bereits vorhanden ist. Es wird `TRUE` zurückgegeben, wenn Daten für die angegebene Sprache existieren.

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

### Handhabung von Sprachen mit Adaptern

    // gibt die aktuell gesetzte Sprache zurück
    $actual = $translate->getLocale();

    // der optionale Parameter kann während 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
    }

### Automatische Handhabung von Sprachen

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

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:

#### Automatische Erkennen der Sprache

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

Nachdem eine Sprache von Hand mit der Methode `setLocale()` gesetzt wurde, wird die automatische Erkennung ausgeschaltet und übergangen.

Wenn man sie wieder verwenden will, kann die Sprache auto mit `setLocale()` gesetzt werden, was die automatische Erkennung für `Zend_Translate` wieder reaktiviert.

Seit dem Zend Framework 1.7.0 unterstützt `Zend_Translate` auch die Verwendung eines anwendungsweiten Gebietsschemas. Man kann einfach eine `Zend_Locale` 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.

    // 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();

### Ein Land als Sprache verwenden

Man kann auch ein Land als "locale"-Parameter verwenden. Dass kann nützlich sein, wenn man seinem Benutzer Fahnen anbieten will, welche das Land repräsentieren in dem er lebt. Wenn er seine Fahne auswählt, würde er automatisch die Standardsprache für dieses Land erhalten.

Wenn der Benutzer zum Beispiel US auswählt, dann würde er en_US als Gebietsschema erhalten, welches dann verwendet wird. Das führt automatisch zur Sprache en, welche die Standardsprache für das Land US ist.

    $translate = new Zend_Translate(
        array(
            'adapter' => 'gettext',
            'content' => 'my_de.mo',
            'locale'  => 'US'
        )
    );

#### Länder immer groß schreiben

Wenn man diese Syntax verwendet, sollte man die Eingaben immer groß schreiben, wenn man weiß, dass es ein Land ist. Der Grund hierfür ist, dass es auch Sprachen gibt, welche die gleichen Buchstaben wie ein Land verwenden. Nehmen wir zum Beispiel om. Man könnte erwarten ar_OM zu erhalten, wenn man das Land "Oman" meint oder man könnte die Sprache "Oromo" erwarten, welche zum Beispiel in Kenia gesprochen wird.

Da `Zend_Translate` auf Sprachen bezogen ist, würde es in so einem Fall immer die Sprache wählen. Deshalb sollte das Gebietsschema immer groß geschrieben werden, wenn man will, dass es als Land erkannt wird.

## Automatische Erkennung von Quellen

`Zend_Translate` kann Übersetzungsquellen automatisch erkennen. Es muss also nicht jede Quelldatei manuell deklariert werden. Man kann diesen Job `Zend_Translate` überlassen, welches die komplette Verzeichnisstruktur nach Quelldateien durchsucht.

Automatische Erkennung der Quellen ist seit Zend Framework Version 1.5 vorhanden.

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.

### Scannen nach Quellen in einer Verzeichnisstruktur

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

`Zend_Translate` muss also nicht nur das angegebene Verzeichnis nach Dateien für Übersetzungen durchsuchen, sondern auch alle Unterverzeichnisse. Das macht die Verwendung sehr einfach. Aber `Zend_Translate` wird alle Dateien ignorieren, welche keine Quellen sind oder während 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.

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

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:

### Sprachen durch die Benennung von Verzeichnissen

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.

`Zend_Translate` benötigt die 'scan' Option um zu wissen, dass es die Namen aller Verzeichnisse nach Sprachen durchsuchen soll. Siehe das folgende Beispiel für Details:

#### Verzeichnisse nach Sprachen durchsuchen

    // 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
        )
    );

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.

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

### Sprache durch Dateinamen

Ein anderer Weg um die Sprache automatisch zu erkennen ist die Verwendung von speziellen Dateinamen. Man kann entweder die komplette Datei oder Teile der Datei nach der verwendeten Sprache benennen. Um diese Option zu Verwenden muss die 'scan' Option beim Initiieren gesetzt werden. Es gibt verschiedene Wege die Quelldateien zu benennen, welche im folgenden beschrieben werden:

#### Suchen nach Sprachen im Dateinamen

    // 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
        )
    );

#### Komplette Dateinamen

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

    /languages/
    /languages/en.mo
    /languages/de.mo
    /languages/es.mo

#### Dateierweiterung

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.

    /languages/
    /languages/view.en
    /languages/view.de
    /languages/view.es

#### Teile von Dateinamen

`Zend_Translate` kann die Sprache auch erkennen, wenn sie im Dateinamen enthalten ist. Aber wenn man diesen Weg wählt, muss die Sprache mit einem Trennzeichen separiert werden. Es gibt drei unterstützte Trennzeichen, welche verwendet werden können. Ein Punkt '.', ein Unterstrich '_', oder ein Bindestrich '-'.

    /languages/
    /languages/view_en.mo -> erkennt englisch
    /languages/view_de.mo -> erkennt deutsch
    /languages/view_it.mo -> erkennt italienisch

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.

    /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

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.

    /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

### Spezielle Dateien und Verzeichnisse ignorieren

Manchmal ist es nützlich, Dateien oder sogar Verzeichnisse davon auszunehmen, dass diese automatisch hinzugefügt werden. Hierfür kann man die Option ignore verwenden, welche drei mögliche Verwendungen anbietet.

#### Ein spezielles Verzeichnis oder eine Datei ignorieren

Standardmäßig ist `Zend_Translate` so gesetzt, dass alle Dateien und Verzeichnisse, welche mit '`/.`' beginnen ignoriert werden. Dies bedeutet, dass SVN-Dateien ignoriert werden.

Man kann eine eigene Syntax setzen, indem ein String für die Option ignore angegeben wird. Der Verzeichnistrenner wird automatisch angehängt, wenn er nicht angegeben wurde.

    $translate = new Zend_Translate(
        array(
            'adapter' => $adapter,
            'content' => $content,
            'locale'  => $locale,
            'ignore'  => 'test'
        )
    );

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

##### Verhindern, dass SVN-Dateien gesucht werden

Wenn man diese Option setzt, dann wird das standardmäßige '`/.`' gelöscht. Dies bedeutet, dass `Zend_Translate` dann alle Dateien von den versteckten SVN-Verzeichnissen hinzugefügt werden. Wenn man mit SVN arbeitet, dann sollte man die Array-Syntax verwenden, welche im nächsten Abschnitt beschrieben wird.

#### Verschiedene Verzeichnisse oder Dateien ignorieren

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.

    $translate = new Zend_Translate(
        array(
            'adapter' => $adapter,
            'content' => $content,
            'locale'  => $locale,
            'ignore'  => array('.', 'test', 'old')
        )
    );

Im obigen Fall werden alle Dateien oder Verzeichnisse ignoriert, die auf eines der drei Muster passen. Aber sie müssen mit dem Muster beginnen, um erkannt und ignoriert zu werden.

#### Spezifische Namen ignorieren

Um Dateien und Verzeichnisse zu ignorieren, welche nicht mit einem definierten Muster beginnen, aber ein spezielles Muster irgendwo in ihrem Namen haben, kann man einen regulären Ausdruck verwenden.

Um einen regulären Ausdruck zu verwenden, muss der Array-Schlüssel der Option ignore mit regex beginnen.

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

Im obigen Fall haben wir zwei 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 test enthält ignoriert wird. Zusätzlich werden alle Dateien und Verzeichnisse, welche mit deleted enden, nicht als Übersetzung hinzugefügt.

## Weiterleiten von Übersetzungen

Nicht jede Nachrichten ID kann übersetzt werden. Aber manchmal ist es sinnvoll die Ausgabe der Übersetzung von einer anderen Sprache durchzuführen statt die Nachrichten ID selbst zurückzugeben. Man kann dies durchführen indem man die Option route verwendet.

Man kann eine Route für jede Sprache hinzufügen. Siehe das folgende Beispiel:

    $translate = new Zend_Translate(
        array(
            'adapter' => $adapter,
            'content' => $content,
            'locale'  => $locale,
            'route'   => array('fr' => 'en', 'de' => 'fr')
        )
    );

Das oben stehende give eine englische Übersetzung für alle Nachrichten zurück welche nicht in französisch übersetzt werden können. Und es gibt eine französische Übersetzung für alle Nachrichten zurück welche nicht in deutsch übersetzt werden können. Es gibt sogar eine englische Übersetzung für alle Nachrichten zurück welche weder in deutsch noch in französisch übersetzt werden können. So kann man sogar eine komplette Übersetzung-Kette definieren.

Dieses Feature kann für jedermann interessant sein. Aber man sollte darauf achten dass es problematisch sein kann Übersetzungen einer falsche oder anderen Sprache zurück zu geben wenn der Benutzer diese Sprache nicht versteht. Man sollte dieses Feature also sehr sparsam einsetzen.

## Mehrere Übersetzungsquellen kombinieren

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.

Durch Kombination mehrerer Übersetzungsadapter kann man diese in einer Instanz verwenden. Siehe das folgende Beispiel:

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

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.

### Speicher sparen

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, kann man sie entfernen (unset).

Wenn man Verzeichnisse scannt, kann es sein, dass man nur eine definierte Sprache verwenden will. Die vordefinierten Ressourcen sind zum Beispiel 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.

    $translate->addTranslation(
        array(
            'content' => $translate_second,
            'locale' => 'en'
        )
    );

Das erlaubt es trotzdem durch die Verzeichnisse zu scannen und nur jene Sprachen hinzuzufügen, welche für die eigene Anwendung relevant sind.

## Prüfen von Übersetzungen

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 `isTranslated()` verwendet werden.

`isTranslated($messageId, $original = false, $locale = null)` 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 `$original` auf `TRUE` gesetzt ist, gibt die `isTranslated()` Methode in solche Fällen `FALSE` zurück.

### Prüfen ob ein Text übersetzbar ist

    $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";
    }

## Wie können nicht gefundene Übersetzungen geloggt werden

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 `Zend_Translate` verwendet.

Man muss den folgenden zwei oder drei einfachen Schritten folgen. Zuerst muss man eine Instanz von `Zend_Log` erstellen. Anschließend muss man diese Instanz an `Zend_Translate` übergeben. Siehe das folgende Beispiel:

### Übersetzungen loggen

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

Jetzt steht im Log eine neue Notiz: Untranslated message within 'de': unbekannter String.

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.

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, muss man seinen eigenen Log Writer erstellen, der das Format schreibt, das man haben will und das führende "Untranslated message" herausschneidet.

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

### Selbstdefinierte Logmeldungen

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

Zusätzlich kann man auch die Priorität ändern, welche verwendet wird, um eine Nachricht in das Log zu schreiben. Standardmäßig wird die Priorität Zend_Log::NOTICE verwendet. Sie ist identisch mit dem Wert 5. Wenn man die Priorität verändern will, kann man jede der Prioritäten von `Zend_Log` verwenden. Siehe das folgende Beispiel:

### Selbst definierte Log Priorität

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

    $translate = new Zend_Translate(
        array(
            'adapter' => 'gettext',
            'content' => $path,
            'locale'  => 'de',
            'log'             => $log,
            'logMessage'      => "'%message%' fehlt im Gebietsschema '%locale%'",
            'logPriority'     => Zend_Log::ALERT,
            'logUntranslated' => true
        )
    );

    $translate->translate('unbekannter String');

## Zugang zu Quelldaten

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

Die `getMessageIds($locale = null)` Methode gibt alle bekannten Ids für Übersetzungen als Array zurück.

Wenn man die Message ID für eine angegebene Übersetzung wissen will, dann kan man die Methode `getMessageId()` verwenden.

Die `getMessages($locale = null)` Methode gibt die komplette Übersetzungsquelle als Array zurück. Die Ids der Übersetzungen werden als Schlüssel und die übersetzten Daten als Wert verwendet.

Beide Methoden akzeptieren einen optionalen Parameter `$locale` 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 muss.

Zusätzlich kann die `getMessages()` 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.

Achtung: Das zurückgegebene Array kann sehr groß sein, abhängig von der Anzahl an hinzugefügten Gebietsschemata und der Anzahl an Übersetzungsdaten.

### Handhabung von Quelldaten

    // 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);