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

$translation->setLanguage('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 druch 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.

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

$options = array('clear' => true);
$translate = new Zend_Translate('csv', 'path/to/mytranslation.csv', 'de');
$translate->addTranslation('path/to/other.csv', 'fr');
... // mach was
$translate->addTranslation('path/to/new.csv', 'fr', $options); // löschen der Sprache fr, neue Übersetzungen benutzen

31.3.7. Checking for translations

Normally text will be translated without any computations. But sometimes it is necessary to know if a text is translated or not within the source. Therefor the isTranslated() method can be used.

isTranslated($messageId, $original = false, $locale = null) takes as first parameter the text from which you want to know if it can be translated. And as optional third parameter the locale for which you want to know the translation. The optional second parameter declares if translation is fix to the declared language or a lower set of translations can be used. If you have a text which can be translated by 'en' but not for 'en_US' you will normally get the translation returned, but by setting $original to true, the isTranslated() method will return false in such cases.

Beispiel 31.7. Checking if a text is translateable

$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' can be translated";
}
if (!($translate->isTranslated('message1', true, 'de'))) {
    print "'message1' can not be translated in 'de' as it's only avaiable in 'de_AT'";
}
if ($translate->isTranslated('message1', false, 'de')) {
    print "'message1' can be translated in 'de_AT' falls back to 'de'";
}

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