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.

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.

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'];

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');

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 strings
    • accessible via $this->getLang()
      
      
  • lang/<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 $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 text
    • accessible via $this->locale_xhtml()
      
      
  • lang.php – override the provided strings
    • accessible via $this->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.

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');

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 strings
    • accessible via tpl_getLang()
      
      
  • lang/<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 text
    • accessible via tpl_locale_xhtml()
      
      
  • lang.php – override the provided strings
    • accessible via $this->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.

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.

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'];