31.3. Benutzen von Übersetzungs Adaptoren

31.3. Benutzen von Übersetzungs Adaptoren
Zurück	Kapitel 31. Zend_Translate	Weiter

Der nächste Schritt ist die Benutzung des Adapters im eigenen Code.

Beispiel 31.1. Beispiel eines einsprachigen PHP Codes

<?php
print "Beispiel\n";
print "========\n";
print "Hier steht Zeile eins\n";
print "Heute ist der " . date("d.m.Y") . "\n";
print "\n";
print "Fixe Sprache hier ist Zeile zwei\n";

Das obige Beispiel zeigt eine Ausgabe ohne Unterstützung für Übersetzungen. Der Code wird üblicherweise in der eigenen Muttersprache geschrieben. Üblicherweise muß nicht nur die Ausgabe übersetzt werden, sondern auch Fehlermeldungen oder Logmeldungen.

Der nächste Schritt ist also die Einarbeitung von Zend_Translate in den existierenden Code. Natürlich ist das viel einfacher wenn der Code bereits so geschrieben wird das er Zend_Translate benutzt anstatt das er im Nachhinein hierfür geändert wird.

Beispiel 31.2. Beispiel für mehrsprachigen PHP Code

<?php
require_once("Zend/Translate.php");

$translate = new Zend_Translate('gettext', '/my/path/source-de.mo', 'de');
$translate->addTranslation('//my/path/fr-source.mo', 'fr');

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

$translate->setLocale('fr');
print $translate->_("Fixe Sprache hier ist Zeile zwei") . "\n";

Nun nehmen wir einen tieferen Blick in was getan wurde und wie Zend_Translate in den eigenen Code integriert wird.

Erzeugen eines neuen Objekts und Definition des Basis Adapters:

<?php
require_once("Zend/Translate.php");

$translate = new Zend_Translate('gettext', '/my/path/source-de.mo', 'de');

In diesem Beispiel wird der Gettext Adapter verwendet. Die Übersetzungsdatei source-de.mo wird im Verzeichnis /my/path platziert. Diese Gettext Datei beinhaltet eine deutsche Übersetzung. Ausserdem steht eine zweite Sprachquelle für Französisch zur Verfügung.

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

<?php
print $translate->_("Beispiel")."\n";
print "========\n";
print $translate->_("Hier ist die Zeile Eins")."\n";

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

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

<?php
printf($translate->_("Today is the %1\$s") . "\n", date("d.m.Y"));

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

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

<?php
print $translate->_(1)."\n";
print "=======\n";
print $translate->_(2)."\n";

Allerdings hat dies mehrere grobe Nachteile:

Es ist nicht erkennbar was der Code ausgeben sollte indem man ihn betrachtet.

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

31.3.1. Strukturen für Übersetzungdateien

Der nächste Schritt besteht in der Erstellung der Übersetzungsdateien für die verschiedenen Sprachen welche zu übersetzen sind. Für jeden Adapter gibt es eine andere Art und Weise die hier beschrieben ist. Aber es gibt ein paar generelle Features die für alle Adaptoren relevant sind.

Zuerst muß überlegt werden wo die Übersetzung Dateien gespeichert werden. Mit Zend_Translate bestehen hierbei keinerlei Einschränkungen. Trotzdem sollten die folgenden Strukturen bevorzugt verwendet werden:

Einzeln strukturierte Quellen
```
/application
/languages
  lang.en
  lang.de
/library
                
```
Positiv: Alle Quell Dateien jeder Sprache sind in einem Verzeichnis zu finden. Keine Aufteilung der relevanten Dateien.
Sprachlich stukturierte Quellen
```
/application
/languages
  /en
    lang.en
    other.en
  /de
    lang.de
    other.de
/library
                
```
Positiv: Jede Sprache ist in einem einzelnen Verzeichnis zu finden. Jede Sprache hat sein eigenes Verzeichnis und kann durch ein eigenes Übersetzungsteam bearbeitet werden. Ausserdem ist die Verwendung von mehreren Dateien genauso transparent.
Applikations strukturierte Quellen
```
/application
  /languages
    lang.en
    lang.de
    other.en
    other.de
                
```
Positiv: Alle Quell Dateien für jede Sprache können in einem einzelnen Verzeichnis gefunden werden. Keine Aufteilung der relevanten Dateien.

Negativ: Die Benutzung von mehreren Datein für die selbe Sprache ist problematisch.
Gettext strukturierte Quellen
```
/languages
  /de
    /LC_MESSAGES
      lang.mo
      other.mo
  /en
    /LC_MESSAGES
      lang.mo
      other.mo
                
```
Positiv: Alte Gettext Quellen können ohne Veränderung der Struktur benutzt werden.

Negativ: Die Benutzung von Sub-Sub Verzeichnissen ist verwirrend für Personen die Gettext noch nie benutzt haben.
Datei strukturierte Quellen
```
/application
  /models
    mymodel.php
    mymodel.de
    mymodel.en
  /views
  /controllers
    mycontroller.de
/document_root
  /images
  /styles
  .htaccess
  index.php
  index.de
/library
  /Zend
                
```
Positiv: Jede Datei ist bei Ihrer Übersetzung zu finden source.

