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

<code>
{{wvds:lang>key}}
</code>

==== Syntax Variants ====

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

----

===== 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:

<code ini>
[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
</code>

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

<code>
Welcome to the {{wvds:lang>menu_home}}!
</code>

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

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

**Configuration:**
<code ini>
[de]
term_hash = Hashwert

[en]
term_hash = Hash
</code>

**Result:**
  * Output: "The hash value (German: Hashwert) is a cryptographic fingerprint."

==== Example 3: Inline Translation ====

**Requirement:** Quick translation without configuration entry.

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

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

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

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

==== Example 5: Configuration Values ====

**Requirement:** Read multilingual wiki title from configuration.

<code>
Welcome to {{wvds:lang>conf:title}}
</code>

**DokuWiki local.php:**
<code php>
$conf['title'] = 'de:Wissensdatenbank|en:Knowledge Base|sl:Baza znanja';
</code>

**Result (on English page):**
  * Output: "Welcome to Knowledge Base"

----

===== How It Works =====

==== Processing Pipeline ====

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

==== 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" |

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

----

===== 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:

<code ini>
[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
</code>

----

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

<note tip>
Pages with ''<nowiki>{{wvds:lang>...}}</nowiki>'' should use ''<nowiki>~~NOCACHE~~</nowiki>'' if content should change based on language.
</note>

----

===== Version History =====

^ Version ^ Date ^ Changes ^
| 1.0.0 | 2025-01-06 | Initial release |

----

===== See Also =====

  * [[wvdschunk]] - Reusable HTML chunks
  * [[wvdsif]] - Conditional content by language
  * [[flat]] - Template with language switcher

----

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

<code php>
// 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>";
}
</code>

==== Usage in Other Plugins ====

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

----

{{wvds:snippet>wvds_audit_badge}}

~~DISCUSSION~~