| Next revision | Previous revision |
| en:entwickler:mehrsprachigkeit [2015/11/04 16:40] – created thomas-rcv | en:entwickler:mehrsprachigkeit [2018/06/17 07:47] (current) – [Using in source code] fasse |
|---|
| ====== Multilingualism ====== | ====== Multilingualism ====== |
| With version 2.2 Admidio supports multiple languages. For this purpose, all the texts were stored in an XML file in **adm_program/languages** with the respective language abbreviations as the filename. The language can be selected in the **Organization Settings**. | With version 2.2 Admidio supports multiple languages. For this purpose, all the texts were stored in an XML file in **adm_program/languages** with the respective language abbreviations as the filename. The language can be selected in the **Organization Settings** within the **Regional settings** area. |
| |
| ==== Using in source code ==== | ==== Using in source code ==== |
| In the **common.php** a global object **gL10n** of the Class **Language** is applied, which is derived of the PHP class [[http://de3.php.net/manual/de/class .simplexmlelement.php | SimpleXMLElement]]. This object reads the XML file. About the method **get ($ text_id, $ var1 = "", $ var2 = "")** the search text can be handed over with the ID. It returns then the text in the set language respectively. Does the text have placeholders (% VAR1%, % VAR2% ...), so this can be passed as additional parameters. | In the **common.php** a global object **gL10n** of the Class **Language** is applied, which is derived of the PHP class [[https://secure.php.net/manual/en/class.simplexmlelement.php|SimpleXMLElement]]. This object reads the XML file. About the method **get($textId, $params = array())** the search text can be handed over with the ID. It returns then the text in the set language respectively. Does the text have placeholders (#VAR1#, #VAR2# ...), so this can be passed as additional parameters. |
| |
| Example: | Example: |
| <code php>// the following call returns in German "Anlegen" and in English "Create" back | <code php>// the following call returns in German "Anlegen" and in English "Create" back |
| $gL10n->get('SYS_CREATE');</code> | $gL10n->get('SYS_CREATE');</code> |
| Does a text not exist in a language , the corresponding text of the reference language is taken (at the moment German) automatically. | Does a text not exist in a language , the corresponding text of the reference language is taken automatically. The reference language is english (en). |
| |
| ==== XML language file ==== | ==== XML language file ==== |
| The XML file is structured as follows: <code xml><?xml version="1.0" encoding="UTF-8"?> | The XML file is structured as follows: <code xml><?xml version="1.0" encoding="UTF-8"?> |
| <language id="en"> | <resources> |
| <version id="2.2.1"> | <string name="SYS_HOUSE">House</string> |
| <text id="SYS_HOUSE" development="edit" translation="todo">house</text> | <string name="SYS_DOG">Dog</string> |
| </version> | <string name="SYS_LONG_TEXT">This is a very long text where it's not possible to get a good identifier.</string> |
| <version id="2.2.0"> | <string name="SYS_PLACEHOLDER_TEXT">This is a #VAR1# text where it's possible to set some #VAR2_BOLD# placeholders.</string> |
| <!-- Phrases only in Announcementmodule --> | </resources></code> There is a resource-node which contains several string-nodes. Each string-node contains an attribute **name**. This attribute must be unique and identifies the respective text. The **name** is fully capitalized and separated with an underline to each word. The string-node itself contains the text in the language of the file.\\ |
| <text id="ANN_ANNOUNCEMENT" development="new" translation="todo">announcement</text> | The texts are to be sorted in the XML file alphabetically per module area according to the **name**.\\ |
| | |
| <!-- System-Phrases for use in every module --> | |
| <text id="SYS_CREATE" development="new" translation="todo">Create</text> | |
| <text id="SYS_MAX" development="new" translation="todo" description="maximum">max.</text> | |
| </version> | |
| </language></code> There is a language-node which outputs the informative language of the file. Below you find the version node, which contains the new and changed text of the relevant version. Below follows the text node that has an attribute **id**. This attribute must be unique and identifies the respective text. The **id** is fully capitalized and separated with an underline to each word. The attribute **development** describes whether the text has been created or changed in the version. This is intended for future translators to help. Another attribute of the translator is **translation**. This attribute marks the status of the translation of the text. Possible values are **todo**, **edited** and **finalized**. Optional there is an attribute **description**, which is to serve a help for the translator especially when abbreviations or ambiguities.\\ | |
| The texts are to be sorted in the XML file alphabetically per module area according to the **id**.\\ | |
| |
| Module-specific texts and words are to be assigned to the module fields. In the long term, it is planned to load the module-specific texts only when the corresponding module is called. | Module-specific texts and words are to be assigned to the module fields. In the long term, it is planned to load the module-specific texts only when the corresponding module is called. |
| |
| ==== Rules for ID ==== | ==== Rules for the name ==== |
| The ID should always be written capitalized and isolated with underscore to each word. It starts with a //3-digit abbreviation of range/module//. This should be modeled on the symbol of the database tables. Then the English word should be namend. English, therefore, that it is easier for translators who are not proficient in German, to identify the right texts. After the symbol then the content of the text should be summarized as short as possible, so that you know about what it is, when you see only the ID. It makes sense ta add also verbs to the end to group texts by sections, e.g. **PRO_PHR_PHOTO_SAVED PRO_PHR_PHOTO_DELETED**. Help for correct translation of the German word into English ID can be found at [[http://translate.google.de |Google Translator]] or [[http://dict.leo.org|Leo]]. | The **name** should always be written capitalized and isolated with underscore to each word. It starts with a //3-digit abbreviation// of system //SYS//. You should not use the abbreviation of the modules anymore. English, therefore, that it is easier for translators who are not proficient in German, to identify the right texts. After the symbol then the content of the text should be summarized as short as possible, so that you know about what it is, when you see only the **name**. It makes sense to add also verbs to the end to group texts by sections, e.g. **PRO_PHR_PHOTO_SAVED PRO_PHR_PHOTO_DELETED**. Help for correct translation of the German word into English **name** can be found at [[https://translate.google.com |Google Translator]] or [[https://dict.leo.org|Leo]]. |
| |
| Examples: | Examples: |
| <code>ANN_ANNOUNCEMENT</code> represents //Announcement// | <code>SYS_ANNOUNCEMENT</code> represents //Announcement// |
| <code>SYS_NO_ENTRY</code> represents //The requested item does not exist in the database.// | <code>SYS_NO_ENTRY</code> represents //The requested item does not exist in the database.// |
| <code>PRO_PHOTO_DELETED</code> represents //The profile photo has been deleted.// | <code>SYS_PHOTO_DELETED</code> represents //The profile photo has been deleted.// |
| |
| ==== Design options in the text ==== | ==== Design options in the text ==== |
| In translatable text placeholders can be defined that can be filled in later recall of the text with variable content. Placeholders are defined as **%VAR1%**, **%VAR2%**, etc. Currently 4 placeholder per text can be specified, which can be expanded as needed. Calling the **get** - method they are passed successively. If not all or none are required, then the getter becomes simply passed fewer arguments. | In translatable text placeholders can be defined that can be filled in later recall of the text with variable content. Placeholders are defined as **#VAR1#**, **#VAR2#**, etc. Calling the **get** - method they are passed successively within an array in the second parameter. If not all or none are required, then the getter becomes simply passed fewer arguments. |
| <code php>$gL10n->get('SYS_BEISPIEL', 'Text for VAR1', $content_var2, 'VAR3'. $content); </code> | <code php>$gL10n->get('SYS_EXAMPLE', array('Text for VAR1', $content_var2, 'VAR3'. $content)); </code> |
| If the contents of a placeholder are issued **bold**, this is possible in the text with the addition **_ BOLD** to the variable name **%VAR1_BOLD%**. | If the contents of a placeholder are issued **bold**, this is possible in the text with the addition **_ BOLD** to the variable name **#VAR1_BOLD#**. |
| |
| Fixed line breaks within the text can be specified via **\n**. These will be replaced later for displaying on the homepage by **<br />**. | Fixed line breaks within the text can be specified via **\n**. These will be replaced later for displaying on the homepage by **<br />**. |
| ==== Multilingualism in Plugins ==== | ==== Multilingualism in Plugins ==== |
| |
| Also in Plugins own language files can be integrated and accessed to existing Admidio language files. Access to the Admidio language files is done relatively easily over the already used syntax in Admidio itself. | Please have a look at [[en:entwickler:how_to_make_your_plugin_translatable|How to make your plugin translatable]]. |
| <code php>$gL10n-> get ('SYS_ALL')</code>\\ | |
| If someone wants to use new unused texts in the plugin, so it must be created an own language file for the plugin. For this, a folder is created in the plugin folder **languages**, where then a newly language file is to be created ,example **de.xml**. The structure of this language file must match from the section **XML language file**. This new folder will be made known via the following call at the beginning of the plugin: <code php> $gL10n-> addLanguagePath (PLUGIN_PATH '/'.$ plugin_folder.'/Languages'.); </code> Now, using the familiar syntax texts from these language files of plugins are accessible. There is no special adaptation necessary. <code php> $ gL10n-> get('PLG_LOGIN_ACTIVE_SINCE') </code> | |
