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.

All files containing localization strings must be encoded in UTF-8 Encoding. Each language have their own subdirectory named after the wiki/ISO_3166-1 two letter code. You will also find the ISO-code of well-known languages at http://translate.dokuwiki.org/.

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.

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.

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

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

The base plugin class DokuWiki_Plugin provides support for localization of plugins.

There are four public methods and two properties:

• Methods
  • getLang('string name') — will return the local language version of string name or the US English version if it is not present.
  • locale_xhtml('filename') — will pass the local language version of 'filename.txt' to the renderer for immediate output. If a local language file does not exist the US English version will be used.
  • localFN('id') — will return the full path for local language file 'id.txt' or if that file doesn't exist it will return the full path for the US English version of 'id.txt'.
  • setupLocale() — will read in the plugins language strings for the current language - any missing strings will be filled with the US English version. If retrieval of language strings is handled by getLang() there is no need to access this method.

• Properties
  • $lang — an array of language dependent strings. This array is initially empty and needs to be filled either by calling setupLocale() or making a call to getLang(). If all retrieval of language strings is handled by getLang() there is no need to access this property.
  • $localised — boolean, indicates whether or not localisation has been setup. Initially false, set to true by setupLocale(). If all retrieval of language strings is handled by getLang() there is no need to access this property.

Localisation files must be placed in the following folder structure:

lib/plugins/[plugin name]/lang/[xx]/

where [xx] is the two digit localisation code. All plugins should at least provide data for “en” (US English). This data will be used if data for the actual locale is not present.

Text strings displayed by the plugin should be defined in the file

.../lang/[xx]/lang.php

and be of the form

$lang['string name'] = 'text';

Many templates only uses the core language files but they can also have their own localization files.

   lib/tpl/<template name>/lang/<ISO-code>/ 

The strings will be added to the core $lang[] array.