Difference between revisions of "Making templates translatable"

Revision as of 16:34, 22 August 2008

Introduction to template translation[edit]

<translate> Joomla! is a truly international application and supports the translation of all strings contained within it. Templates are no exception, and a little extra time spent ensuring that the strings used in your templates are translatable will pay dividends. </translate>

<translate> The language translation system has been designed to be as simple and error-proof as possible. For example, even if a language file is missing, or a particular string has not been translated, Joomla will transparently fall back to showing the untranslated string. There are also some useful tools built into Joomla itself to assist translators in creating a new translation. </translate>

<translate> In this document you will learn about constructing language definition files for your template and how to include translations in your template package file. You will also learn how to make sure that all strings used in your template are translatable and how to debug a new translation. </translate>

Location of template language definition files[edit]

REDIRECT J1.5:Location of template language definition files

Creating a language definition file[edit]

Joomla!

3.x

<translate> series</translate>

<translate> Joomla! language definition files are written in the very basic INI file format. They must be saved using the UTF-8 encoding. Blank lines and lines beginning with a semicolon (;) are ignored and the latter may be used to add comments to the file. Each line consists of a key-value pair separated by an equals sign: </translate>

<translate><!--T:10-->
KEY="value"
</translate>

<translate> where KEY is a string to be translated and value is the translated string. For example: </translate>

<translate><!--T:14-->
ADDITIONAL_INFORMATION="Additional Information"</translate>

<translate> Different versions of Joomla have used slightly different ways to read language files (namely a custom parser and the native PHP INI parser, the latter of which was buggy in PHP 5.2 and older), leading to different rules for what exactly is allowed in keys and values. Language files that abide by the following rules should work under many versions of Joomla, but at least on Joomla and newer. </translate>

<translate> The KEY should only use ASCII characters. It should only contain capital letters, digits, underscores and hyphens, and it should start with a capital letter. Dots (.) are formally allowed, but do not appear to be completely supported. It is a convention to replace any whitespace in the string to be translated with underscores. If more than one entry has the same key, the last one to be encountered is the one that will be used. When you use the key in a JText::_ call, the case does not matter as strings are folded to upper case before searching takes place. So additional_information, Additional_Information or even AdDiTiOnAl_InFoRmAtIoN will be matched. </translate>

