Differences

This shows you the differences between two versions of the page.

--- en:dev:284:translate [16.05.2015 11:47] – created Manuela v.d.Decken
+++ en:dev:284:translate [18.07.2018 12:46] (current) – [Translations before 2.8.4] Manuela v.d.Decken
@@ Line 1: / Line 1: @@
-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.
-====== Zentrale Verwaltung der Übersetzungen ======
+The days when adventurous constructs like the following had to be integrated in addons clearly belong to the past<PHP>
-**Translate** ist ein Paket aus mehreren Klassen, das ab WB-2.8.4 bereits weitgehend das komplette Handling der bisher als 'Sprachdateien' bekannten Übersetzungen übernimmt.
-Die Zeiten, als in Addons die Übersetzungen noch mit solchen und ähnlichen, abenteuerlichen Konstrukten 'eingebaut' werden mussten, sind damit eindeutig Vergangenheit.<PHP>
 // Load Language file
 if(LANGUAGE_LOADED) {
@@ Line 12: / Line 10: @@
     }
 }
-</PHP>Ab jetzt genügt ein einfaches: <php>$oTrans->enableAddon('modules\\droplets');</php>
+</PHP>From now on only a statement like: <php>$oTrans->enableAddon('modules\\droplets');</php>
-und schon ist alles erledigt.
+is needed, and you are done.
-Wenn jetzt die berechtigte Frage kommt: 'was ist dann alles erledigt?', dann einfach weiterlesen.
+If you now pose the legitimate question: 'is that all?', then simply read on.
-===== Allgemeiner Aufbau der Übersetzungs-Struktur =====
+===== General structure of the translation mechanism =====
-==== Allgemein ====
+==== General ====
-Der Einfachheit halber rede ich hier immer nur von 'Sprachdateien'. Real müssen die Übersetzungen jedoch nicht mehr zwingend in PHP-Dateien als Arrays definiert werden. Es ist jetzt jedes denkbare, geeignete Dateiformat möglich. Die Daten müssen nicht einmal auf dem selben Server liegen. Auch könnten die Daten durch einen WebService zur Verfügung gestellt oder in einer Datenbank abgelegt werden. Dazu ist einzig und allein jeweils ein kleiner, spezialisierter Treiber nötig, der jederzeit, auch temporär sogar für ein einzelnes Addon oder Template, eingebunden werden kann.
+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 ====
+==== Translations before 2.10.0 ====
-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.;-))//\\
+Let's start at the current level at the beginning of 2.10.0 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. ;-))//\\
+=== Aufbau der Sprachdateien (EN.php) ===
+<PHP>
+//Modul Description
+$module_description = 'Enter here a really short description of your module. About 200-250 characters should suffice.';
-==== Das Grundsystem hinter Translate ====
+$MOD_MyModule['PRINT']                       = 'Please print this page, if a copy is desired for your records.';
-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.\\
+$MOD_MyModule['LOAD_LAYOUT']                 = 'Load Default Layout';
-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.\\
+$MOD_MyModule['TEXT_GUEST']                  = 'Guest';
-Was sollen Sprachdateien in Templates?? \\
+$MOD_MyModule['TEXT_UNKNOWN']                = 'unknown';
-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.
+$MOD_MyModule['TEXT_PRINT_PAGE']             = 'Print page';
+$MOD_MyModule['MESSAGE_ARCHIVE_DELETED']     = 'Zip(s) deleted successfully.';
+$MOD_MyModule['MESSAGE_ARCHIVE_NOT_DELETED'] = 'Cannot delete the selected Zip(s).';
+</PHP>
+somebody wrote this kind of entries:
+<PHP>
+$MOD_MyModule['PRINT']                       = 'Please print this page, if a copy is desired for your records.';
+$MOD_MyModule_TEXT['GUEST']                  = 'Guest';
+$MOD_MyModule_MESSAGE['ARCHIVE_DELETED']     = 'Zip(s) deleted successfully.';
+</PHP>
+It does not look that good, but it works. Both syntax lead to the same Translate keys.
+<PHP>
+echo $oTrans->MOD_MyModule_PRINT;
+echo $oTrans->MOD_MyModule_LOAD_LAYOUT;
+echo $oTrans->MOD_MyModule_TEXT_GUEST;
+echo $oTrans->MOD_MyModule_TEXT_UNKNOWN;
+echo $oTrans->MOD_MyModule_TEXT_PRINT_PAGE;
+echo $oTrans->MOD_MyModule_MESSAGE_ARCHIVE_DELETED;
+echo $oTrans->MOD_MyModule_MESSAGE_ARCHIVE_NOT_DELETED;
+</PHP>
-==== Struktur der Translation Tabellen ====
-{{:dev:284:translate:sprachcountrycodes-de.gif?nolink |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.
+==== 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.
-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 [[http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes|ISO 639-1]] genügen längst nicht mehr um wenigstens die meisten Sprachen mit deren wichtigsten, regionalen Abwandlungen zu definieren. Die Nutzung von [[http://en.wikipedia.org/wiki/IETF_language_tag|IETF language tag]] nach [[http://tools.ietf.org/html/rfc5646|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//.\\
+==== Structure of translation tables ====
-{{ :dev:284:translate:translatemixing.gif?nolink|}}
-//**Translate**// selbst berücksichtigt derzeit folgende Tags:
-  * //**primary language subtag**// basierend auf [[http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes|ISO-639-1/639-2T/639-3]]
-  * //**region subtag**// basierend auf [[http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2|ISO 3166-1 alpha-2]]. Die 3-Digit-Codes nach [[http://en.wikipedia.org/wiki/UN_M.49|UN_M.49]] werden derzeit **nicht** unterstützt.
-  * //**variant subtags**// auszugsweise basierend auf der [[http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry|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? ====
+{{:dev:284:translate:sprachcountrycodes-de.gif?nolink |Sprachauswahl im FireFox}}
-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:\\
+//**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.
-<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:\\
+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 [[http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes|ISO 639-1]] no longer satisfy at least the most languages with their major, regional to define variations. The use of [[http://en.wikipedia.org/wiki/IETF_language_tag|IETF language tag]] according to [[http://tools.ietf.org/html/rfc5646|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//.\\
-<php> $template->set_var(Translate::getInstance()->getLangArray()); </php> eingebunden werden die Texte im Template mit ''{TEXT_CANCEL}''.
+{{ :dev:284:translate:translatemixing.png?nolink|}}
-Das Problem bei dieser Methode ist, dass immer eine komplette Kopie der Übersetzungstabelle an die Templateengine übergeben wird.
+//**Translate**// itself currently includes the following tags:
+  * //**Primary language subtag**// based on [[http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes|ISO-639-1/639-2T/639-3]]
+  * //**Region subtag**// based on [[http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2|ISO 3166-1 alpha-2]]. The 3-digit codes for [[http://en.wikipedia.org/wiki/UN_M.49|UN_M.49]] are currently **not** supported.
+  * //**Variant subtags**// in part based on the [[http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry|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 is indeed Chinese in China and which in turn contains Mandarin or Cantonese, Singapore etc ... This linguistic diversity is essentially more common than one can imagine at first glance.
+==== How does Translate process this information now? ====
+The complete structure of Translate is based on complex translation tables which are each responsible for the core, a module or template. The basic structure is based on the 3 language settings and the fallback mechanism specified by WebsiteBaker: \\
+  - The system language (SYSTEM_LANGUAGE). This is the language of the system, which is the basis on which usually all programmed is done. As a rule, simply English **[en]**.
+  - The default language (DEFAULT_LANGUAGE) is selected during installation. For a German website would choose German **[de]** or **[de-de]**.
+  - The user language (USER_LANGUAGE) that the individual visitor to the website chooses.
+Now, an auxiliary table is set up for each language setting, each in turn mixed together from up to 3 language files, which specifies the language code. This 3 auxiliary tables are then mapped together in the order System->Default->User to obtain the actual translation table (in fact it's a bit more complex to save time and memory), which is then also automatically cached. So the next call to the same language setting eliminates all the above-described procedure and just the final table is loaded from the cache. \\
+Exactly as just described for the central translation table, it also happens the same way for each individual module and its template which ships with language files and actually loads and uses them.
-Wesentlich einfacher und platzsparender ist die Verwendung in Verbindung mit Twig, da hier nur eine speichersparende Referenz auf das Translateobjekt übergeben wird:\\
+==== How to use Translate ====
-<php> $aTwigData['Trans'] = Translate::getInstance(); </php> die Anzeige im Template erfolgt durch ''%%{{ Trans.TEXT_CANCEL }}%%''
+For Addon developers Translate is very easy to use. The basic initialization is done automatically **always** from Core and therefore Addons don't have to care at all about this mechanism. In older addons that contain PHP files that need to be called directly from the outside, 2 to a maximum of 4 Translate methods need to be called (all commands are given in the form of standalone). Condition for the use of Translate is that the file ''framework/initialize.php'' has been loaded (included) already:
+  * <php>Translate::getInstance()->enableAddon('modules\\MyAddon');</php> This command is used at the very beginning of the file being accessed. Thus possibly existing language files of this addon are enabled. In case another addon is already enabled, it will be deactivated first.
+  * <php>Translate::getInstance()->enableAddonTemplate('NameOfTemplate');</php> This command activates when needed existing language files of an associated template. If no 'NameOfTemplate' is specified, it looks for the template globally set. If this is not found, a fallback to the default template is used.
+  * <php>Translate::getInstance()->enableAddonTheme('NameOfTheme');</php> This command if necessary enables existing language files of an associated theme. If no 'NameOfTheme' is specified, it looks for the theme globally set. If this is not found, a fallback to the default theme is used.
+  * <php>Translate::getInstance()->disableAddon();</php> With this command the active addon together with its theme and/or template are disconnected again from Translate.
+Even simpler with add-on files that are called Core-controlled: Here the addon is already activated from the Core. Only the template and/or the theme must still be activated by the addon itself. The deactivation is performed automatically by the core.
+Now basically the only thing left is actually to call the translated texts by Translate. The easiest way is: \\
+<php> $sText = Translate::getInstance()->TEXT_CANCEL; </php>  (corresponds to the former <php> $sText = $GLOBALS['TEXT']['CANCEL']; </php>)
+Temporarily for older Addons a method exists that allows to pass all translation texts in one rushto the //**phplib**// Template Engine:\\
+<php> $template->set_var(Translate::getInstance()->getLangArray()); </php> in the template the texts are inserted with ''{TEXT_CANCEL}''.
+The problem with this method is that always a complete copy of the translation table is passed to the Template Engine.
+Much easier and less space is used in conjunction with Twig, since only a memory-saving reference is passed to the Translate object:\\
+<php> $aTwigData['Trans'] = Translate::getInstance(); </php> - in order to display it in the template use ''%%{{ Trans.TEXT_CANCEL }}%%''

WebsiteBaker Documentation

User Tools

Site Tools

Differences

Page Tools