====== WvdS.DokuWiki.Lang Vticnik ======

**Vticnik:** wvdslang\\
**Verzija:** 1.0.0\\
**Imenski prostor:** ''lib/plugins/wvdslang/''\\
**Avtor:** Wolfgang van der Stille <zeljko.petrusic@outlook.de>\\
**Licenca:** GPL 2

----

===== Definicija =====

Vticnik **wvdslang** omogoca vecjezicne prevode v DokuWiki straneh s centraliziranim upravljanjem. Rešuje problem raztresenih prevodov in ponuja varno alternativo PHP kodi v straneh.

===== Primeri uporabe =====

  * **Vecjezicni meniji** - Stranska navigacija v razlicnih jezikih
  * **Lokalizirano besedilo** - Centralno upravljanje ponavljajocega besedila
  * **Integracija predlog** - Uporaba prevodov v predlogah
  * **Tehnicna dokumentacija** - Sklicevanje na izraze v vec jezikih
  * **Konfiguracijske vrednosti** - Branje vecjezicnih nastavitev wikija

----

===== Sintaksa =====

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

==== Variante sintakse ====

^ Sintaksa ^ Opis ^ Primer ^
| ''<nowiki>{{wvds:lang>key}}</nowiki>'' | Prevod iz INI konfiguracije | ''<nowiki>{{wvds:lang>menu_home}}</nowiki>'' |
| ''<nowiki>{{wvds:lang:CODE>key}}</nowiki>'' | Ekspliciten jezik | ''<nowiki>{{wvds:lang:en>menu_home}}</nowiki>'' |
| ''<nowiki>{{wvds:lang>de:X|en:Y}}</nowiki>'' | Vgrajeni prevod | ''<nowiki>{{wvds:lang>de:Ja|en:Yes}}</nowiki>'' |
| ''<nowiki>{{wvds:lang>conf:setting}}</nowiki>'' | DokuWiki konfiguracija | ''<nowiki>{{wvds:lang>conf:title}}</nowiki>'' |
| ''<nowiki>{{wvds:lang>tpl:setting}}</nowiki>'' | Konfiguracija predloge | ''<nowiki>{{wvds:lang>tpl:footerText}}</nowiki>'' |

----

===== Parametri =====

==== Parametri sintakse ====

^ Parameter ^ Tip ^ Opis ^
| **key** | string | Kljuc iz INI konfiguracije |
| **CODE** | string | ISO 639-1 jezikovna koda (de, en, sl, itd.) |
| **conf:** | predpona | Predpona za DokuWiki konfiguracijske vrednosti |
| **tpl:** | predpona | Predpona za konfiguracijske vrednosti predloge |

==== Konfiguracijske nastavitve ====

Preko **Skrbnik → Konfiguracija → wvdslang**:

^ Nastavitev ^ Tip ^ Privzeto ^ Opis ^
| ''enabled'' | Vklop/Izklop | Vklop | Omogoci/onemogoci vticnik |
| ''languages'' | Besedilo | de,en | Razpolozljivi jeziki (loceni z vejico) |
| ''defaultLang'' | Besedilo | de | Privzeti jezik za nadomestno vrednost |
| ''langPosition'' | Število | 0 | Polozaj jezika v poti imenskega prostora (0 = prva raven) |
| ''translations'' | Textarea | //(prazno)// | Prevodi v INI formatu |

----

===== Format prevodov =====

==== INI struktura ====

Prevodi so shranjeni v INI formatu v konfiguraciji vticnika:

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

==== Pravila formata ====

^ Pravilo ^ Primer ^
| Odsek z jezikovno kodo | ''[de]'', ''[en]'', ''[sl]'' |
| Kljuc = Vrednost | ''menu_home = Domov'' |
| Narekovaji niso potrebni | ''text = Moje besedilo'' |
| Presledki so dovoljeni | ''long_text = To je dolgo besedilo'' |
| Vecvrsticno ni mogoce | Uporabite ''\\n'' za prelome vrstic |

----

===== Primeri =====

==== Primer 1: Enostaven prevod ====

**Zahteva:** Besedilo menija naj se prikaže v trenutnem jeziku.

