====== WvdS.DokuWiki.i18n Plugin ======

**Plugin:** wvdsi18n\\
**Version:** 1.0.0\\
**Namespace:** ''lib/plugins/wvdsi18n/''\\
**Author:** Wolfgang van der Stille <zeljko.petrusic@outlook.de>\\
**License:** GPL 2

----

<note important>
**Migration from wvdslang:** This plugin replaces the old ''wvdslang'' plugin.
Redirect functionality has been moved to the ''wvdscond'' plugin (Separation of Concerns).
</note>

----

===== Definition =====

The **wvdsi18n** plugin provides internationalization functions for multilingual content:

  * **Translation keys** - From CSV file
  * **Inline translations** - ''de:Text|en:Text''
  * **Config values** - With multilingual parsing
  * **Template values** - With multilingual parsing

===== Use Cases =====

  * **Multilingual navigation** - Menu texts in different languages
  * **Translatable UI elements** - Buttons, labels, notices
  * **Template integrations** - Sidebar, footer, header
  * **Centralized translations** - All texts in one CSV file

----

===== Syntax =====

==== Translation Key ====

<code>
{{wvds:i18n>menu_home}}
{{wvds:i18n>menu_contact}}
</code>

Loads value from ''i18n.csv'' based on current language.

==== Explicit Language ====

<code>
{{wvds:i18n:de>menu_home}}
{{wvds:i18n:en>menu_home}}
</code>

Forces a specific language, regardless of browser.

==== Inline Translation ====

<code>
{{wvds:i18n>de:Ja|en:Yes|sl:Da}}
{{wvds:i18n>de:Speichern|en:Save|sl:Shrani}}
</code>

Direct translation without CSV file.

==== Config Value ====

<code>
{{wvds:i18n>conf:title}}
{{wvds:i18n>conf:tagline}}
</code>

Reads DokuWiki configuration with multilingual parsing.

==== Template Config ====

<code>
{{wvds:i18n>tpl:footerText}}
{{wvds:i18n>tpl:topSidebarTitle}}
</code>

Reads template configuration with multilingual parsing.

----

===== CSV Format =====

Translations are stored in ''lib/plugins/wvdsi18n/i18n.csv'':

<code>
key,de,en,sl,it,hr
menu_home,Startseite,Home,Domov,Home,Početna
menu_contact,Kontakt,Contact,Kontakt,Contatto,Kontakt
button_save,Speichern,Save,Shrani,Salva,Spremi
</code>

^ Column ^ Description ^
| ''key'' | Unique key |
| ''de'' | German translation |
| ''en'' | English translation |
| ... | Additional languages |

----

===== Language Detection =====

Language is determined in the following order:

  - **Namespace path** - ''de:start'' → de
  - **Browser header** - ''Accept-Language: de-DE'' → de
  - **DokuWiki language** - ''$conf['lang']''
  - **Plugin default** - ''defaultLang'' configuration

----

===== Configuration =====

^ Option ^ Default ^ Description ^
| ''enabled'' | 1 | Enable plugin |
| ''languages'' | de,en,sl,it,hr | Available languages |
| ''defaultLang'' | en | Default language (fallback) |
| ''langPosition'' | 0 | Language position in namespace (0 = first level) |

----

===== Examples =====

==== Example 1: Navigation ====

<code>
===== {{wvds:i18n>menu_navigation}} =====
  * [[.:start|{{wvds:i18n>menu_home}}]]
  * [[.:docs:index|{{wvds:i18n>menu_docs}}]]
  * [[.:contact|{{wvds:i18n>menu_contact}}]]
</code>

**Result (browser: en):**
  * Home
  * Documentation
  * Contact

==== Example 2: Inline in Buttons ====

<code>
<button>{{wvds:i18n>de:Absenden|en:Submit|sl:Pošlji}}</button>
</code>

==== Example 3: Footer with Template Config ====

<code>
<footer>
{{wvds:i18n>tpl:footerText}}
</footer>
</code>

==== Example 4: Explicit Language for Links ====

<code>
Languages: [[.:de:start|{{wvds:i18n:de>menu_home}}]] |
           [[.:en:start|{{wvds:i18n:en>menu_home}}]] |
           [[.:sl:start|{{wvds:i18n:sl>menu_home}}]]
</code>

**Result:**
  * Languages: Startseite | Home | Domov

----

===== Integration in Templates =====

==== PHP Usage ====

<code php>
<?php
// Load helper
$helper = plugin_load('helper', 'wvdsi18n');

if ($helper) {
    // Get translation
    echo hsc($helper->get('menu_home'));

    // Explicit language
    echo hsc($helper->get('menu_home', 'en'));

    // Parse inline
    echo hsc($helper->parseMultilang('de:Ja|en:Yes'));

    // Template config
    echo hsc($helper->getTplConfig('footerText'));
}
?>
</code>

----

===== Migration from wvdslang =====

^ Old (wvdslang) ^ New (wvdsi18n) ^ Status ^
| ''{{wvds:lang>key}}'' | ''{{wvds:i18n>key}}'' | Syntax changed |
| ''{{wvds:lang:de>key}}'' | ''{{wvds:i18n:de>key}}'' | Syntax changed |
| ''{{wvds:lang>de:X|en:Y}}'' | ''{{wvds:i18n>de:X|en:Y}}'' | Syntax changed |
| ''{{wvds:redirect>...}}'' | ''{{wvds:redirect ...}}'' | Moved to wvdscond |

==== Search and Replace ====

<code>
Old: {{wvds:lang>
New: {{wvds:i18n>

Old: {{wvds:lang:
New: {{wvds:i18n:
</code>

----

===== Version Notes =====

^ Version ^ Date ^ Changes ^
| 1.0.0 | 2026-01-29 | Initial release (successor to wvdslang) |

----

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

  * [[.:wvdscond]] - Conditional content and redirects
  * [[.:wvdssnippet]] - Reusable HTML building blocks
  * [[.:flat]] - Template with language switcher

----

===== Technical Reference =====

==== Class: syntax_plugin_wvdsi18n ====

**File:** ''lib/plugins/wvdsi18n/syntax.php''

^ Method ^ Description ^
| ''getType()'' | Returns ''substition'' |
| ''getSort()'' | Returns ''100'' |
| ''connectTo($mode)'' | Registers i18n patterns |
| ''handle($match, ...)'' | Parses syntax and extracts content |
| ''render($mode, ...)'' | Returns translated text |

==== Class: helper_plugin_wvdsi18n ====

**File:** ''lib/plugins/wvdsi18n/helper.php''

^ Method ^ Description ^
| ''get($key, $lang)'' | Gets translation for key |
| ''parseMultilang($value, $lang)'' | Parses ''de:X|en:Y'' format |
| ''getConfig($key, $lang)'' | Gets DokuWiki config with parsing |
| ''getTplConfig($key, $lang)'' | Gets template config with parsing |
| ''detectLanguage()'' | Detects current language |
| ''getLanguages()'' | Returns configured languages |

----

<wvds:audit stack="doku" title="wvdsi18n Plugin">
  <wvds:include ref="code:qualitaet" critical="true">[x][x][x][x]</wvds:include>
  <wvds:include ref="stacks:dokuwiki-php">[x][x][x][x][x]</wvds:include>
  <wvds:include ref="sicherheit:kritis" critical="true">[x][x][x][x][x]</wvds:include>
</wvds:audit>

~~DISCUSSION~~