Negativ: Mehrfache kleine Übersetzungs Quellen machen die Übersetzung sehr schwer. Ausserdem muß jede Datei als Übersetzung Quelle hinzugefügt werden.

Einzeln strukturierte und sprachlich strukturierte Quell Dateien sind für Zend_Translate am besten benutzbar.

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

31.3.2. Erzeugung von Array Quellen

Array Quellen sind einfache Array. Aber sie müssen per Hand definiert werden da es hierfür keine Tools gibt. Weil Sie so einfach zu handhaben sind, ist Ihre Verwendung auch der schnellste Weg um zu testen ob Nachrichten innerhalb des Codes wie erwartet arbeiten. Es ist generell der beste Adapter um mit Mehrsprachigkeit zu beginnen wenn man keine diesbezüglichen Kenntnisse hat.

$english = array('message1' => 'message1',
                 'message2' => 'message2',
                 'message3' => 'message3');
$german = array('message1' => 'Nachricht1',
                'message2' => 'Nachricht2',
                'message3' => 'Nachricht3');

$translate = new Zend_Translate('array', $english, 'en');
$translate->addTranslation($deutsch, 'de');

31.3.3. Erstellung von Gettext Quellen

Gettext Quellen werden durch GNU's Gettext Bibliothek erstellt. Es gibt einige kostenlose Tools welche den Code parsen können und hierbei die gewünschten Gettext Quellen erstellen. Diese Dateien haben die Endung *.mo und sind binäre Dateien. Ein kostenloses Programm für die Erstellung der Quellen ist poEdit. Dieses Tool unterstützt auch beim Übersetzungs Prozess selbst.

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

Wie man sieht wird dieser Adapter auf exakt die gleiche Art und Weise verwendet mit einer kleinen Änderung. Den Tausch von 'array' zu 'gettext'. Alle anderen Punkte werden in jedem anderen Adapter auf exakt die gleiche Weise verwendet. Mit diesem Gettext Adapter muß nicht mehr auf die geforderte Standard Verzeichnis Struktur von Gettext geachtet werden. Auch nicht auf bindtextdomain und textdomain. Nur der Pfad und der Dateiname muß dem Adapter übergeben werden.

	Anmerkung
Man sollte immer UTF-8 als Quell Encoding verwenden. Man könnte sonst Probleme bekommen wenn man zwei verschiedene Encodings verwendet. Wenn zum Beispiel eine Quell Datei mit ISO-8815-11 und eine andere mit CP815 encoded ist. Man kann immer nur ein Encoding für alle Quell Dateien verwenden, und hierbei würde eine der gewünschten Sprachen nicht korrekt angezeigt werden. UTF-8 ist ein portables Format welches alle Sprachen unterstützt. Wenn man also UTF-8 für alle Sprachen verwendet, eliminiert man die Probleme mit inkompatiblen Encodings.

Anmerkung

Man sollte immer UTF-8 als Quell Encoding verwenden. Man könnte sonst Probleme bekommen wenn man zwei verschiedene Encodings verwendet. Wenn zum Beispiel eine Quell Datei mit ISO-8815-11 und eine andere mit CP815 encoded ist. Man kann immer nur ein Encoding für alle Quell Dateien verwenden, und hierbei würde eine der gewünschten Sprachen nicht korrekt angezeigt werden.

UTF-8 ist ein portables Format welches alle Sprachen unterstützt. Wenn man also UTF-8 für alle Sprachen verwendet, eliminiert man die Probleme mit inkompatiblen Encodings.

31.3.4. Erstellung von TMX Quellen

TMX Quellen sind der neue Industrie Standard. Sie haben den Vorteil das sie XML Dateien sind und deswegen mit jedem Texteditor und natürlich auch von Menschen direkt lesbar. Man kann TMX Dateien entweder per Hand erstellen oder man verwendet Tools dafür. Allerdings sind die meisten erhältlichen Tools die TMX Quellen erstellen können nicht kostenlos.

Beispiel 31.3. Beispiel einer TMX Datei

<?xml version="1.0" ?>
<!DOCTYPE tmx SYSTEM "tmx14.dtd">
<tmx version="1.4">
 <header creationtoolversion="1.0.0" datatype="winres" segtype="sentence" adminlang="en-us" srclang="de-at" o-tmf="abc" creationtool="XYZTool" >
 </header>
 <body>
  <tu tuid='message1'>
   <tuv xml:lang="de"><seg>Nachricht1</seg></tuv>
   <tuv xml:lang="en"><seg>message1</seg></tuv>
  </tu>
  <tu tuid='message2'>
   <tuv xml:lang="en"><seg>message2</seg></tuv>
   <tuv xml:lang="de"><seg>Nachricht2</seg></tuv>
  </tu>

$translate = new Zend_Translate('tmx', 'path/to/mytranslation.tmx', 'en');
// TMX kann mehrere Sprachen in einer einzigen TMX Datei enthalten.

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

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

