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.

// 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:

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.

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.

// 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
}

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

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

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

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.

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.

// 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.

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:

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

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

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

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

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

/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

/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

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

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

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

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.

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.

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.

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.

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

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:

$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.

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:

$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:

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

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.

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