WvdS.DokuWiki.Lang Plugin

Plugin: wvdslang
Version: 1.0.0
Namespace: lib/plugins/wvdslang/
Author: Wolfgang van der Stille zeljko.petrusic@outlook.de
License: GPL 2

Definition

The wvdslang plugin enables multilingual translations in DokuWiki pages with centralized management. It solves the problem of scattered translations and provides a secure alternative to PHP code in pages.

Use Cases

Multilingual Menus - Sidebar navigation in different languages
Localized Text - Manage recurring text centrally
Template Integration - Use translations in templates
Technical Documentation - Reference terms in multiple languages
Configuration Values - Read multilingual wiki settings

Syntax

{{wvds:lang>key}}

Syntax Variants

Syntax	Description	Example
`{{wvds:lang>key}}`	Translation from INI configuration	`{{wvds:lang>menu_home}}`
`{{wvds:lang:CODE>key}}`	Explicit language	`{{wvds:lang:en>menu_home}}`
`{{wvds:lang>de:X\|en:Y}}`	Inline translation	`{{wvds:lang>de:Ja\|en:Yes}}`
`{{wvds:lang>conf:setting}}`	DokuWiki configuration	`{{wvds:lang>conf:title}}`
`{{wvds:lang>tpl:setting}}`	Template configuration	`{{wvds:lang>tpl:footerText}}`

Parameters

Syntax Parameters

Parameter	Type	Description
key	string	Key from INI configuration
CODE	string	ISO 639-1 language code (de, en, sl, etc.)
conf:	prefix	Prefix for DokuWiki configuration values
tpl:	prefix	Prefix for template configuration values

Configuration Settings

Via Admin → Configuration → wvdslang:

Setting	Type	Default	Description
`enabled`	On/Off	On	Enable/disable plugin
`languages`	Text	de,en	Available languages (comma-separated)
`defaultLang`	Text	de	Default language for fallback
`langPosition`	Number	0	Language position in namespace path (0 = first level)
`translations`	Textarea	(empty)	Translations in INI format

Translation Format

INI Structure

Translations are stored in INI format in the plugin configuration:

[de]
menu_home = Startseite
menu_contact = Kontakt
menu_back = Zurück
site_welcome = Willkommen auf unserer Seite
 
[en]
menu_home = Home
menu_contact = Contact
menu_back = Back
site_welcome = Welcome to our site
 
[sl]
menu_home = Domov
menu_contact = Kontakt
menu_back = Nazaj
site_welcome = Dobrodošli na naši strani

Format Rules

Rule	Example
Section with language code	`[de]`, `[en]`, `[sl]`
Key = Value	`menu_home = Home`
No quotes needed	`text = My Text`
Spaces allowed	`long_text = This is a long text`
Multiline not possible	Use `\\n` for line breaks

Examples

Example 1: Simple Translation

Requirement: Menu text should display in current language.

Welcome to the {{wvds:lang>menu_home}}!

Result (at en:start):

Output: „Welcome to the Home!“

Result (at de:start):

Output: „Welcome to the Startseite!“

Example 2: Explicit Language for Glossary

Requirement: Show German term in English documentation.

The hash value (German: {{wvds:lang:de>term_hash}}) is a cryptographic fingerprint.

Configuration:

[de]
term_hash = Hashwert
 
[en]
term_hash = Hash

Result:

Output: „The hash value (German: Hashwert) is a cryptographic fingerprint.“

Example 3: Inline Translation

Requirement: Quick translation without configuration entry.

{{wvds:lang>de:Weiter|en:Continue|sl:Naprej}}

Result:

On German page: „Weiter“
On English page: „Continue“
On Slovenian page: „Naprej“

Example 4: In HTML Blocks

Requirement: Translations in sidebar with HTML structure.

<html>
<nav class="main-menu">
    <ul>
        <li><a href="?id=start">{{wvds:lang>menu_home}}</a></li>
        <li><a href="?id=contact">{{wvds:lang>menu_contact}}</a></li>
    </ul>
</nav>
</html>

The plugin also works within <html>…</html> blocks, as it replaces before HTML processing.

Example 5: Configuration Values

Requirement: Read multilingual wiki title from configuration.