31.3.5. Erstellung von CSV Quellen

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

Beispiel 31.4. Beispiel CSV Datei

#Example csv file
message1;Nachricht1
message2;Nachricht2

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

Das standardmäßige Trennzeichen für CSV Strings ist das ';' Zeichen. Aber es muß nicht dieses Zeichen verwendet werden. Mit der Option 'separator' kann man ein anderes Trennzeichen definieren das verwendet werden soll.

Wenn das Trennzeichen im zu übersetzenden String enthalten ist, dann muß es einfach verdoppelt werden. Ein Trennzeichen trennt die Original Zeichenkette von der Übersetzung. Zwei Trennzeichen schreiben ein Trennzeichen als normales Zeichen in den String. Am besten wird das folgende Beispiel für Details betrachtet:

Beispiel 31.5. Beispiel 2 für CSV Dateien

#Example csv file
# original 'message,1'
message,,1,Nachricht1
# translation 'Nachricht,2'
message2,Nachricht,,2
# original 'message3,'
message3,,,Nachricht3

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

31.3.6. Optionen für Adapter

Optionen können bei allen Adaptoren verwendet werden. Natürlich sind die Optionen für alle Adaptoren verschieden. Die Optionen können bei Erstellung des Objekts miterstellt werden. Zur Zeit gibt es nur eine Option die für alle Adaptoren verfügbar ist. 'clear' entscheidet 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 bestehenden. Aber das wird immer nur für die aktuelle Sprache gemacht. Alle anderen Sprachen werden nicht verändert.

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

Beispiel 31.6. Benutzen von Übersetzungsoptionen

// Definiere ':' als Trenner für die Quelldatei der Übersetzung
$options = array('separator' => ':');
$translate = new Zend_Translate('csv', 'path/to/mytranslation.csv', 'de', $options);

...

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

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

Tabelle 31.2. Optionen für Übersetzungs-Adapter

Adapter	Option	Standard Wert	Beschreibung
all	clear	false	Wenn true gesetzt wird, werden bereits gelesene Übersetzungen entfernt. Das kann statt dem Erstellen einer neuen Instanz verwendet werden wenn neue Übersetzungsdaten gelesen werden
Csv	separator	;	Definiert welches Zeichen verwendet wird um Quelle und Übersetzung zu trennen

Wenn man selbstdefinierte Optionen haben will, können diese auch in allen Adaptern verwendet werden. Die setOptions() Methode 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. Es muß nur sichergestellt werden das keine bereits existierende Option überschrieben wird welche ein Adapter verwendet.

Um die gesetzte 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 wird, wird nur diese spezielle Option zurückgegeben.

31.3.7. Mit Sprachen arbeiten

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

Die getLocale() Methode 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 setLocale() Methode setzt eine neue Standardsprache für Übersetzungen. Das verhindert das der optionale Sprachparameter der translate() Methode mehr als einmal gesetzt werden muß. Wenn die angegebene Sprache nicht existiert, oder keine Übersetzten Daten für diese Sprache vorhanden sind, wird eine Ausnahme geworfen.

Die isAvaiable() Methode 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 getList() Methode verwendet werden um alle aktuell gesetzten Sprachen für einen Adapter als Array zurückgegeben zu bekommen.

Beispiel 31.7. Handhabung von Sprachen mit Adaptern

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

...
// der optionale Parameter kann wärend der Übersetzung verwendet werden
echo $translate->_("mein_Text", "fr");
// oder es wird eine neue Standardsprache gesetzt
$translate->setLocale("fr");
echo $translate->_("mein_Text");

...
// Prüft ob die Sprache existiert
if ($translate->isAvaiable("fr")) {
    // Sprache existiert
}

31.3.8. Prüfen von Übersetzungen

Normalerweise wird Text ohne irgendwelche Berechnungen übersetzt. Aber manchmal ist es notwendig zu wissen ob ein Text in der Quelle übersetzt ist oder nicht. Hierzu kann die Methode isTranslated() verwendet werden.

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

Beispiel 31.8. Prüfen ob ein Text übersetzbar ist

$english = array('message1' => 'Nachricht 1',
                 'message2' => 'Nachricht 2',
                 'message3' => 'Nachricht 3');
$translate = new Zend_Translate('array', $english, 'de_AT');

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

31.3.9. Zugang zu Quell Daten

Natürlich ist es manchmal nützlich Zugang zu den übersetzten Quelldaten zu erhalten. Hierfür existieren zwei Methoden.

Die getMessageIds() Methode gibt alle bekannten Ids für Übersetzungen als Array zurück.

Und die getMessages() Methode gibt die komplette Übersetzungs-Quelle als Array zurück. Die Ids der Übersetzungen werden als Schlüssel und die Übersetzten Daten als Wert verwendet.

Beispiel 31.9. Handhabung von Quell Daten

...
// gibt alle bekannten Übersetzungs Ids zurück
$messageids = $translate->getMessageIds();
print_r($messageids);

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

Zurück	Nach oben	Weiter
31.2. Adapter für Zend_Translate	Zum Anfang	Kapitel 32. Zend_Uri