DokuWiki Multi-Language Wiki — Language Files, Translation Plugin, and i18n

In this tutorial, you'll learn how to set up a multi-language DokuWiki, including language file structure, the translation plugin for multilingual content, interface localization, and Internationalization best practices.

What You'll Learn

• DokuWiki's language file system
• Interface localization (translating UI elements)
• The translation plugin for content
• Creating multilingual page structures
• Language detection and switching
• i18n best practices

Why It Matters

If your wiki serves users who speak different languages, you need multi-language support. DokuWiki's approach is different from MediaWiki — it uses the translation plugin to create parallel pages in different languages, not a database-based system. Understanding this approach prevents confusion and helps you create a wiki that serves international users effectively.

Real-World Use

A documentation wiki for an open-source project needs to serve content in English, German, and Japanese. The admin installs the translation plugin. For each page, they create translations: docs:installation (English), docs:de:installation (German), and docs:ja:installation (Japanese). The language switcher in the header allows users to switch between languages. New content is written in English first, then translated to other languages.

Learning Path

flowchart LR
  A[SEO] --> B[Multi-Language]
  B --> C[CLI Tools]
  C --> D[API]
  D --> E[Backup]
  E --> F[Upgrading]

DokuWiki Interface Languages

DokuWiki's user interface is translated into dozens of languages. Language files are in inc/lang/:

inc/lang/
├── en/           # English (default)
│   ├── lang.php  # UI strings
│   └── settings.php
├── de/           # German
├── fr/           # French
├── ja/           # Japanese
├── pt_BR/        # Brazilian Portuguese
└── zh/           # Chinese

Setting the Default Language

<?php
// conf/local.php
$conf['lang'] = 'en';     // Default language
$conf['autolang'] = 'en'; // Auto-detect browser language, fallback to en

User Language Preference

Users can set their language in their profile. The interface appears in their chosen language if translation files exist.

The Translation Plugin

The translation plugin enables multilingual content. It creates parallel pages in different languages.

Installation

cd /var/www/html/wiki/lib/plugins/
wget https://github.com/splitbrain/dokuwiki-plugin-translation/archive/master.zip
unzip master.zip
mv dokuwiki-plugin-translation-master translation

Configuration

<?php
// conf/local.php
$conf['plugin']['translation']['translations'] = 'en,de,fr,ja';
$conf['plugin']['translation']['display'] = 'langcode';  // Show language codes
$conf['plugin']['translation']['dropdown'] = 0;           // 0 = list, 1 = dropdown
$conf['plugin']['translation']['showheader'] = 1;         // Show translation bar
$conf['plugin']['translation']['starttranslations'] = 'en'; // Primary language

Multilingual Page Structure

The translation plugin uses a naming convention:

namespace:page              # Default language (English)
namespace:de:page           # German translation
namespace:fr:page           # French translation
namespace:ja:page           # Japanese translation

Pages in different languages are separate wiki pages with different IDs. The plugin manages navigation between them.

Translation Bar

When the plugin is enabled, a translation bar appears at the top of each page:

English | Deutsch | Français | 日本語

Clicking a language link takes the user to the corresponding translation.

Creating Multilingual Content

Step 1: Write the Primary Language Page

Create the page in your primary language (e.g., English):

====== Installation Guide ======

This guide covers the installation process.

Step 2: Create Translations

Create pages with the language prefix:

====== Installationsanleitung ======

Dieser Leitfaden behandelt den Installationsprozess.

The page ID would be de:installation-guide.

Step 3: Link Pages with the Plugin

The translation plugin automatically detects language variants when the naming convention is followed. No manual linking needed.

Translation Status Display

The plugin shows translation status:

[en] Installation Guide (complete)
[de] Installationsanleitung (complete)
[fr] Guide d'installation (outdated)
[ja] インストールガイド (missing)

This helps editors know which pages need updates.

Language Detection

Browser Language Detection

DokuWiki can detect the user's browser language:

