This XML format is used for "locallang-XML" files, a format TYPO3 uses for storage of interface labels and translations of them. The format is parsed by t3lib_div::xml2array() which means that tag-names and "index" attribute values are inter-related in significance. The content is always in utf-8.
See "Inside TYPO3" for more details about locallang-files and the application of this format.
"locallang-XML" files are translated by a backend tool (extension "llxmltranslate") contrary to "locallang*.php" files which are translated online on TYPO3.org. Using a backend tool makes translation faster and more "responsive" for translators who get immediate results.
A "locallang-XML" file contains a set of labels in the default language (always English) and translations of them for each system language in TYPO3 (around 40). Alternatively translations for a single language can be stored externally in an "include-file" which is a practical solution for large amounts of texts in order not to bloat the files; after all people would only need the default labels plus a single or two languages active on an installation.
This is the elements and their nesting in the locallang-XML format.
Elements nesting other elements (“Array” elements):
All elements defined here cannot contain any string value but must contain another set of elements.
(In a PHP array this corresponds to saying that all these elements must be arrays.)
Element | Description | Child elements |
|---|---|---|
<T3locallang> | Document tag | <meta> <data> <orig_hash> <orig_text> |
<meta> | Contains meta data about the locallang-XML file. Used in translation, but not inside TYPO3 directly. | <labelContext> <description> <type> <csh_table> <fileId> <keep_original_text> <ext_filename_template> |
<data> | Contains the data for translations Notice: The contents in the <data> tag is all that is needed for labels inside TYPO3. Everything else is meta information for the translation tool! | <languageKey> |
<orig_hash> | Contains hash-integers for each translated label of the default label at the point of translation. This is used to determine if the default label has changed since the translation was made. | <languageKey> |
<orig_text> | Contains the text of the default label that was the basis of the translated version! This will be stored only if <meta><keep_original_text> is set. Otherwise the information is stored in temporary files in typo3temp/ on the local server (which means this meta-information is available but only locally.) The original text is used to show a diff between the original base of the translation and the new default text so a translator can quickly see what has changed. | <languageKey> |
<languageKey> | Array of labels for a language. The "index" attribute contains language key External includefile under "<data>": If the <languageKey> tag used in the context of the <data> tag contains a string instead of an array of labels then it indicates that all labels for the language in question (other than "default"!) is found in another XML file pointed to by this value. The point is to save space so locallang-XML files doesn't have to carry all translations with them (in particular interesting for CSH content where the amounts of text is enormous.) The filenames of include files should not start with "locallang..." since they will then be detected directly by the translation tool (which you don't want!). A common practice could be to prefix them with the language key like in this example: Example of including an external file for a specific language: EXT:csh_dk/lang/dk.locallang_csh_web_info.xml | <label> Alternatively, when used under <data> it can be a string pointing to an external "include file"! |
<labelContext> | Array of context descriptions of the default labels. The "index" attribute contains label key | <label> |
Elements containing values (“Value” elements):
All elements defined here must contain a string value and no other XML tags whatsoever!
All values are in utf-8.
(In a PHP array this corresponds to saying that all these elements must be strings or integers.)
Element | Format | Description |
|---|---|---|
<label> (under <data>) | string | Value of a original/translated label. The "index" attribute contains label key. |
<label> (under <orig_hash>) | integer | Hash of a translated label. The "index" attribute contains label key. |
<label> (under <orig_text>) | string | Original default value of a translated label used for making a diff if the original has changed. The "index" attribute contains label key. |
<label> (child of <labelContext>) | string | Description of a default labels context. This should be used where it cannot be clear for the translation where the default labels occur. Sometimes the context is important for the translator in order to translate correctly. The "index" attribute contains label key. |
<description> | string | Description of the file contents. |
<type> | string | Type of content. Possible values are:
|
<csh_table> | string | (Only when the type is "CSH"!) For CSH it is important to know what "table" the labels belong to. A "table" in the context of CSH is an identification of a group of labels. This can be an actual table name (containing all CSH for a single table) or it can be module names etc. with a prefix to determine type. See CSH section in "Inside TYPO3" for more details. Examples: <csh_table>xMOD_csh_corebe</csh_table> (General Core CSH) <csh_table>_MOD_tools_em</csh_table> (For Extension Mgm. module) <csh_table>pages</csh_table> (For "pages" table) |
<fileId> | string | File identification string, typically the filename relative to extension folder. Example: EXT:lang/locallang_csh_corebe.xml |
<keep_original_text> | boolean | If set to "1" the content of "<orig_text> is updated by the translation tool. |
<ext_filename_template> | string | Template string for automatically created external files (for all other languages than "default") Example: EXT:csh_###LANGKEY###/lang/###LANGKEY###.locallang_csh_corebe.xml |
<T3locallangExt>
External include files contains a sub-set of the tags of the <T3locallang> format. Basically they contain the <data>, <orig_hash> and <orig_text> tags but with "<languageKey>" tags inside only for the specific language they used.
When the include file is read the information for the selected language key is read from each of the three tags and merged into the internal array.
Element | Description | Child elements |
|---|---|---|
<T3locallangExt> | Document tag for the external include files of "<T3locallang>" | <data> <orig_hash> <orig_text> |
<data> | See <data> element of <T3locallang> above. | |
<orig_hash> | See <data> element of <T3locallang> above. | |
<orig_text> | See <data> element of <T3locallang> above. |
Example: locallang-XML file for a backend module
This example shows a standard locallang-XML file for a backend module. Notice how the <orig_hash> section is included which means that translators can spot if an original label changes. However the "<orig_text>" section would have been needed if translators were supposed to also see the difference. But typically that is not enabled since it takes a lot of space up.
<T3locallang>
<meta type="array">
<description>Standard Module labels for Extension Development Evaluator</description>
<type>module</type>
<csh_table/>
<fileId>EXT:extdeveval/mod1/locallang_mod.xml</fileId>
<labelContext type="array"/>
</meta>
<data type="array">
<languageKey index="default" type="array">
<label index="mlang_tabs_tab">ExtDevEval</label>
<label index="mlang_labels_tabdescr">The Extension Development Evaluator tool.</label>
</languageKey>
<languageKey index="dk" type="array">
<label index="mlang_tabs_tab">ExtDevEval</label>
<label index="mlang_labels_tabdescr">Evalueringsværktøj til udvikling af extensions.</label>
</languageKey>.... </data> <orig_hash type="array">
<languageKey index="dk" type="array">
<label index="mlang_tabs_tab" type="integer">114927868</label>
<label index="mlang_labels_tabdescr" type="integer">187879914</label>
</languageKey> </orig_hash></T3locallang>
Example: locallang-XML file (CSH) with reference to external include file
The main XML file looks like this. Notice the tag "csh_table" has a value which is important for CSH content so it can be positioned in the right category.
In the <data> section you can see all default labels. But notice how the value for the "dk" translation is a reference to an external file! The contents of that file is shown below this listing.
The tag <ext_filename_template> contains a value which means that new translations for other language keys automatically creates a new file somewhere. The main rule is that the file cannot exist yet. The main point is to make it easy to create new external include files, in particular group them into extensions carrying such as CSH for a whole language. This value shows that a new language (eg. "de") will create a new file inside an extension prefixed "csh_".
<T3locallang> <meta type="array">
<description>CSH for Web>Info module(s) (General Framework)</description>
<type>CSH</type>
<fileId>EXT:lang/locallang_csh_web_info.xml</fileId>
<csh_table>_MOD_web_info</csh_table>
<keep_original_text>1</keep_original_text>
<ext_filename_template>EXT:csh_###LANGKEY###/lang/###LANGKEY###.locallang_csh_web_info.xml</ext_filename_template>
<labelContext type="array"/>
</meta>
<data type="array">
<languageKey index="default" type="array">
<label index=".alttitle">Web > Info module</label>
<label index=".description">The idea of the Web>Info ...</label>
<label index=".details">Conceptually the Web>Info mod...functionality.</label>
<label index="_.seeAlso">_MOD_web_func,</label>
<label index="_.image">EXT:lang/cshimages/pagetree_overview_10.png</label>
<label index=".image_descr">The Web>Info module a.... "info_pagetsconfig".</label>
</languageKey>
<languageKey index="dk">EXT:csh_dk/lang/dk.locallang_csh_web_info.xml</languageKey>
</data>
</T3locallang>
The include file (for "dk") looks like below. Because <keep_original_text> was set in the main file you will also see that the <orig_text> section is filled in with content as well.
<T3locallangExt> <data type="array">
<languageKey index="dk" type="array">
<label index="pagetree_overview.alttitle">Sidetræ overblik</label>
</languageKey>
</data>
<orig_hash type="array">
<languageKey index="dk" type="array">
<label index="pagetree_overview.alttitle" type="integer">92312309</label>
</languageKey>
</orig_hash>
<orig_text type="array">
<languageKey index="dk" type="array">
<label index="pagetree_overview.alttitle">Pagetree Overview</label>
</languageKey>
</orig_text>
</T3locallangExt>
