Internationalization (i18n)

i18n makes page content multilingual without duplicating the page: the markup key inserts the current language's text in place — from a CSV table, from a setting, or straight out of the markup. It is meant for authors who keep menus, buttons and building blocks in several languages, and for template developers who need the same texts from PHP.

Quick start: show a text in two languages – the shortest path to a first result, in three steps.

Create the translation table → place the markup on a page → check which language is chosen

The wki18n plugin brings four sources of multilingual text into a page:

• Translation keys – looked up in a CSV table
• Inline translations – de:Text|en:Text, written into the markup itself
• Configuration values – DokuWiki settings, with language pairs resolved
• Template values – template settings, resolved the same way

• Multilingual navigation – menu labels that follow the reader's language
• Translatable interface elements – buttons, labels, hints
• Template integration – sidebar, footer, header
• One place for shared texts – every recurring label in a single table

Home
Contact

Looks the key up in the translation table (see CSV format) for the current language.

Startseite
Home

Uses the named language, whatever the page or the browser asks for.

de:Ja|en:Yes|sl:Da
de:Speichern|en:Save|sl:Shrani

The translations live in the markup; no table is involved.

conf:title
conf:tagline

Reads a DokuWiki setting and resolves the language pairs in it.

tpl:footerText
tpl:topSidebarTitle

Reads a template setting and resolves the language pairs in it.

Your own translations belong in data/wki18n/i18n.csv (strictly: <savedir>/wki18n/i18n.csv). That file lives outside the plugin folder, survives every update, and is never served by the web server:

key,de,en,sl
menu_home,Startseite,Home,Domov
menu_contact,Kontakt,Contact,Kontakt
button_save,Speichern,Save,Shrani

The plugin itself ships only a few general keys in lib/plugins/wki18n/i18n.csv (menu_home, menu_contact, menu_back), and every install replaces that file. Your table is read after it and wins per key and per language: a row in your table overrides the shipped value in every language it fills in, and an empty cell leaves the shipped value in place. A line that starts with # is a comment.

The language is determined in this order (helper.php, detectLanguage()):

1. The visitor's explicit choice – ?lang=sl in the request, otherwise the choice remembered from an earlier request (a cookie). It only applies after a deliberate click in a language switcher; a visitor who never chooses never notices it.
2. The namespace path – de:start → de
3. The language of the window that opened this one – a window such as the media dialog keeps the language it was opened in; this is not remembered
4. The browser header – Accept-Language: de-DE → de
5. DokuWiki's language – $conf['lang']
6. The plugin default – the defaultLang setting

Each candidate is checked against the languages list; a code that is not on it is skipped.

The default is the value the plugin ships with. On this site, languages is set to de,en,sl.

===== menu_navigation =====
  * [[..:start|Home]]
  * [[..:docs:index|Project Documentation]]
  * [[..:contact|Contact]]

Result (browser set to English):

• Home
• Project Documentation
• Contact

<button>de:Absenden|en:Submit|sl:Pošlji</button>

<footer>
tpl:footerText
</footer>

Languages: [[..:de:start|Startseite]] |
           [[..:en:start|Home]] |
           [[..:sl:start|Domov]]

Result:

• Languages: Startseite | Home | Domov

<?php
// Load the helper
$helper = plugin_load('helper', 'wki18n');
 
if ($helper) {
    // A translation for the current language
    echo hsc($helper->get('menu_home'));
 
    // A fixed language
    echo hsc($helper->get('menu_home', 'en'));
 
    // Resolve an inline value
    echo hsc($helper->parseMultilang('de:Ja|en:Yes'));
 
    // A template setting
    echo hsc($helper->getTplConfig('footerText'));
}
?>

Old: {{wk:lang>
New: {{wk:i18n>

Old: {{wk:lang:
New: {{wk:i18n:

• wksnippet – reusable HTML building blocks
• wkacmenu – menu titles that use this markup

File: lib/plugins/wki18n/syntax.php

File: lib/plugins/wki18n/helper.php

<wk:audit stack=“doku” title=“wki18n Plugin”>

<wk:include ref="code:qualitaet" critical="true">[x][x][x][x]</wk:include>
<wk:include ref="stacks:dokuwiki-php">[x][x][x][x][x]</wk:include>
<wk:include ref="sicherheit:kritis" critical="true">[x][x][x][x][x]</wk:include>

</wk:audit>

DISCUSSION

Plugin: wki18n
Version: 1.0.0
Namespace: lib/plugins/wki18n/
Author: Wolfgang van der Stille Wolfgang.van.der.Stille@gmail.com (The White Knight Labs)
License: GPL 2