<?php
// conf/local.php
$conf['autolang'] = 'en';  // Auto-detect, fallback to English

When a user visits the wiki, DokuWiki checks their Accept-Language header and shows the interface in their preferred language.

Language Switcher

Add a language switcher to your template:

<?php
// In template's main.php
if ($conf['plugin']['translation']['translations']) {
    echo '<div class="lang-switcher">';
    $translations = explode(',', $conf['plugin']['translation']['translations']);
    foreach ($translations as $lang) {
        $url = wl($lang . ':' . $ID);
        $active = ($lang === $conf['lang']) ? ' class="active"' : '';
        echo '<a href="' . $url . '"' . $active . '>' . hsc($lang) . '</a>';
        echo ' ';
    }
    echo '</div>';
}

Language Files and Localization

Custom Language Strings

To customize or add UI translations:

<?php
// inc/lang/en/lang.php (do not edit directly)
// Instead, create conf/lang.php override

// conf/lang.php - Override specific strings
$lang['btn_edit'] = 'Edit This Page';
$lang['btn_history'] = 'View History';
$lang['loggedinas'] = 'Logged in as:';

Plugin Language Files

Plugins also have language files:

lib/plugins/myplugin/lang/
├── en/
│   └── lang.php
├── de/
│   └── lang.php
└── fr/
    └── lang.php

i18n Best Practices

Naming Conventions

• Use ISO 639-1 language codes (en, de, fr, ja, zh, etc.)
• Use ISO 3166-1 region codes for regional variants (en_US, en_GB, pt_BR)
• Keep the namespace structure consistent across languages

Content Management

• Write content in the primary language first
• Create translations promptly
• Mark outdated translations clearly
• Keep a translation checklist for each page

Template i18n

Templates can be translated:

lib/tpl/mytemplate/lang/
├── en/
│   └── lang.php
├── de/
│   └── lang.php
└── fr/
    └── lang.php

In template PHP:

<?php
// Use language strings in templates
echo $lang['dw_btn_edit'];  // Loaded from template's lang file

Common Mistakes

1. Not using the translation plugin: Trying to manage multilingual content without the plugin leads to broken navigation and confusing URL structures.
2. Inconsistent namespace structure: Each language should mirror the same structure. If en:installation exists, de:installation must also exist (with German content).
3. Not marking outdated translations: Users who find outdated translations lose trust. Use the translation status feature to flag stale content.
4. Translating the entire wiki at once: Start with the most important pages and expand. A fully translated start page and sidebar is more valuable than 50% of pages translated randomly.
5. Hard-coding language strings in plugins: Plugin strings should use language files. Hard-coded English text cannot be translated without modifying the plugin.

Practice Questions

1. How does the translation plugin structure multilingual pages, and what naming convention does it use?
2. How does DokuWiki detect a user's preferred language, and where do you configure fallback behavior?
3. What is the difference between interface translation (inc/lang/) and content translation (translation plugin)?
4. Challenge: Set up a multi-language DokuWiki with English as the primary language and two additional languages (German and Japanese). Create 5 pages in English: start page, installation guide, configuration guide, FAQ, and contact page. Translate all 5 pages to German. Translate 3 of 5 pages to Japanese. Mark the Japanese translations that are still pending. Configure the translation plugin to show language flags in the translation bar. Test switching between languages and verify that untranslated pages show the English fallback.

FAQ

Mini Project

Goal: Build a multi-language wiki with at least three languages.

1. Install the translation plugin
2. Configure three languages: en, de, fr
3. Create the start page in English with welcome content
4. Create German and French translations of the start page
5. Create 3 content pages in English
6. Translate 2 of them to German and 1 to French
7. Configure the translation bar to show language names
8. Test navigation between languages
9. Mark one translation as outdated and verify the status display
10. Document the translation workflow for content editors

What's Next

Multi-language support makes your wiki global. Now learn about CLI tools for managing your wiki from the command line.