====== WvdS.DokuWiki.I18n Plugin ======

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

----

===== Definizione =====

Il plugin **wvdsi18n** fornisce un sistema di traduzione multilingue per pagine DokuWiki. Supporta sia file di lingua centrali che traduzioni inline, con rilevamento automatico della lingua basato sul namespace.

===== Casi d'uso =====

  * **Interfacce multilingue** - Voci di menu, pulsanti, etichette
  * **Documentazione** - Testi che devono apparire in più lingue
  * **Template** - Elementi riutilizzabili con supporto linguistico
  * **Widget** - Snippet con contenuto specifico per lingua

----

===== Sintassi =====

==== Chiave da file lingua ====

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

==== Traduzione inline ====

<code>
{{wvds:i18n>de:Testo tedesco|en:Testo inglese|it:Testo italiano}}
</code>

==== Lingua forzata ====

<code>
{{wvds:i18n:de>key}}
{{wvds:i18n:en>intro_text}}
</code>

----

===== Parametri =====

==== Sintassi chiave ====

^ Sintassi ^ Descrizione ^
| ''key'' | Cerca chiave nei file di lingua |
| ''conf:key'' | Accede a valori di configurazione DokuWiki |
| ''de:X|en:Y'' | Traduzione inline con codice lingua |

==== Lingua forzata ====

^ Sintassi ^ Descrizione ^
| ''{{wvds:i18n:de>...}}'' | Forza output tedesco |
| ''{{wvds:i18n:en>...}}'' | Forza output inglese |
| ''{{wvds:i18n:it>...}}'' | Forza output italiano |

----

===== File di lingua =====

==== Posizione ====

<code>
lib/plugins/wvdsi18n/lang/
├── de/
│   └── translations.php
├── en/
│   └── translations.php
├── sl/
│   └── translations.php
├── hr/
│   └── translations.php
└── it/
    └── translations.php
</code>

==== Formato ====

**lib/plugins/wvdsi18n/lang/it/translations.php:**
<code php>
<?php
$lang['menu_home'] = 'Home';
$lang['menu_docs'] = 'Documentazione';
$lang['menu_contact'] = 'Contatto';
$lang['menu_back'] = 'Indietro';
$lang['greeting'] = 'Benvenuto nella nostra documentazione';
</code>

----

===== Esempi =====

==== Esempio 1: Voci di menu ====

<code>
  * [[start|{{wvds:i18n>menu_home}}]]
  * [[docs:start|{{wvds:i18n>menu_docs}}]]
  * [[contatto|{{wvds:i18n>menu_contact}}]]
</code>

**Risultato (pagina italiana):**
  * Home
  * Documentazione
  * Contatto

==== Esempio 2: Traduzione inline ====

<code>
{{wvds:i18n>de:Willkommen|en:Welcome|it:Benvenuto|hr:Dobrodošli}}
</code>

**Risultato:** Visualizza il testo nella lingua del namespace corrente.

==== Esempio 3: In snippet HTML ====

**File:** ''lib/plugins/wvdssnippet/snippets/footer.html''
<code html>
<footer>
    <p>{{wvds:i18n>de:Alle Rechte vorbehalten|en:All rights reserved|it:Tutti i diritti riservati}}</p>
</footer>
</code>

==== Esempio 4: Lingua forzata ====

<code>
La versione inglese è: {{wvds:i18n:en>greeting}}
</code>

Visualizza sempre il testo in inglese, indipendentemente dal namespace corrente.

----

===== Rilevamento lingua =====

==== Rilevamento automatico ====

La lingua viene determinata dalla posizione nel namespace:

<code>
de:docs:start     → Tedesco
en:docs:start     → Inglese
it:docs:start     → Italiano
hr:docs:start     → Croato
sl:docs:start     → Sloveno
</code>

==== Priorità di fallback ====

<code>
1. Lingua del namespace corrente
2. Lingua predefinita (configurazione)
3. Prima lingua disponibile nella traduzione inline
4. Chiave come fallback (per debug)
</code>

----

===== Configurazione =====

==== Impostazioni amministratore ====

Tramite **Admin → Configurazione → wvdsi18n**:

^ Impostazione ^ Tipo ^ Default ^ Descrizione ^
| ''defaultLanguage'' | Testo | de | Lingua predefinita |
| ''langPosition'' | Numero | 0 | Posizione del codice lingua nel namespace (0 = primo) |

----

===== Integrazione =====

==== Con wvdssnippet ====

Snippet possono usare tag i18n:

<code html>
<nav>
    <a href="?id=start">{{wvds:i18n>menu_home}}</a>
    <a href="?id=docs">{{wvds:i18n>menu_docs}}</a>
</nav>
</code>

==== Con flat Template ====

Il template usa l'helper i18n per:
  * Footer multilingue
  * Titoli sidebar
  * Etichette switcher lingua

----

===== Gestione errori =====

^ Scenario ^ Comportamento ^
| Chiave non trovata | Restituisce la chiave stessa (utile per debug) |
| Lingua non disponibile | Fallback su defaultLanguage |
| Traduzione inline vuota | Usa prima lingua disponibile |
| File lingua mancante | Usa chiave come fallback |

----

===== Best practice =====

  * **Chiavi significative** - Usare nomi descrittivi: ''menu_home'' invece di ''m1''
  * **File centrali** - Usare file lingua per testi frequenti
  * **Inline per casi speciali** - Usare inline per testi unici
  * **~~NOCACHE~~** - Aggiungere a pagine con contenuto multilingue

----

===== Note sulla versione =====

^ Versione ^ Data ^ Modifiche ^
| 1.0.0 | 2026-01-06 | Prima pubblicazione |

----

===== Vedi anche =====

  * [[.:wvdscond]] - Contenuti condizionali e redirect
  * [[.:wvdssnippet]] - Blocchi HTML riutilizzabili
  * [[.:flat]] - Template con supporto multilingue

----

===== Riferimento tecnico =====

==== Classe: syntax_plugin_wvdsi18n ====

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

^ Metodo ^ Descrizione ^
| ''getType()'' | Restituisce ''substition'' |
| ''getSort()'' | Restituisce ''305'' (prima di wvdssnippet) |
| ''connectTo($mode)'' | Registra pattern ''\\{\\{wvds:i18n[^}]*>[^}]+\\}\\}'' |
| ''handle($match, ...)'' | Analizza sintassi, estrae chiave/traduzioni |
| ''render($mode, ...)'' | Restituisce testo tradotto |

==== Classe: helper_plugin_wvdsi18n ====

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

^ Metodo ^ Parametri ^ Ritorno ^ Descrizione ^
| ''detectLanguage()'' | - | string | Rileva lingua dal namespace |
| ''get()'' | $key, $lang | string | Restituisce traduzione |
| ''parseInline()'' | $text | string | Analizza formato ''de:X|en:Y'' |

----

<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][-][-]</wvds:include>
</wvds:audit>

~~DISCUSSION~~