<translate> The value should always be surrounded by double-quote characters ("), as in the example. The value itself cannot include double-quote characters, although single-quote characters (') are valid. Use \, including the double quotes, to place a double-quote character in your value. For example, to attach the value <span class="red">Warning!</span> to the key WARNING_TEXT, use following line: </translate>

WARNING_TEXT="<span class=\"red\">Warning!</span>"

<translate> Note that these rules are stricter than required by the PHP INI parser. For example, the PHP INI parser allows you to omit the double quotes around the value as long as it does not contain certain characters. Using the rules above should make it much easier to avoid mistakes such as forgetting double quotes when they are required. </translate>

Note also that from Joomla 4.4.1 and 5.0.1 each value can only be one line of text. Hard linebreaks invalidate the whole language definition file.

Amending the templateDetails.xml file[edit]

<translate> To ensure that your template is fully internationalised you must make sure that certain XML elements are translated and that the language definition files are listed in the templateDetails.xml file. </translate>

Translating templateDetails.xml[edit]

A couple of the elements in the templateDetails.xml file are used in the Template Manager and are themselves translatable. The description should always be translated. </translate>

<translate> name</translate>	<translate> Name of the template. For example, Beez</translate>
<translate> description</translate>	<translate> Description of the template</translate>

<translate> These fields are also shown to the user during template installation. </translate>

Adding Language Definition Files to templateDetails.xml[edit]

</translate> <translate> All language files must be declared in the templateDetails.xml file. This is done by adding two <language> elements for each language to be included with the template: one for the Frontend strings, the other for the Administrator Backend strings. For example, the two British English language files and the two German language files for the Beez template are declared as follows: </translate>

<?xml version=”1.0” encoding=”utf-8” ?>
<install version=”1.5” type=”template”>

     .........

    <languages>
        <language tag=”en-GB”>en-GB.tpl_beez.ini</language>
        <language tag=”de-DE”>de-DE.tpl_beez.ini</language>
    </languages>

     .........

    <administration>
        <languages folder=”admin”>
            <language tag=”en-GB”>en-GB.tpl_beez.ini</language>
            <language tag=”de-DE”>de-DE.tpl_beez.ini</language>
        </languages>
    </administration>

</install>

<translate> Note that in the administration <languages> tag the folder attribute is used. This is because the language files for the Frontend and Backend have the same file names and so cannot exist in the same directory within the template package file. In this example, the administration language files have been placed in a sub-directory called admin to separate them from the Frontend language files. </translate>

Embedding translatable strings in the template[edit]

<translate> In the template itself, translations are handled using the JText static class. It is referred to as "static" because it does not require instantiation as an object before its methods may be used. </translate>

Simple Text Strings[edit]

</translate>

<translate> Most text strings can be translated using the "_" (underscore) method. For example, suppose your template contains the English text "Welcome" which needs to be made translatable. </translate>

<?php
  echo 'Welcome';
?>

<translate> Then you would replace the static string like this: </translate>

<?php
  echo JText::_( 'Welcome' );
?>

<translate> This would cause the translation system to search the appropriate language file for "WELCOME" on the left side of an equals sign. The search is case-insensitive. If this language definition string is encountered: </translate>

WELCOME=Welcome!

<translate> the effect will be to output the string "Welcome!" to the browser. If the user switches to the German language, the German language definition file will be searched for "WELCOME" and this time might encounter the string: </translate>

WELCOME=Willkommen

<translate> and so "Willkommen" will be sent to the browser. Importantly, if the user switches to German but there is no German language file present, or the appropriate string does not appear in the German language file, Joomla will fall back to sending the untranslated string "Welcome" to the browser, also preserving its original case. </translate>

Debugging a translation[edit]

<translate> Joomla supports some useful debugging mechanisms that can make it easier to locate untranslated strings and diagnose problems with language translations in installed extensions. </translate>

Debug Language[edit]

</translate> [[Image:global-config-language-debug-<translate> en</translate>.png|right|250px]]<translate> Activate language debugging in the Administration Backend by going to System → Global Configuration → System tab. Go down to Debug Language, change the value to Yes. Then select Save & Close. </translate>

<translate> With this option active all translatable strings are shown surrounded with special characters that indicate their status. </translate>

<translate> Code</translate>	<translate> Status</translate>
Joomla CMS	<translate> (text surrounded by asterisks) indicates that a match has been found in the language definition file and the string has been translated.</translate>
??Joomla CMS??	<translate> (text surrounded by pairs of question marks) indicates that the string is translatable but no match was found in the language definition file.</translate>
Joomla CMS	<translate> (text with no surrounding characters) indicates that the string is not translatable.</translate>

Debug System[edit]

</translate> <translate> Additional language debugging information can be obtained by activating system debugging. Go to System → Global Configuration → System tab. Find the Debug System option and change the value to Yes. Then select Save & Close. </translate>

<translate> With this option active all screens have additional debugging information at the end of each page. Currently this includes </translate>

<translate>

Profile information. This is the amount of time taken to execute code up to various mark points in the code.</translate>

<translate>

Memory usage. The amount of system RAM used.</translate>

<translate>

SQL queries executed. All of the SQL queries executed in the process of building the page.</translate>

<translate>

Language files loaded. A list of all the language files loaded in the process of building the page, including full path information. This can be useful to check that the expected files have been loaded. The number after each file path is the number of times that the file was referenced.</translate>

<translate>

Untranslated strings diagnostic. A list of all the untranslated strings found and the likely file location given where the JText call was made.</translate>

<translate>

Untranslated strings designer. A list of all the untranslated strings found but listed in a KEY=Value format so they can be copy-pasted directly into a language definition file (INI).</translate>

Debug Plugin[edit]

</translate> [[Image:debug-plugin-<translate> en</translate>.png|right]]<translate> This system plugin controls what is displayed when debugging is activated in Global Configuration. It is enabled by default. You can access the parameters for the plugin from Extensions → Plugin Manager. Locate the System - Debug plugin and click on it. There are three settings of interest to translators.</translate>

<translate>

Display loaded language files. If set to Yes, the debug information will include a list of the language files that were requested as the current page was being generated.</translate>

<translate>

Display undefined language strings. If set to diagnostic mode, a list of untranslated strings and the location of the file containing the call to JText is included in the debug information. If set to designer mode, a list of untranslated strings in a format that can be copy-pasted directly into a language definition file is included in the debug information. That is, it displays the list in KEY=String format. If set to All modes, both the diagnostic mode and designer mode lists are included in the debug information.</translate>

<translate>

Strip Key Prefix. Only used when Display undefined language strings is set to Designer mode or All modes. This allows you to strip a prefix from the string to form the key. This is useful if the designer uses a common prefix for their extensions when using JText methods. See example below.</translate>

<translate> Note that the display of untranslated strings will only display the value passed to the appropriate JText method. For example, with the following code: </translate>

echo JText::_( 'Reports Import Configuration' );

<translate> If untranslated, Designer mode will display this as: </translate>

# /administrator/components/com_reports/views/reports/tmpl/default.php
REPORTS IMPORT CONFIGURATION=Reports Import Configuration

<translate> If the Strip Key Prefix is set to Reports, the display would change slightly to: </translate>

# /administrator/components/com_reports/views/reports/tmpl/default.php
REPORTS IMPORT CONFIGURATION=Import Configuration

<translate> Note that the path shown is only a best guess based on a call to the PHP debug_backtrace function. Sometimes it is accurate, sometimes it is not and there are also cases where no file could be determined. In those cases you have to use your best judgement. </translate>

@@ Line 1: / Line 1: @@
 ===Introduction to template translation===
 {{:Introduction to template translation}}
-===Location of language definition files===
+===Location of template language definition files===
-{{:Location of language definition files}}
+{{:Location of template language definition files}}
 ===Creating a language definition file===
 {{:Creating a language definition file}}