Multilingual Templates and Modules/cs

Tato stránka vysvětluje, jak vytvářet globální, cross-wiki a vícejazyčné moduly a šablony a jak je synchronizovat napříč wiki projekty Wikimedie.
Proč je to potřeba? Protože nemáme jednu Wikipedii, máme více než 300 samostatných Wikipedií a dalších wiki projektů a pokaždé, když někdo vytvoří dobrou novou šablonu nebo Lua modul, je zkopírován a přeložen více než 300krát. Každý překladatel musí důkladně rozumět značkování MediaWiki, což z kopírování dělá velmi zdlouhavý a chybám náchylný proces, částečně proto, že autoři šablon často předpokládají, že jejich šablony budou použity pouze v jednom jazyce. Po zkopírování se původní šablony často vylepšují a každá kopie musí být aktualizována, přičemž se zachovávají všechny existující překlady. Čistě lidské náklady na kopírování šablon a modulů jsou tak vysoké, že většina z nich se buď nikdy nekopíruje, nebo se nikdy neaktualizuje, zejména u menších wikin.
Je tohle nejlepší přístup? Ne, ale je to nejlepší přístup s ohledem na současnou technologii. Aby to bylo možné na systémové úrovni, je zapotřebí rozsáhlé přepracování MediaWiki. Šablony pro více webů byly požadovány od samého začátku v roce 2001, ale moc se toho neudělalo, jednoduše proto, že se jedná o obtížně řešitelný problém. S tímto přístupem je nyní možné vytvářet vícejazyčný obsah a jakmile jej MediaWiki bude podporovat, můžeme snadno migrovat vícejazyčný obsah do nového systému bez větší námahy.
Příklady
Zde je několik příkladů modulů Lua, které byly globalizovány a jsou synchronizovány napříč wikinami pomocí nástroje Synchronizátor :
- Module:Excerpt (Q52428273-enwiki)
- Module:Transcluder (Q96679044-enwiki)
- Module:Cycling race (Q21707933-wikidatawiki)
- Module:TNT (Q28132212-mediawikiwiki)
Obecná metoda
Vytvoření obecného modulu:
- Navrhněte nebo přepracujte modul tak, aby wikiny mohly lokalizovat vše, co potřebují lokalizovat, aniž by musely upravovat zdrojový kód. Tato stránka popisuje několik technik, jak toho dosáhnout.
- Použijte nástroj Synchronizátor k zachování shody zdrojového kódu napříč wikinami projektů Wikimedie.
Osvědčené postupy
Tato část popisuje některé ze současných osvědčených postupů pro vývoj globálních modulů.
Pojmenování
Tuto sekci lze ignorovat u modulů určených k volání pouze ze šablon.
Globální moduly, které mají být používány jinými moduly, by měly být ve všech wikinách pojmenovány stejně, aby se zabránilo přerušení závislostí s jinými globálními moduly. Například pokud modul s názvem A vyžaduje modul s názvem B, ale v nějaké wiki je modul B pojmenován C, pak modul A v této wiki nebude fungovat, pokud se zdrojový kód modulu A lokálně nezmění tak, aby vyžadoval C místo B, což by znemožnilo globalizaci (modulu A).
Pokud lokální komunita neakceptuje globální název nebo je přejmenování příliš problematické, pak je řešením vytvořit "modul přesměrování" s globálním názvem, který jednoduše vyžaduje a vrací modul s lokálním názvem.
Naštěstí skutečnost, že jmenný prostor modulu je v každém jazyce pojmenován jinak, nenarušuje závislosti, protože "Module" je alias pro jmenný prostor modulu ve všech jazycích.
Master (hlavní) modul
Globální moduly by si měly vybrat jednu wiki, kde se bude provádět vývoj. Obecně se jedná o domovskou wiki modulu, ale může se z různých důvodů přesunout, například aby se zvýšila šance na nábor nových vývojářů centralizací vývoje do větší nebo vhodnější wiki.
Globální moduly by měly začínat komentářem, který obsahuje odkaz na hlavní modul, aby se snížilo riziko větvení a pomohlo se s náborem nových vývojářů (příklad).
Sandbox
Globální moduly by měly mít podstránku /sandbox, kde je možné testovat změny před jejich nasazením do hlavního modulu a ostatních wikin (příklad).
Zkušební testy
Globální moduly by měly mít podstránku /testcases s kvalitními jednotkovými testy, aby byla zajištěna vysoká kvalita a stabilita modulu (příklad). Zkušební testy by měly:
- Používat Module:ScribuntoUnit
- Spustit s hlavním modulem i sandboxovou verzí, abychom mohli porovnat výsledky (příklad)
- Použít require('strict') , k zabránění nechtěnému použití nedeklarovaných proměnných.
- Výsledky vypisat na stránku modulu
/testcases/doc
i na hlavní stránku/doc
, aby se chyby odhalily co nejdříve.
Dokumentace
Globální moduly by měly mít podstránku /doc s dokumentací všech veřejných funkcí modulu (příklad) a sekci s testovacími případy běžícími pro primární i sandbox verzi modulu (příklad).
Konfigurace
Globální moduly, které vyžadují konfiguraci, by měly mít samostatný submodul /config, aby se zabránilo lokálním wikinám v úpravě zdrojového kódu za účelem konfigurace modulu (příklad).
Synchronizace
Jakmile je možné modul zkopírovat beze změny do jiných wikin, lze k jeho zkopírování a synchronizaci napříč všemi wikinami Wikimedie použít nástroj Synchronizátor .
Zpětná kompatibilita
Globální moduly by obecně měly zajišťovat zpětnou kompatibilitu vývoje, protože změny, které nejsou zpětně kompatibilní, často vyžadují ruční aktualizace každé wiki, šablony a modulu, který daný modul používá.
Lokalizace parametrů šablony
Parametry globálních modulů mohou být lokalizovány volajícími šablonami. Uvažujme například následující modul, který jednoduše vypíše zadaný text (nebo "Example", pokud žádný není zadán):
local p = {}
function p.main(frame)
local args = frame.args
local text = args['text'] or 'Example'
return text
end
return p
Španělská šablona by pak lokalizovala modul takto:
{{#invoke:Example|main
| text = {{{texto|Ejemplo}}}
}}
Všimněte si, že šablona nejen lokalizuje název parametru "text" ("texto" znamená ve španělštině "text"), ale také výchozí text ("Ejemplo" znamená ve španělštině "Example" (příklad)).
Viz Plantilla:Extracto pro reálný případ šablony, která lokalizuje globální modul pomocí této techniky. Viz také Template:Excerpt pro případ, kdy je globální modul lokalizován do anglické Wikipedie, což ukazuje, že lokalizace není vždy totéž co překlad.
Lokalizace uživatelsky čitelných řetězců
Mnoho modulů potřebuje vytvářet uživatelsky čitelné řetězce, jako jsou chybové zprávy a prvky rozhraní (jako jsou tlačítka). Pevné kódování textu těchto řetězců nutí ostatní wikiny upravovat kód za účelem jejich lokalizace, což brání globalizaci. Aby se tomu zabránilo, vývojáři by měli poskytnout způsoby, jak lokalizovat uživatelsky čitelné řetězce, aniž by bylo nutné upravovat samotný kód. Tato část vysvětluje několik způsobů, jak toho dosáhnout.
Parametry šablon
Uživatelsky čitelné řetězce lze lokalizovat pomocí parametrů šablony při volání modulu. Tento přístup je vhodný, když:
- Text se pravděpodobně bude lišit s každým voláním šablony.
- Uživatelé pravděpodobně při volání šablony změní text.
- Text pravděpodobně obsahuje magické slovo, volání šablony, funkci parseru nebo nějaký jiný wiki prvek
Příklad modulu využívajícího tento přístup by byl:
local p = {}
function p.main(frame)
local args = frame.args
local text = args['text'] or 'Example'
return text
end
return p
Tímto způsobem může každá šablona upravit text při volání modulu, například takto:
{{#invoke:Example|main
| text = Ejemplo
}}
Všimněte si, že v tomto příkladu, pokud šablona volá modul bez zadání parametru text
, použije se pevně zakódovaný anglický text 'Example'.
To není nutné.
Moduly mohou vyžadovat, aby volající šablony nastavili parametr text
, a pokud tak neučiní, vyvolají chybu.
Často je však výhodnější mít záložní řešení.
Konfigurační soubor
Dalším způsobem, jak lokalizovat uživatelsky čitelné řetězce, je vytvořit samostatnou podstránku /config. Tento přístup je vhodný, když:
- Modul je určen k volání mnoha šablonami na wiki, což umožňuje lokalizaci provést pouze jednou a poté ji znovu použít.
- Je třeba lokalizovat mnoho zpráv, takže je snazší je mít všechny pohromadě na svém místě.
- Soubor /config je již potřeba z jiných důvodů, takže ho můžeme stejně tak použít i pro lokalizaci.
Příklad modulu využívajícího tento přístup by byl:
local config = require('Module:Example/config')
local p = {}
function p.main(frame)
local text = config.text or 'Example'
return text
end
return p
Pak by wiki mohly vytvářet soubory /config, jako je tento:
return {
text = 'Ejemplo'
}
Překladové tabulky
Dalším způsobem, jak lokalizovat uživatelsky čitelné řetězce, je prostřednictvím centrální překladové tabulky na Commons. Tento přístup je vhodný, když:
- Řetězce by se měly lišit v závislosti na preferovaném jazyce uživatele, nikoli v jazyce wiki nebo stránky.
- Chceme centralizovat lokalizační úsilí na jedné stránce.
Modul Module:TNT byl vytvořen speciálně pro získávání řetězců z překladových tabulek. Příklad modulu používajícího TNT by mohl vypadat takto:
local TNT = require('Module:TNT')
local p = {}
function p.main(frame)
local text = TNT.format('I18n/Example', 'text')
return text
end
return p
Jednoduchý, ale reálný příklad překladové tabulky se dvěma zprávami, z nichž každá má jeden parametr, naleznete v souboru Data:I18n/Template:Graphs.tab. Je důležité ukládat parametry jako součást řetězců, protože v mnoha jazycích by musel být parametr umístěn na jiné pozici v řetězci podle norem daného jazyka.
Překladové tabulky by měly začínat předponou "Data:I18n/...", aby se oddělily od ostatních typů tabulkových dat. Pokud zpráva ještě nebyla lokalizována, TNT se vrátí k angličtině (nebo jinému záložnímu jazyku definovanému v záložní sekvenci daného jazyka). TNT také podporuje všechny standardní lokalizační konvence, jako například {{PLURAL|...}} a další parametry .
Jednou z nevýhod tohoto přístupu je, že vyžaduje instalaci a nastavení Extension:JsonConfig , což se na wiki stránkách jiných platforem nemuselo dělat, což omezuje možnost opětovného použití těchto modulů na wiki stránkách třetích stran.
Zprávy MediaWiki
V některých případech může samotná MediaWiki (nebo nějaké rozšíření) obsahovat zprávy, které potřebujeme, již lokalizované. Například pokud potřebujeme řetězec "New page" (nová stránka), můžeme použít MediaWiki:Newpage, například takto:
local p = {}
function p.main(frame)
local msg = mw.message.new('newpage')
local text = msg:plain()
return text
end
return p
Seznam všech dostupných zpráv naleznete v sekci Special:AllMessages.
Vše výše uvedené
V závislosti na případu lze všechny výše uvedené metody kombinovat. Například zprávy MediaWiki mohou být použity, pokud jsou k dispozici, a pokud ne, je dotazována překladová tabulka nebo konfigurační soubor a pokud se tam nenajde žádná lokalizace, použije se pevně zakódovaný anglický text, pokud jej nepřepíše parametr šablony.
Kombinace několika metod může být efektivní, ale výhody by měly být zváženy oproti nevýhodám zvýšené složitosti, která může způsobit ztrátu výkonu a chyby, a také větší obtíže s údržbou kódu a náborem nových vývojářů.
Template data
Parametry šablony se obvykle ukládají jako blok JSON templatedata uvnitř podstránky šablony s hodnotou /doc
.
Díky tomu je překlad pohodlný, ale když je do globální šablony přidán nový parametr, je nutné aktualizovat všechny stránky s kódem /doc
v každém jazyce.
Module:TNT s tím pomáhá automatickým generováním bloku templatedata z tabulky uložené na Commons.
Vložením následujícího řádku do každé podstránky /doc
se pomocí tabulky Data:Templatedata/Graph:Lines.tab vygenerují všechny potřebné informace o templatedata v každém jazyce.
I když místní komunita nepřeložila kompletní dokumentaci k šabloně, bude si moci prohlédnout všechny parametry šablony, centrálně aktualizované.
{{#invoke:TNT|doc|Graph:Lines}}
Související odkazy
- Návrh na seznam přání 2019 (40 hlasů)
- T122086 - RFC: Sdílení šablon a modulů mezi wikinami - verze pro chudé (původní nápad pro tohoto robota)
- T121470 - tiket Centrální globální repozitář pro šablony, moduly Lua a gadgety (hlavní tiket pro vše, co lze sdílet napříč weby)
- T41610 - Scribunto by mělo podporovat globální volání modulů.
- Globální šablony/Navrhovaná specifikace, zkrácená verze - návrh na komplexní implementaci podobné myšlenky, bez nutnosti speciálních nástrojů a s plnou podporou v jádru a rozšířeních MediaWiki
- Global gadgets - gadgety, které jsou navrženy a připraveny k použití v jakékoli wiki