<code>
Dobrodošli na {{wvds:lang>menu_home}}!
</code>

**Rezultat (pri sl:start):**
  * Izhod: "Dobrodošli na Domov!"

**Rezultat (pri en:start):**
  * Izhod: "Dobrodošli na Home!"

==== Primer 2: Ekspliciten jezik za slovar ====

**Zahteva:** Prikazi angleški izraz v slovenski dokumentaciji.

<code>
Zgoščena vrednost (angl.: {{wvds:lang:en>term_hash}}) je kriptografski prstni odtis.
</code>

**Konfiguracija:**
<code ini>
[sl]
term_hash = Zgoščena vrednost

[en]
term_hash = Hash
</code>

**Rezultat:**
  * Izhod: "Zgoščena vrednost (angl.: Hash) je kriptografski prstni odtis."

==== Primer 3: Vgrajeni prevod ====

**Zahteva:** Hiter prevod brez konfiguracijskega vnosa.

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

**Rezultat:**
  * Na nemški strani: "Weiter"
  * Na angleški strani: "Continue"
  * Na slovenski strani: "Naprej"

==== Primer 4: V HTML blokih ====

**Zahteva:** Prevodi v stranski vrstici s HTML strukturo.

<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>
Vticnik deluje tudi znotraj ''<html>...</html>'' blokov, ker nadomešca pred obdelavo HTML.
</note>

==== Primer 5: Konfiguracijske vrednosti ====

**Zahteva:** Preberi vecjezicni naslov wikija iz konfiguracije.

<code>
Dobrodošli v {{wvds:lang>conf:title}}
</code>

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

**Rezultat (na slovenski strani):**
  * Izhod: "Dobrodošli v Baza znanja"

----

===== Kako deluje =====

==== Procesni cevovod ====

<code>
1. Zaznava sintakse
   └── Najde vse {{wvds:lang>...}} oznake na strani

2. Zaznava jezika
   └── Preveri pot imenskega prostora (npr. sl:stran → "sl")
   └── Ce ni najdeno: Brskalnikova Accept-Language glava
   └── Ce ni najdeno: Privzeti jezik iz konfiguracije

3. Razrešitev kljuca
   ├── conf:* → Bere iz $conf[...]
   ├── tpl:* → Bere iz tpl_getConf(...)
   ├── de:X|en:Y → Razcleni vgrajeni format
   └── key → Išce v INI prevodih

4. Ekstrakcija vrednosti
   └── Za format s crtami: Izvlece vrednost za trenutni jezik
   └── Za preprosto vrednost: Vrne vrednost neposredno
   └── Nadomestna vrednost: defaultLang ali sam kljuc

5. Zamenjava
   └── Zamenja oznako z najdeno vrednostjo
</code>

==== Zaznava jezika ====

Jezik je zaznan v naslednji prioriteti:

^ Prioriteta ^ Vir ^ Primer ^
| 1 | Pot imenskega prostora | ''sl:dokumenti:start'' → "sl" |
| 2 | Accept-Language glava | ''sl,en;q=0.9,de;q=0.8'' → "sl" |
| 3 | Privzeti jezik | ''defaultLang = sl'' → "sl" |

<note>
Polozaj v imenskem prostoru je dolocen z ''langPosition''. Pri ''langPosition=0'' se uporabi prvi segment (npr. ''**sl**:dokumenti:start'').
</note>

----

===== Konfiguracija =====

==== Skrbniške nastavitve ====

Preko **Skrbnik → Konfiguracija → wvdslang**:

=== Osnovne nastavitve ===

^ Nastavitev ^ Tip ^ Privzeto ^ Opis ^
| ''enabled'' | Vklop/Izklop | Vklop | Omogoci vticnik |
| ''languages'' | Besedilo | de,en | Razpolozljivi jeziki |
| ''defaultLang'' | Besedilo | de | Privzeti jezik |
| ''langPosition'' | Število | 0 | Polozaj jezika v imenskem prostoru |

=== Prevodi ===

Textarea ''translations'' vsebuje vse prevode v INI formatu:

<code ini>
[de]
; Navigacija
menu_home = Startseite
menu_docs = Dokumentation
menu_contact = Kontakt
menu_back = Zurück

