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. ==== Translations before 2.8.4 ==== Let's start at the current level at the beginning of 2.8.4 and earlier. In the central language directory of the core, there are a large number of language files (DE.php | EN.php | etc.). Each of these files contains an overwhelmingly large number of language variables (specifically, currently about 600 !!). The used system requires that in each language file, each entry is present. Missing one often ends up in a runtime error. Once WebsiteBaker starts, one of these language files will be loaded with its full 600 entries forcibly. completely independent of whether even one of them is required! Of course, different addons then load their own language files still additionally. Having several different addons on one page even a very considerable number can also come together.
(From historical times, the translation of many ancient modules are included and a real care of the files, with a reasonable time / effort is virtually impossible. Whoever says otherwise, must be happy from now on take care of these fossil files. )
==== The basic system behind Translate ==== Translate is based on the premise that language files generally contain only the necessary items for each area. In return, a relatively large number of small language files is used. Each addon, each ACP extension must and even each individual template / theme can bring their own language files.
This division simplifies the work of a developer. He no longer has to find 'halfway matching' entries already there in the central file and to add any new entries, which must then be maintained / translated into ~ 25 different languages. As an absolute minimum requirement, it is completely sufficient, that an addon-specific file in the system language 'english' is shaped, that contains all the text of an addon, except for the central texts.
What are language files good for in templates ??
All language files are 'output Global'. This means that these texts are generally issued the same in all selected templates / themes. If a template for example has space for relatively short texts only, so that's no longer a problem. There are just the adapted texts taken with identical keys in the language file of the template - and the lyrics are especially adapted to this template. All other templates as usual get the global texts. ==== Structure of translation tables ==== Translate works internally with several translation tables (TranslationTable). Each of these tables is made up of a maximum of 9!! different language files. That sounds at first a bit 'oversized', but it's not so bad, because first, the resulting translation table will be never greater than the largest file loaded due to the technology used, and secondly, by the built-in caching mechanism, the translation tables need to be rebuilt only after changes to the language files. When you look at the table on the left (Extract from the Language support of Firefox), you can already see various Chinese, several German and English language in several dialects. The previously used, simple 2-letter codes purely following ISO 639-1 no longer satisfy at least the most languages with their major, regional to define variations. The use of IETF language tag according to RFC 5646 has therefore in the meantime become to an established standard. Translate supports at least the major part of the IETF tags. Not supported are currently the optional script subtags, extension subtags, and the private-use subtag.
Translate itself currently includes the following tags: * Primary language subtag based on ISO-639-1/639-2T/639-3 * Region subtag based on ISO 3166-1 alpha-2. The 3-digit codes for UN_M.49 are currently not supported. * Variant subtags in part based on the IANA language-subtag-registry. Here 2-8 characters are allowed, in addition, one or more hyphens can be contained.
With this system, almost all languages and language variations occurring in the world can be mapped. In the full IETF tags still stood far more information, including the used character set (script). We have restricted ourselves here deliberately only to the actual language code plus the regional allocation. The Variant tag is used for the definition of slightly modified differences of language in the same country. For example, There are indeed Chinese in China and which in turn contains Mandarin or Cantonese, Singapore etc … This linguistic diversity is essential common than one can imagine at first glance. ==== 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 }}