User Tools

Site Tools


en:dev:284:translate

This is an old revision of the document!


FIXME This page is not fully translated, yet. Please help completing the translation.
(remove this paragraph once the translation is finished)

Centralized management of translations

Translate is a package consisting of several classes, that already in WB 2.8.4 take care about all the handling of translations known as 'language files' up to now. The days when adventurous constructs like the following had to be integrated in addons clearly belong to the past<PHP> Load Language file if(LANGUAGE_LOADED) { if(!file_exists(WB_PATH.'/modules/droplets/languages/'.LANGUAGE.'.php')) { require_once(WB_PATH.'/modules/droplets/languages/EN.php'); } else { require_once(WB_PATH.'/modules/droplets/languages/'.LANGUAGE.'.php'); } } </PHP>From now on only a statement like: <php>$oTrans→enableAddon('modules\\droplets');</php> is needed, and you are done. If you now pose the legitimate question: 'is that all?', then simply read on. ===== General structure of the translation mechanism ===== ==== General ==== For simplicity, I'm talking only about 'language files' here. However, in real case usage the translations no longer have to be defined necessarily as arrays in PHP files. Any conceivable suitable file format is possible now. The data don't not even have to be on the same server. The data could be provided by a web service, or stored in a database. For such use cases only a small, specialized driver is necessary, which can be loaded any time, even temporarily even for a single addon or template involved. ==== Übersetzungen vor 2.8.4 ==== Fangen wir beim aktuellen Stand zu Beginn der 2.8.4 und zuvor an. Im zentralen Sprachverzeichnis des Core existieren eine große Anzahl von Sprachdateien (DE.php | EN.php | usw.). Jede dieser Dateien enthält eine schier unüberschaubare Anzahl von Sprachvariablen (genauer gesagt, derzeit etwas über 600!!). Das benutzte System erfordert, dass in jeder Sprachdatei jeder Eintrag vorhanden ist. Fehlt einer, löst das im Benutzungsfall häufig einen Laufzeitfehler aus. Sobald WebsiteBaker startet, wird zwangsweise eine dieser Sprachdateien mit ihren vollen 600 Einträgen geladen. völlig unabhängig davon, ob auch nur ein einziger davon benötigt wird! Selbstverständlich laden dann verschiedene Addons ihre eigenen Sprachdateien noch zusätzlich dazu. Bei mehreren verschiedenen Addons auf einer Seite kann da zusätzlich noch eine ganz erkleckliche Anzahl zusammenkommen.
(Aus historischen Zeiten sind da auch die Übersetzungen von sehr vielen uralten Modulen enthalten und eine wirkliche Pflege der Dateien ist, mit vernünftigem Zeit-/Arbeitsaufwand praktisch unmöglich. Wer was anderes behauptet, darf gerne ab sofort die Pflege dieser fossilen Dateien übernehmen.;-))
==== Das Grundsystem hinter Translate ==== Translate basiert auf der Vorgabe, dass Sprachdateien grundsätzlich jeweils nur die für den jeweiligen Bereich notwendigen Einträge enthalten. Im Gegenzug werden relativ viele, kleine Sprachdateien eingesetzt. Jedes Addon, jede ACP-Erweiterung muss und sogar jedes einzelne Template/Theme kann seine eigenen Sprachdateien mitbringen.
Diese Aufteilung vereinfacht die Arbeit eines Entwicklers. Er muss nicht mehr 'halbwegs passende' Einträge in der zentralen Datei suchen und dort schon gar keine neuen Einträge hinzufügen, die dann in ~25 verschiedenen Sprachen gepflegt/übersetzt werden müssen. Als absolute Mindestanforderung genügt es völlig, eine Addon-spezifische Datei in der Systemsprache '
englisch' mitzuliefern, die alle Texte eines Addons, abzüglich der zentralen Texte enthält.
Was sollen Sprachdateien in Templates??
Alle Sprachdateien sind 'Ausgabe-Global'. Das bedeutet, dass diese Texte grundsätzlich in allen ausgewählten Templates/Themes identisch ausgegeben werden. Hat jetzt ein Template z.B. nur Platz für relativ kurze Texte so ist das kein Problem mehr. Es werden einfach die angepassten Texte mit identischem Schlüssel in die Sprachdatei des Templates aufgenommen - Und schon sind die Texte speziell auf dieses Template angepasst. Alle anderen Templates bekommen wie gewohnt die globalen Texte. ==== Struktur der Translation Tabellen ==== Sprachauswahl im FireFox
Translate arbeitet intern mit mehreren Übersetzungstabellen (TranslationTable). Jede dieser Tabellen setzt sich aus einer bis maximal 9!! verschiedenen Sprachdateien zusammen. Das hört sich zwar im ersten Moment etwas 'oversized' an, ist aber halb so wild, da durch die eingesetzte Technik die resultierend Übersetzungstabelle erstens nie größer sein wird, als die größte der geladenen Einzeldateien und zweitens durch das eingebaute Caching die Übersetzungstabellen nur nach Änderungen an den Sprachdateien neu aufgebaut werden müssen. Wenn man sich die Tabelle links (Auszug aus der Sprachauswahl des FireFox) anschaut, erkennt man bereits verschiedene chinesische, mehrere deutsche und noch mehr verschiedene englische Sprachweisen. Die bisher genutzten, simplen 2-Buchstaben-Codes rein nach ISO 639-1 genügen längst nicht mehr um wenigstens die meisten Sprachen mit deren wichtigsten, regionalen Abwandlungen zu definieren. Die Nutzung von IETF language tag nach RFC 5646 ist daher zwischenzeitlich längst Standard. Translate unterstützt zumindest den wichtigsten Teil der IETF-Tags. Nicht unterstützt werden derzeit die optionalen script subtags, extension subtags und der private-use subtag.
Translate selbst berücksichtigt derzeit folgende Tags: * primary language subtag basierend auf ISO-639-1/639-2T/639-3 * region subtag basierend auf ISO 3166-1 alpha-2. Die 3-Digit-Codes nach UN_M.49 werden derzeit nicht unterstützt. * variant subtags auszugsweise basierend auf der IANA language-subtag-registry. Hier sind 2-8 Zeichen erlaubt, wobei zusätzlich noch ein oder mehrere Bindestriche enthalten sein können. Mit diesem System können fast alle auf der Erde vorkommenden Sprachen und Sprachvariationen abgebildet werden. In den vollständigen IETF-Tags stünden noch weit mehr Informationen, bis hin zum verwendeten Zeichensatz(Script). Wir haben uns hier bewusst nur an den eigentlichen Sprachcode plus die Regionalzuweisung gehalten. Der Variant-Tag wird leicht modifiziert zur Definition von Unterschieden einer Sprache im selben Land genutzt. Z.B. gibt es ja chinesisch in China und davon dann wiederum Mandarin oder Cantonesisch, Singapur etc… Diese Sprachvielfalt kommt wesentlich häufiger vor, als man sich im ersten Augenblick vorzustellen vermag. ==== Wie verarbeitet Translate jetzt diese Informationen? ==== Die komplette Struktur von Translate basiert auf komplexen Übersetzungstabellen die jeweils für den Core, ein Modul oder ein Template zuständig sind. Der Grundstruktur basiert auf den 3 Spracheinstellungen und dem FallBack-Mechanismus, den WebsiteBaker vorgibt:
- die Systemsprache (SYSTEM_LANGUAGE). Das ist die Sprache des Systems, auf deren Basis grundsätzlich programmiert wird. In der Regel einfaches Englisch [en]. - die Default-Sprache (DEFAULT_LANGUAGE), wird bei der Installation ausgewählt. Eine deutsche Website wird da deutsch [de] oder [de-de] wählen. - die Benutzersprache (USER_LANGUAGE), die sich der einzelne Besucher der Website aussucht. Für jede Spracheinstellung wird jetzt eine Hilfstabelle aufgebaut, die sich jeweils wiederum aus bis zu 3 Sprachdateien zusammengemischt, die der Sprachcode vorgibt. Diese 3 Hilfstabellen werden nur in der Reihenfolge System→Default→User zu der eigentlichen Übersetzungstabelle zusammengemischt (in real etwas komplexer um Zeit und Speicher zu sparen), die dann auch automatisch gecacht wird. Beim nächsten Aufruf mit der selben Spracheinstellung entfällt also das ganze vorbeschriebene Prozedere und es wird einfach nur die fertige Tabelle aus dem Cache geladen.
So wie das jetzt für die zentrale Übersetzungstabelle beschrieben ist, exakt genau so geschieht es auch für jedes einzelne Modul und dessen Template, das Sprachdateien mitliefert und das auch tatsächlich geladen und benutzt wird. ==== Wie wird Translate benutzt? ==== Für Addon-Entwickler ist Translate sehr einfach einzusetzen. Die Grundinitialisierung wird immer automatisch vom Core vorgenommen und Addons haben damit überhaupt nichts zu schaffen. Bei älteren Addons, die noch PHP-Dateien enthalten, die direkt von außen aufgerufen werden müssen, sind 2 bis maximal 4 Translate-Methoden erforderlich (alle Kommandos werden in der Standalone-Form angegeben). Bedingung für den Einsatz von Translate ist, dass die Datei framework/initialize.php bereits geladen (included) ist: * <php>Translate::getInstance()→enableAddon('modules\\MeinAddon');</php> Dieser Befehl wird gleich zu Beginn einer aufgerufenen Datei eingesetzt. Dadurch werden eventuell vorhandene Sprachdateien dieses Addons aktiviert. Sollte noch ein anderes Addon aktiviert sein, wird dieses zuerst deaktiviert. * <php>Translate::getInstance()→enableAddonTemplate('NameDesTemplates');</php> Dieser Befehl aktiviert bei Bedarf vorhandene Sprachdateien eines zugehörigen Templates. Wird kein 'NameDesTemplates' angegeben, wird nach dem allgemein eingestellten Template gesucht. Wird das nicht gefunden, erfolgt ein Fallback auf das Default-Template. * <php>Translate::getInstance()→enableAddonTheme('NameDesThemes');</php> Dieser Befehl aktiviert bei Bedarf vorhandene Sprachdateien eines zugehörigen Themes. Wird kein 'NameDesThemes' angegeben, wird nach dem allgemein eingestellten Theme gesucht. Wird das nicht gefunden, erfolgt ein Fallback auf das Default-Theme. * <php>Translate::getInstance()→disableAddon();</php> Mit diesem Kommando wird das aktive Addon mitsamt seinem Theme und/oder Template wieder von Translate getrennt. Einfacher noch geht es bei Addon-Dateien, die Core-gesteuert aufgerufen werden: Hier wird das Addon bereits vom Core aktiviert. Einzig das Template und/oder das Theme müssen derzeit noch vom Addon selbst aktiviert werden. Auch die Deaktivierung erfolgt automatisch durch den Core. Jetzt müssen eigentlich nur noch die Übersetzungstexte von Translate abgerufen werden. Der einfachste Weg ist:
<php> $sText = Translate::getInstance()→TEXT_CANCEL; </php> (entspricht dem früheren <php> $sText = $GLOBALS['TEXT']['CANCEL']; </php>) Für ältere Addons existiert vorübergehend eine Methode, sämtliche Übersetzungstexte in einem Zug an die
phplib Templateengine zu übergeben:
<php> $template→set_var(Translate::getInstance()→getLangArray()); </php> eingebunden werden die Texte im Template mit {TEXT_CANCEL}. Das Problem bei dieser Methode ist, dass immer eine komplette Kopie der Übersetzungstabelle an die Templateengine übergeben wird. Wesentlich einfacher und platzsparender ist die Verwendung in Verbindung mit Twig, da hier nur eine speichersparende Referenz auf das Translateobjekt übergeben wird:
<php> $aTwigData['Trans'] = Translate::getInstance(); </php> die Anzeige im Template erfolgt durch {{ Trans.TEXT_CANCEL }}

en/dev/284/translate.1439498495.txt.gz · Last modified: 13.08.2015 20:41 by mrbaseman