Table of Contents
Localization
Internationalization is a key feature of DokuWiki and localization of the user interface in templates and 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 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 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.
<?php // Example language file $lang['hello_world'] = 'Hello world!';
Larger files where DokuWiki formatting syntax are allowed is also supported. They have same format and naming conventions as normal wiki pages, see inc/lang/en/admin.txt
for an example.
- inc/lang/en/admin.txt
====== Administration ====== Below you can find a list of administrative tasks available in DokuWiki.
Core localization
String localizations
Inside inc/init.php the configuration setting determines which lang.php
file are read into a 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.
global $lang; echo $lang['btn_edit'];
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 p_locale_xhtml('filename')
.
print p_locale_xhtml('denied');
Plugin localization
The base plugin class 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 stringslang/<language>/settings.php
– localised strings used in the configuration managerlang/<language>/<filename>.txt
– localised text including DokuWiki markup- accessible via
$this->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 textlang.php
– override the provided strings
In the plugins the javascript localization is supported too.
The most important public methods are:
getLang('string name')
— will return the local language version ofstring 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:
$title = $this->getLang('dataentry') $updated = sprintf($this->getLang('updated'), $this->numberdownloads)
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 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
:
echo $this->locale_xhtml('admin_intro');
Template Localization
Many templates only uses the core language files but they can also have their own localization files. DokuWiki provides via 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 stringslang/<language>/settings.php
– localised strings used in the configuration manager- Show up in the configuration manager
lang/<language>/<filename>.txt
– localised text including DokuWiki markup- accessible via
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 textlang.php
– override the provided strings
In the templates the javascript localization is supported too.
The relevant method is:
tpl_getLang('string name')
— will return the local language version ofstring 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:
$title = tpl_getLang('dataentry') $updated = sprintf(tpl_getLang('updated'), $this->numberdownloads)
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 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:
<?php $lang['js']['key'] = 'translation text'; $lang['js']['your translation key'] = 'translation text';
This information will be provided in the global LANG
variable in JavaScript. You can access them the following way:
// 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'];