Einführung

Einführung – Die Verwendung von Translation2

Was ist Translation2?

Translation2 ist eine Klasse um mehrsprachige Anwendungen zu schreiben. Es bietet einfache Möglichkeiten um alle Zeichenketten für eine mehrsprachige Webseite oder Anwendung aus eine Datenquelle zu holen, wie z.B. einer Datenbank. Die API einfach zu verwenden und trotzdem machtig und erweiterbar. Die Klasse Translation2_Admin bietet Methoden, um Übersetzungen zu verwalten, wie das Hinzufügen/Entfernen einer Sprache oder Zeichenkette.

Die folgenden Container (Datenquellen-Treiber) werden unterstützt:

  • PEAR::DB

  • PEAR::MDB

  • PEAR::MDB2

  • gettext

  • PEAR::DB_DataObject (experimentell, wird benutzt von PEAR:: HTML_Template_Flexy)

  • XML

Einige Decorator-Klassen sind hilfreiche für bestimmte Situationen. Sie können in beliebiger Reihenfolge aufgeschichtet werden. Dadurch werden sie einer Vielzahl von Ansprüchen gerecht. Derzeit sind folgende Decorator-Klassen enthalten:

  • CacheLiteFunction (Für schnelles, datei-basiertes Caching)

  • CacheMemory (Für speicher-basiertes Caching)

  • DefaultText (Um leere Zeichenketten durch ihren Schlüssel oder Standardtext zu ersetzen)

  • ErrorText (Um leere Zeichenketten mit der "error_text"-Medlung zu ersetzen)

  • Iconv (Um zwischen verschiedenen Zeichensatz-Encodings zu wechseln)

  • Lang (Die Definition von Fallback-Sprachen, wenn Zeichenketten in Übersetzungen nicht zur Verfügung stehen)

  • SpecialChars (Ersetzt HTML-Entitäten durch ihre hexadezimale Darstellung)

  • UTF-8 (Konvertiert Zeichenketten von UTF-8 nach ISO-8859-1)

Beispiel

Dieses Beispiel zeigt die Erzeugung eines Translation2 Objekte und demonstriert die Ermittlung übersetzter Zeichenketten bei der Verwendung des MDB2-Treibers:

<?php
// Die Parameter für die Datenbankverbindung
$dbinfo = array(
    
'hostspec' => 'host',
    
'database' => 'dbname',
    
'phptype'  => 'mysql',
    
'username' => 'user',
    
'password' => 'pwd'
);

define('TABLE_PREFIX''mytable_');

// Translation2 muss über die eigene DB-Struktur
// informatiert werden
// Anmerkung: die Standardstruktur ist:
//
// Tabelle "langs"
// (verfügbare Sprachen und Meta-Informationen)
// +----+------+------+----------+------------+
// | ID | name | meta | encoding | error_text |
// +----+------+------+----------+------------+
//
// Table "strings" (Übersetzungen)
// +----+---------+----+----+----+-----+
// | ID | page_id | en | de | it | ... |
// +----+---------+----+----+----+-----+
// Man kann eine Tabelle pro Übersetzung verwenden, statt
// einer Tabelle für alle
//
$params = array(
    
'langs_avail_table' => TABLE_PREFIX.'langs_avail',
    
'lang_id_col'     => 'ID',
    
'lang_name_col'   => 'name',
    
'lang_meta_col'   => 'meta',
    
'lang_errmsg_col' => 'error_text',
    
'strings_tables'  => array(
                            
'en' => TABLE_PREFIX.'i18n',
                            
'it' => TABLE_PREFIX.'i18n',
                            
'de' => TABLE_PREFIX.'i18n'
                         
),
    
'string_id_col'      => 'ID',
    
'string_page_id_col' => 'pageID',
    
'string_text_col'    => '%s'  //'%s' wird durch den Sprachcode ersetzt
);

$driver 'MDB2';

require_once 
'Translation2.php';
$tr =& Translation2::factory($driver$dbinfo$params);

// Prüfen Sie Rückgabewerte auf Fehler
// In diesen Beispielen verzichten wir daruf
// um sie übersichtlicher zu halten
if (PEAR::isError($tr)) {
    
// Fehler behandeln
}

// die primäre Sprache setzen
$tr->setLang('it');

// die Gruppe von Zeichenkette bestimmen, die geholt werden soll
$tr->setPageID('defaultGroup');

// einen Lang-Decorator setzen für die Fallback-Sprache
$tr =& $tr->getDecorator('Lang');
$tr->setOption('fallbackLang''en');

// Einen weiteren Lang-Decorator für eine zweite Fallback-Sprache
// Für den Fall das Zeichenketten weder in Italienisch noch Englisch vorliegen
$tr =& $tr->getDecorator('Lang');
$tr->setOption('fallbackLang''de');

// Die Zeichenkette mit der stringID 'test' holen
echo $tr->get('test');

// Eine Zeichnekette holen, die nicht in Italienisch vorliegt
// (Test auf Fallback ins Englische
echo $tr->get('only_english');

// Die komplette Gruppe holen, ohne die Fallback-Funktion zu nutzen
// und ohne weitere Decorator-Klassen zu durchlaufen
$rawPage $tr->getRawPage();
print_r($rawPage);

// Die komplette Gruppe mit Berücksichtung der Decorator
$page $tr->getPage();
print_r($page);