; Splošno
site_welcome = Willkommen
site_footer = © 2025 Moje podjetje

[en]
; Navigation
menu_home = Home
menu_docs = Documentation
menu_contact = Contact
menu_back = Back

; General
site_welcome = Welcome
site_footer = © 2025 My Company

[sl]
; Navigacija
menu_home = Domov
menu_docs = Dokumentacija
menu_contact = Kontakt
menu_back = Nazaj

; Splošno
site_welcome = Dobrodošli
site_footer = © 2025 Moje podjetje
</code>

----

===== Obravnava napak =====

==== Vedenje pri manjkajocem kljucu ====

^ Scenarij ^ Vedenje ^
| Kljuc ni najden | Vrne sam kljuc |
| Jezik ni v INI | Nadomestna vrednost na ''defaultLang'' |
| Nadomestna vrednost ni na voljo | Vrne kljuc |
| Neveljaven format | Vrne original |

==== Razhroščevanje ====

Ce se pojavijo tezave, preverite:

  * Ali je vticnik omogocen? (Skrbnik → Vticniki)
  * Ali so prevodi pravilno formatirani? (INI sintaksa)
  * Ali je vrednost ''langPosition'' pravilna?
  * Ali jezik obstaja na seznamu ''languages''?

----

===== Zmogljivost =====

==== Priporocila ====

| Scenarij | Priporocilo |
| Malo prevodov (<50) | Normalna uporaba |
| Veliko prevodov (50-500) | Združite po podrocju |
| Zelo veliko prevodov (>500) | Razdelite v wvdschunk |

==== Predpomnjenje ====

<note tip>
Strani z ''<nowiki>{{wvds:lang>...}}</nowiki>'' naj uporabljajo ''<nowiki>~~NOCACHE~~</nowiki>'', ce se mora vsebina spreminjati glede na jezik.
</note>

----

===== Zgodovina verzij =====

^ Verzija ^ Datum ^ Spremembe ^
| 1.0.0 | 2025-01-06 | Zacetna izdaja |

----

===== Glej tudi =====

  * [[wvdschunk]] - Veckratno uporabni HTML bloki
  * [[wvdsif]] - Pogojna vsebina po jeziku
  * [[flat]] - Predloga s preklopnikom jezika

----

===== Tehnicna referenca =====

==== Razred: syntax_plugin_wvdslang ====

**Datoteka:** ''lib/plugins/wvdslang/syntax.php''

^ Metoda ^ Opis ^
| ''getType()'' | Vrne ''substition'' |
| ''getSort()'' | Vrne ''305'' (pred wvdschunk) |
| ''connectTo($mode)'' | Registrira vzorec ''\\{\\{wvds:lang[^}]*>[^}]+\\}\\}'' |
| ''handle($match, ...)'' | Razcleni sintakso, izvlece kljuc in jezik |
| ''render($mode, ...)'' | Zamenja oznako s prevedeno vrednostjo |

==== Razred: helper_plugin_wvdslang ====

**Datoteka:** ''lib/plugins/wvdslang/helper.php''

^ Metoda ^ Parametri ^ Vrne ^ Opis ^
| ''getLang()'' | - | string | Doloci trenutni jezik |
| ''get()'' | $key, $lang=null | string | Vrne prevod |
| ''parseTranslations()'' | $ini | array | Razcleni INI v polje |
| ''parseValue()'' | $value, $lang | string | Izvlece jezikovno vrednost iz formata s crtami |

==== Uporaba v predlogah ====

<code php>
// V datotekah predlog (main.php, itd.)
$helper = plugin_load('helper', 'wvdslang');
if ($helper) {
    $lang = $helper->getLang();
    $homeText = $helper->get('menu_home');
    echo "<a href='?id=start'>$homeText</a>";
}
</code>

==== Uporaba v drugih vticnikih ====

<code php>
// V drugih vticnikih
$langHelper = plugin_load('helper', 'wvdslang');
if ($langHelper) {
    $translated = $langHelper->get('my_key');
}
</code>

----

{{wvds:snippet>wvds_audit_badge}}

~~DISCUSSION~~