DokuWiki

It's better when it's simple

User Tools

Site Tools


Sidebar

Translations of this page?:

Learn about DokuWiki

Advanced Use

Corporate Use

Our Community


Follow us on Facebook, Twitter and other social networks.

devel:localization

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>/

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
    • lang.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 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:

$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 strings
    • lang/<language>/settings.php – localised strings used in the configuration manager
    • lang/<language>/<filename>.txt – localised text including DokuWiki markup

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
    • lang.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 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:

$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'];
devel/localization.txt · Last modified: 2016-05-18 10:24 by grosse