====== Localization ======

Internationalization is a key feature of DokuWiki and [[:localization]] of the user interface in [[devel:templates|templates]] and [[devel:plugins|plugins]] are supported. Developers should also take extra care to preserve encoding of wiki text and other user input.

===== File format =====

Each language have their own subdirectory named after the [[wp>ISO_3166-1]] two letter code. You will also find the ISO-code of well-known languages at http://translate.dokuwiki.org/.

All files containing localization strings must be encoded in [[:utf-8|UTF-8 Encoding]].

Short strings are stored in a file ''lang.php'', which should contain an array entry for each localized string. These strings can NOT contain any DokuWiki syntax.
 
<code php>
  <?php
  // Example language file
  $lang['hello_world'] = 'Hello world!';
</code>

Larger files where DokuWiki [[:wiki:syntax|formatting syntax]] are allowed is also supported. They have same format and naming conventions as normal wiki pages, see ''[[https://github.com/dokuwiki/dokuwiki/blob/master/inc/lang/en/admin.txt|inc/lang/en/admin.txt]]'' for an example.
<code txt inc/lang/en/admin.txt>
====== Administration ======

Below you can find a list of administrative tasks available in DokuWiki.
</code>

===== Core localization =====
===String localizations===
Inside [[xref>inc/init.php]] the [[config:lang|configuration setting]] determines which ''lang.php'' file are read into a [[devel:environment|global array]] ''$lang[]''. Missing entries are filled with values from the English ''lang.php'' file. 

The strings are read by DokuWiki from the files:
  inc/lang/en/lang.php
  conf/lang/en/lang.php
  inc/lang/<ISO>/lang.php
  conf/lang/<ISO>/lang.php

You can access these localized strings anywhere by using the ''$lang[]'' array. 

<code php>
global $lang;
echo $lang['btn_edit'];
</code>

===File localizations===
Core localization files are stored in
    inc/lang/<ISO>/..
    inc/lang/en/denied.txt

and can be overridden in an individual installation. For example to facilitate customized "Denied login" messages. These files should be stored in
    conf/lang/<ISO>/..
    conf/lang/en/denied.txt

You can access these files by using ''[[xref>p_locale_xhtml()|p_locale_xhtml('filename')]]''.
<code php>
print p_locale_xhtml('denied');
</code>

===== Plugin localization =====
The base plugin class [[xref>DokuWiki_Plugin]] provides support for localization of plugins. 

Localisations are stored in the plugin folder. The next files can be provided by the developer:
  * ''<dokuwiki>/lib/plugins/<pluginname>/''
    * ''lang/<language>/lang.php'' -- English language strings 
      * accessible via ''$this%%->%%[[xref>getLang()]]''\\ \\ 
    * ''lang/<language>/settings.php'' -- localised strings used in the [[plugin:config|configuration manager]]
      * Show up in the [[plugin:config|configuration manager]]\\ \\ 
    * ''lang/<language>/<filename>.txt'' -- localised text including DokuWiki markup 
      * accessible via ''$this%%->%%[[xref>locale_xhtml()]]''

These files can be added by the user to customize the localization:
  * ''<dokuwiki>/conf/plugin_lang/<pluginname>/<language>/''
    * ''<filename>.txt'' -- here wiki admins can override the default localized text
      * accessible via ''$this%%->%%[[xref>locale_xhtml()]]''\\ \\
    * ''lang.php'' -- override the provided strings
      * accessible via ''$this%%->%%[[xref>getLang()]]''\\ \\ 

In the plugins the [[#javascript localization]] is supported too.

The most important public methods are:
    * ''getLang('string name')'' --- will return the local language version of ''string name'' or the English version if it is not present.
    * ''locale_xhtml('filename')'' --- will pass the local language version of ''%%'filename.txt'%%'' (which may contain DokuWiki markup) to the renderer for immediate output, so it returns html. If a local language file does not exist the US English version will be used.


===Examples===
Using localized strings:
<code php>
$title = $this->getLang('dataentry')
$updated = sprintf($this->getLang('updated'), $this->numberdownloads)
</code>
The first string returns the title string e.g. ''Dataentry'' in English or ''Datablok'' in Dutch for the data plugin. The second string ''Plugin %s updated successfully'' contains a ''%s'', which is replaced by [[http://php.net/manual/en/function.sprintf.php|sprintf]] with the value of ''$this%%->%%numberdownloads''.

Also a localised text can be included. This displays the rendered wikitext from file ''lang/<language>/admin_intro.txt'':
<code php>
 echo $this->locale_xhtml('admin_intro');
</code>


===== Template Localization =====

Many templates only uses the core language files but they can also have their own localization files.
DokuWiki provides via [[xref>inc/template.php]] support for localization of templates. 

Localisations are stored in the template folder. The next files can be provided by the developer:
  * ''<dokuwiki>/lib/tpl/<templatename>/''
    * ''lang/<language>/lang.php'' -- English language strings 
      * accessible via ''[[xref>tpl_getLang()]]''\\ \\ 
    * ''lang/<language>/settings.php'' -- localised strings used in the configuration manager
      * Show up in the [[plugin:config|configuration manager]]
    * ''lang/<language>/<filename>.txt'' -- localised text including DokuWiki markup 
      * accessible via ''[[xref>tpl_locale_xhtml()]]''

These files can be added by the wiki user to customize the localization:
  * ''<dokuwiki>/conf/template_lang/<pluginname>/<language>/''
    * ''<filename>.txt'' -- here wiki admins can override the default localized text
      * accessible via ''[[xref>tpl_locale_xhtml()]]''\\ \\ 
    * ''lang.php'' -- override the provided strings
      * accessible via ''$this%%->%%[[xref>tpl_getLang()]]''\\ \\  

In the templates the [[#javascript localization]] is supported too.

The relevant method is:
    * ''tpl_getLang('string name')'' --- will return the local language version of ''string name'' or the English version if it is not present.
    * ''tpl_locale_xhtml('filename')'' --- will pass the local language version of ''%%'filename.txt'%%'' (which may contain DokuWiki markup) to the renderer for immediate output, so it returns html. If a local language file does not exist the English version will be used.


===Examples===
Using localized strings:
<code php>
$title = tpl_getLang('dataentry')
$updated = sprintf(tpl_getLang('updated'), $this->numberdownloads)
</code>
The first string returns the title string e.g. ''Dataentry'' in English or ''Datablok'' in Dutch for the data plugin. The second string ''There are %s units updated successfully'' contains a ''%s'', which is replaced by [[phpfn>sprintf()]] with the value of ''$this%%->%%numberdownloads''.


===== JavaScript Localization =====

DokuWiki provides an easy way to get translated strings into JavaScript.
Just add the translation to the ''lang.php'' in a subarray called ''js''.
This method will also work for plugins and the active template.
Example:
<code php>
<?php
$lang['js']['key'] = 'translation text';
$lang['js']['your translation key'] = 'translation text';
</code>

This information will be provided in the global ''LANG'' variable in JavaScript. You can access them the following way:
<code javascript>
// Core translation.
LANG.key;
LANG['your translation key'];

// If you're in a plugin:
LANG.plugins.<your plugin name>.key;
LANG.plugins.<your plugin name>['your translation key'];

// If you're in a template:
LANG.template.<your template name>.key;
LANG.template.<your template name>['your translation key'];
</code>