Welcome to {{wvds:lang>conf:title}}

DokuWiki local.php:

$conf['title'] = 'de:Wissensdatenbank|en:Knowledge Base|sl:Baza znanja';

Result (on English page):

Output: „Welcome to Knowledge Base“

How It Works

Processing Pipeline

1. Syntax Detection
   └── Finds all {{wvds:lang>...}} tags in the page

2. Language Detection
   └── Checks namespace path (e.g., en:page → "en")
   └── If not found: Browser Accept-Language header
   └── If not found: Default language from configuration

3. Key Resolution
   ├── conf:* → Reads from $conf[...]
   ├── tpl:* → Reads from tpl_getConf(...)
   ├── de:X|en:Y → Parses inline format
   └── key → Searches in INI translations

4. Value Extraction
   └── For pipe format: Extracts value for current language
   └── For simple value: Returns value directly
   └── Fallback: defaultLang or key itself

5. Replacement
   └── Replaces tag with found value

Language Detection

Language is detected in the following priority:

Priority	Source	Example
1	Namespace path	`en:docs:start` → „en“
2	Accept-Language header	`en-US,en;q=0.9,de;q=0.8` → „en“
3	Default language	`defaultLang = en` → „en“

The position in namespace is determined by langPosition. With langPosition=0, the first segment is used (e.g., en:docs:start).

Configuration

Admin Settings

Via Admin → Configuration → wvdslang:

Basic Settings

Setting	Type	Default	Description
`enabled`	On/Off	On	Enable plugin
`languages`	Text	de,en	Available languages
`defaultLang`	Text	de	Default language
`langPosition`	Number	0	Language position in namespace

Translations

The translations textarea contains all translations in INI format:

[de]
; Navigation
menu_home = Startseite
menu_docs = Dokumentation
menu_contact = Kontakt
menu_back = Zurück

; General
site_welcome = Willkommen
site_footer = © 2025 My Company
 
[en]
; Navigation
menu_home = Home
menu_docs = Documentation
menu_contact = Contact
menu_back = Back

; General
site_welcome = Welcome
site_footer = © 2025 My Company

Error Handling

Behavior for Missing Keys

Scenario	Behavior
Key not found	Returns the key itself
Language not in INI	Fallback to `defaultLang`
No fallback available	Returns the key
Invalid format	Returns the original

Debugging

If problems occur, check:

Is the plugin enabled? (Admin → Plugins)
Are translations correctly formatted? (INI syntax)
Is the langPosition value correct?
Does the language exist in the languages list?

Performance

Recommendations

Scenario	Recommendation
Few translations (<50)	Normal usage
Many translations (50-500)	Group by area
Very many translations (>500)	Split into wvdschunk

Caching

Pages with {{wvds:lang>...}} should use ~~NOCACHE~~ if content should change based on language.

Version History

Version	Date	Changes
1.0.0	2025-01-06	Initial release

Technical Reference

Class: syntax_plugin_wvdslang

File: lib/plugins/wvdslang/syntax.php

Method	Description
`getType()`	Returns `substition`
`getSort()`	Returns `305` (before wvdschunk)
`connectTo($mode)`	Registers pattern `\\{\\{wvds:lang[^}]*>[^}]+\\}\\}`
`handle($match, …)`	Parses syntax, extracts key and language
`render($mode, …)`	Replaces tag with translated value

Class: helper_plugin_wvdslang

File: lib/plugins/wvdslang/helper.php

Method	Parameters	Returns	Description
`getLang()`	-	string	Determines current language
`get()`	$key, $lang=null	string	Returns translation
`parseTranslations()`	$ini	array	Parses INI into array
`parseValue()`	$value, $lang	string	Extracts language value from pipe format

Usage in Templates

// In template files (main.php, etc.)
$helper = plugin_load('helper', 'wvdslang');
if ($helper) {
    $lang = $helper->getLang();
    $homeText = $helper->get('menu_home');
    echo "<a href='?id=start'>$homeText</a>";
}

Usage in Other Plugins

// In other plugins
$langHelper = plugin_load('helper', 'wvdslang');
if ($langHelper) {
    $translated = $langHelper->get('my_key');
}

Inhaltsverzeichnis