// Eine Sprache erzwingen
echo $tr->get('month_01''calendar''it');

// Analog für getRawPage() und getPage()
$page $tr->getPage('calendar''de');
print_r($page);
?>

Wie man sehen kann, sind die wichtigsten Methoden get(), getPage() und getRawPage(). Di evollständige Syntax ist

<?php
get
($stringID$pageID$langID);
?>

aber man kann auf die Parameter pageID und langId verzichten, wenn sie vorher gesetzt wurden.

Anmerkung: Es muss eine Fehlerprüfung zumindest beim ersten Aufruf einer dieser Methoden vorgenommen werden. Denn an diesen Punkt wird zum erstenmal die Datenbankverbindung aufgebaut. Daher ist hier das Fehlerrisiko am größten.

Sprachinformationen ermitteln

Jetzt schauen wir uns an, wie Meta-Informationen aus der Datenbank ermittelt werden können:

<?php
$tr
->getLang();     // keine langID => aktuelle Sprache
$tr->getLang('it'); // wie oben, aber jetzt Italienische langID

// Der erste Parameter ist der Sprach-Identifier,
// der zweite bestimmt die gewünschte Information
$tr->getLang('it''error_text');
$tr->getLang('en''name');
$tr->getLang('de''meta');
$tr->getLang('de''encoding');
?>

Die Verendung der Decoratorklassen

Translation2 benutzt Decoratorklassen um Zeichenketten zu filtern bzw. zu beeinflussen. Es kann eine Reihe von Filtern aufgebaut und auch um Eigene ergänzt werden.

<?php
$tr 
=& Translation2::factory($driver$dbinfo$params);
$tr->setLang('en');
$tr->setPageID('calendar');

// Einen speicher-basierten Cache-Decorator ergänzen
// um bestimmte Informationen vorzuladen und die DB-Zugriffe
// zu minimieren
$tr = & $tr->getDecorator('CacheMemory');

// Einen datei-basierten Decorator laden
// um die Seitenzugriffe zu chachen
$tr =& $tr->getDecorator('CacheLiteFunction');
$tr->setOption('cacheDir''cache/');
$tr->setOption('lifeTime'3600*24);

// Einen Sprach-Decorator ergänzen
$tr = & $tr->getDecorator('Lang');
$tr->setOption('fallbackLang''it');

// Einen Decorator ergänzen, um Sonderzeichen durch HTML-Entitäten zu ersetzen
$tr = & $tr->getDecorator('SpecialChars');
// Den Zeichensatz festlegen
$tr->setOption('charset''ISO-8859-2');

// Und einen UTF-8-Decorator ergänzen, um UTF-8-Zeichenketten zu ändern
$tr = & $tr->getDecorator('UTF8');

// Einen Decorator für den Standardtext ersetzen, wenn
// eine leere Zeichenkette gefunden wurde
$tr = & $tr->getDecorator('DefaultText');
// Ersetze die leere Zeichenkette mit seiner stringID
echo $tr->get('emptyString');
// einen bestimmten Fallback-Text setzen
echo $tr->get('emptyString''stringGroup''en''show this default text');
?>

Den Identifier einer Zeichenkette ermitteln

Die Methode getStringID() ist die Umkehrung von get(). Wenn eine Zeichenkette in eine andere Sprache übersetzt werden soll, ist es nicht erforderlich den zugehörigen Identifier (stringID ) zu kennen, stattdessen kann man diese Methode benutzen:

<?php
$tr
->setLang('it');

// Übersetze die italienische Zeichenkette "gennaio"  ins englische "january"
$stringID $tr->getStringID('gennaio''calendar');
echo 
$translatedString $tr->get($stringID'calendar''en');
?>

Parameter-Ersetzung

Translation2 kann mit parameterisierten Zeichneketten umgehen und Parameter zur Laufzeit ersetzen. Dazu können assoziative oder numerische Arrays benutzt werden.

<?php
// "hello_user" = "hello &&user&&, today is &&weekday&&, &&day&&th &&month&& &&year&&"

$tr->setParams(array(
    
0         => '',
    
'user'    => 'Joe',
    
'day'     => '15',
    
'month'   => $tr->get('month_01''calendar''en'),
    
'year'    => '2004',
    
'weekday' => $tr->get('day_5''calendar''en')
));

echo 
$tr->get('hello_user');
// Diese Zeile wird ausgeben: "hello Joe, today is Friday, 15th January 2004"
?>

Die Übersetzungen für mehrere "Seiten" erhalten

Wenn ihre Seite in Sektionen unterteilt ist, wie z.B. ein Seitenkopf, Inhalt und Seitenfuß, können Sie diese "Seiten" oder Gruppen von Übersetzungen nacheinander holen:

<?php
$header_trans 
$tr->getPage('header');
$body_trans   $tr->getPage('body');
$footer_trans $tr->getPage('footer');
?>

Wenn Sie diese über ein einzelnes Array abrufen möchten, verwenden Sie einfach die array_merge()-Funktion

<?php
$translations 
array_merge(
$tr->getPage('header'),
$tr->getPage('body'),
$tr->getPage('footer')
);
?>

Translation2 class (Previous) Usage of Translation2_Admin (Next)
Last updated: Sun, 19 Dec 2010 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

There are no user contributed notes for this page.