Nápověda: Systémové zprávy

From mediawiki.org
This page is a translated version of the page Help:System message and the translation is 97% complete.
PD Poznámka: Editací této stránky souhlasíte s uvolněním svého příspěvku pod licencí CC0. Více informací se dočtete na stránce Public Domain Help Pages.
PD
i18n docs
Označený formulář Special:Upload, zobrazující různé systémové zprávy.

Systémová zpráva je úryvek prostého textu (nowiki), wikitext, CSS nebo JavaScript, který lze použít k přizpůsobení chování MediaWiki a jeho zobrazení pro každý jazyk a lokální počítačový software. MediaWiki používá zprávy pro jakoukoli část uživatelského rozhraní, což umožňuje internacionalizaci a lokalizaci uživatelského rozhraní MediaWiki pro jádro i rozšíření. Všechny zprávy používané v MediaWiki jsou definovány v souboru zpráv.

Přepisování zpráv na wiki

Zprávy lze přepsat z jejich výchozích hodnot úpravou na wiki. Každá zpráva má wiki stránku v oboru názvů MediaWiki s klíčem zprávy jako názvem stránky. Například zpráva "aboutsite" je uložena na MediaWiki:aboutsite. Ve výchozím nastavení je tento obor názvů omezen na úpravy, pokud uživatel nemá oprávnění "editinterface" (rozhraní pro úpravy). Seznam všech stránek se zprávami naleznete na Special:AllMessages. Úpravy zpráv rozhraní jsou obvykle jednoduché, stejně jako úpravy normální stránky wiki, ale jsou omezeny na uživatele s povolením editinterface, které je ve výchozím nastavení přiřazeno správcům (a správcům rozhraní).

Jeden řádek v rámci původní stránky Special:AllMessages.

Speciální stránka Special:AllMessages vypisuje zvlášť pro každou zvolenou jazykovou mutaci tabulku se dvěma sloupci: název propojeného rozhraní a text. Text je vodorovně rozdělen, aby se zobrazil výchozí text nahoře a přizpůsobený text níže. Pokud vlastní zpráva neexistuje, zobrazí se pouze výchozí. Pokud chcete přizpůsobit zprávu, klikněte na horní odkaz v levém sloupci (název zprávy). Tento odkaz je červený, pokud se používá výchozí text, protože stránka pro úpravy je prázdná.

Druhý odkaz v levém sloupci vede na stránku, na které lze vést případnou diskuzi o tom jak má vypadat obsah příslušné zprávy.

Vyhledávání zpráv a dokumentace

Jak se v MediaWiki se zprávami pracuje, jaké jsou s nimi spojené proměnné, parametry, omezení atp. je popsáno v dokumentaci k souborům pseudojazyka qqq, a v pravidlech pro dokumentaci zpráv. Pro některé starší zprávy můžete najít obsáhlejší dokumentaci v rámci původní Kategorie:Zprávy rozhraní .

Ve wiki bázi translatewiki.net je qqq stránka, která obsahuje uživatelskou dokumentaci ke zprávě (v angličtině, protože je stejná pro všechny čtenáře).

Stejně jako / en / ge / fr ... / qqq je podstránkou článku a lze ji přímo zobrazit.

Z tohoto hlediska je qqq považován za jazyk v parametru language= požadavku.

Od MediaWiki verze 1.18 a vyšší, můžete vyhledat identifikační řetězce zpráv použitých na stránce jejím zobrazení s využitím kódu pseudo-jazyka qqx. To lze udělat buď tak, že připojíte za URL příslušné wiki stránky ?uselang=qqx, nebo pokud již URL obsahuje znak ? přidáte parametr &uselang=qqx (viz například). Místo obsahu zprávy se tak na stránce zobrazí její identifikační řetězec (klíč), takže pak můžete snadno vyhledat ten, který odpovídá zprávě, kterou chcete upravit. Je-li zpráva součástí obsahu stránky, tak se při použití qqx nic nezobrazí.

Některé části rozhraní přidávají do řetězce, který se zobrazuje při použití triku qqx, nstab-. Například štítek na kartě, který odkazuje na diskusní stránku v hlavním jmenném prostoru, se zobrazuje jako nstab-talk, ale řetězec je ve skutečnosti umístěn v MediaWiki:Talk.

V případě, že stránka používá nějaké vlastní záložky jako např. speciální stránka "Nastavení" budete muset přidat záložku až za parametr uselang, např. Special:Preferences?uselang=qqx#mw-prefsection-rendering.

Formát lokalizačního souboru

Všechny zprávy používané v MediaWiki jsou definovány v souboru zpráv.

V MediaWiki existují dva typy souborů zpráv: JSON a PHP. Od dubna 2014 byla základní MediaWiki a většina udržovaných rozšíření migrována do formátu JSON. Pro veškerý nový vývoj byste měli používat JSON. Další informace o migraci na JSON najdete na stránce Requests for comment/Localisation format.

JSON

Od konce roku 2013 byl zaveden nový formát souborů pro zprávy: JSON. Toto je prostý JSON, známý jako běžný obecný formát ukládání dat. Každý klíč v něm je klíčem zprávy a hodnotou je text zprávy. Speciální klíč @metadata navíc slouží k uložení informací o překladu, jako jsou autoři překladu.

Použitím JSON jsou lokalizační soubory bezpečnější, protože nejsou spustitelné. Je také kompatibilní s jquery.i18n, knihovnou JavaScript vyvinutou jako součást projektu Milkshake, která poskytuje možnosti lokalizace frontendu podobné MediaWiki a je používána některými rozšířeními, která chtějí být méně závislá na MediaWiki, jako je VisualEditor a UniversalLanguageSelector.

Protože širší sada nástrojů pro internacionalizaci a lokalizaci byla nazvána "Project Milkshake", někteří lidé nazývají tento formát "banán".

Umístění souboru

V jádru MediaWiki jsou lokalizační soubory umístěny v adresáři languages/i18n. Rozšíření MediaWiki obvykle umístí svá rozšíření do podadresáře i18n/. Pokud v rámci projektu existuje velký počet zpráv, je možné je rozdělit do dvou nebo více aktuálních podadresářů, aby bylo možné je udržovat. V kontextu MediaWiki se k výpisu těchto podadresářů používá konfigurační klíč $wgMessagesDirs . Zde je příklad z rozšíření VisualEditoru pro MediaWiki:

{
  "MessagesDirs": {
    "VisualEditor": [
      "lib/ve/modules/ve/i18n",
      "modules/ve-mw/i18n",
      "modules/ve-wmf/i18n",
      "lib/ve/lib/oojs-ui/i18n"
    ]
  }
}

Nové zprávy přidáte do anglického souboru zpráv "en" en.json a zdokumentujete je v souboru dokumentace zpráv se speciálním kódem pseudojazyka "qqq" – qqq.json. Viz také: Přidávání nových zpráv.

Metadata

V současné době se v souborech používají následující pole metadat:

authors
JSON seznam autorů zpráv. Pro angličtinu (en) a dokumentaci ke zprávám (qqq) jsou tyto při úpravě souboru zpráv přidány ručně. U všech ostatních jazyků se toto vkládá automaticky při exportu souboru zpráv z translatewiki.net. Dokumentaci zprávy lze upravovat na translatewiki.net a do souboru qqq.json se automaticky vkládají také editace dokumentace.
message-documentation
Toto je kód pseudojazyka pro ukládání dokumentace zprávy. Pro MediaWiki je to vždy qqq. (To se objevuje v některých rozšířeních, ale ve skutečnosti není žádným způsobem zpracováno. Není to povinné.)

Konvence

Speciální znaky, jako jsou zalomení řádků, jsou escapovány ("\n").

Znaky Unicode, které představují písmena v různých abecedách, jsou uloženy jako skutečné znaky a nikoli jako kódy znaků, protože tyto soubory někdy čtou lidé, a proto jsou soubory menší ("誼" a ne "\u8ABC"). V každém případě mají vývojáři málo důvodů upravovat zprávy v jakémkoli jazyce kromě angličtiny, protože ty se obvykle upravují přes translatewiki.net.

Neunikne ani kód HTML, takže "<strong>Warning</strong>" a ne "\u003cstrong\u003eWarning\u003c/strong\u003e".

Soubory JSON jsou odsazeny pomocí tabulátorů.

PHP

PHP je starší formát lokalizačního souboru. Toto je v podstatě pole PHP se všemi zprávami. V jádru MediaWiki je každý jazyk umístěn ve svém vlastním souboru v adresáři languages/message zdrojového kódu MediaWiki. V rozšířeních jsou všechny jazyky a dokumentace zprávy (qqq) ve stejném souboru: ExtensionName.i18n.php, obvykle v hlavním adresáři rozšíření.

K migraci z PHP na JSON použijte skript generateJsonI18n.php. Přesune zprávy do souborů JSON a nahradí text souboru PHP podložkou, která ukazuje na soubory JSON. Tento standardní kód je potřeba pro zpětnou kompatibilitu s MediaWiki 1.19. Nepoužívá se v nových rozšířeních, která nevyžadují kompatibilitu s MediaWiki 1.19.

Používání zpráv

MediaWiki používá centrální úložiště zpráv, na které se odkazují klíče v kódu. To se liší například od Gettext, který pouze získává přeložitelné řetězce ze zdrojových souborů. Systém založený na key-based některé věci usnadňuje, jako je upřesňování původních textů a sledování změn zpráv. Nevýhodou je samozřejmě to, že seznam použitých zpráv a seznam zdrojových textů pro tyto klíče se nemusí synchronizovat. V praxi to není velký problém a jediným významným problémem je, že někdy další zprávy, které se již nepoužívají, stále zůstávají k překladu.

Chcete-li, aby byly klíče zpráv lépe ovladatelné a snadno k nalezení, také pomocí grep, vždy je pište úplně a nespoléhejte se příliš na jejich dynamické vytváření. Můžete zřetězit části klíčů zpráv, pokud máte pocit, že to dává vašemu kódu lepší strukturu, ale přidejte komentář se seznamem možných výsledných klíčů.

Viz také konvence kódu. Například:

// Zde lze použít zprávy:
// * myextension-connection-success
// * myextension-connection-warning
// * myextension-connection-error
$text = wfMessage( 'myextension-connection-' . $status )->parse();

Chcete-li použít zprávu v JavaScriptu, musíte ji uvést v definici vašeho modulu ResourceLoader ve vlastnosti "messages".

Podrobné využití funkcí zpráv v PHP a JavaScriptu je na stránce Manual:Messages API . Toto je důležitá stránka dokumentace a měli byste si ji přečíst, než napíšete kód, který používá zprávy.

Zdroje zpráv

Kód vyhledává systémové zprávy z těchto zdrojů:

  • Jmenný prostor MediaWiki. To umožňuje wiki převzít nebo přepsat všechny své zprávy, když standardní zprávy nevyhovují nebo jsou nežádoucí.
    • MediaWiki:Message-key je výchozí zpráva,
    • MediaWiki:Message-key/language-code je zpráva, která se má použít, pokud uživatel zvolil jiný jazyk, než je výchozí jazyk wiki.
  • Ze souborů zpráv:
    • Samotné jádro MediaWiki a v současnosti udržovaná rozšíření používají soubor pro jazyk s názvem zyx.json, kde zyx je kód jazyka pro daný jazyk.
    • Některá starší rozšíření používají kombinovaný soubor zpráv obsahující všechny zprávy ve všech jazycích, obvykle pojmenovaný MyExtensionName.i18n.php.
    • Mnoho wiki Wikimedia Foundation přistupuje k některým zprávám z rozšíření WikimediaMessages , což jim umožňuje standardizovat zprávy na wiki WMF, aniž by je vnucovaly každé instalaci MediaWiki.
    • Několik rozšíření používá jiné techniky.

Ukládání do mezipaměti

Systémové zprávy jsou jednou z významnějších součástí MediaWiki, především proto, že se používají v každém webovém požadavku. Soubory zpráv PHP jsou velké, protože obsahují tisíce klíčů a hodnot zpráv. Načtení tohoto souboru (a případně více souborů, pokud se jazyk uživatele liší od jazyka obsahu) činí velké nároky na paměť a výkon. Ke snížení tohoto dopadu na výkon se používá agresivní vrstvený systém ukládání do mezipaměti.

MediaWiki má vestavěno mnoho mechanismů ukládání do mezipaměti, díky kterým je kód poněkud obtížnější pochopit. Od 1.16 je nový systém ukládání do mezipaměti, který ukládá zprávy do mezipaměti buď v souborech cdb nebo v databázi. Přizpůsobené zprávy se ukládají do mezipaměti v souborovém systému a v memcached (nebo alternativně), v závislosti na konfiguraci.

Níže uvedená tabulka poskytuje přehled příslušných nastavení:

Umístění mezipaměti $wgLocalisationCacheConf
'store' => 'db'
 
'store' => 'detect'
(výchozí)
'store' => 'files'
 
'store' => 'array'
(experimentální od MW ≥ 1,26)
$wgCacheDirectory = false
(default)
l10n cache table l10n cache table chyba (nedefinovaná cesta) chyba (nedefinovaná cesta)
= path l10n cache table lokální souborový systém (CDB) lokální souborový systém (CDB) lokální souborový systém (pole PHP)
MediaWiki versions:
1.27.0 – 1.27.2
Gerrit #Id3e2d2

V MediaWiki 1.27.0 a 1.27.1 byla autodetekce změněna tak, aby upřednostňovala backend souboru. V případě 'store' => 'detect' (výchozí) se použije backend souboru s cestou z $wgCacheDirectory . Pokud tato hodnota není nastavena (což je výchozí hodnota), použije se dočasný adresář určený operačním systémem. Pokud nelze dočasný adresář detekovat, použije se jako záložní řešení backend databáze. Toto bylo vráceno z 1.27.2 a 1.28.0 kvůli konfliktu souborů na sdílených hostitelích a bezpečnostním problémům (viz T127127 a T161453).

Funkce backtrace

Pro lepší vizuální znázornění vrstev ukládání do mezipaměti je zde funkce backtrace toho, jaké metody se nazývají při načítání zprávy. Vysvětlení každé vrstvy najdete v následujících částech.

  • Message::fetchMessage()
  • MessageCache::get()
  • Language::getMessage()
  • LocalisationCache::getSubitem()
  • LCStore::get()

MessageCache

Třída MessageCache je nejvyšší úrovní ukládání zpráv do mezipaměti. Je volána ze třídy Message a vrací konečný nezpracovaný obsah zprávy. Tato vrstva zpracovává následující logiku:

Poslední odrážka je důležitá. Jazyková rezerva (language fallbacks) umožňuje MediaWiki použít jiný jazyk, pokud originál neobsahuje požadovanou zprávu. Jak je zmíněno v další části, většina jazykových řešení se vyskytuje na nižší úrovni. Pouze vrstva MessageCache však kontroluje, zda v databázi nejsou přepsané zprávy. Zde se tedy provádí integrace přepsaných zpráv z databáze do záložního řetězce. Pokud databázi nepoužíváte, lze celou tuto vrstvu zakázat.

LocalisationCache

Viz LocalisationCache.php

LCStore

Třída LCStore je pouze implementací typu back-end, kterou používá třída LocalisationCache pro skutečné ukládání do mezipaměti a získávání zpráv. Stejně jako třída BagOStuff, která se používá pro obecné ukládání do mezipaměti v MediaWiki, existuje řada různých typů mezipaměti (konfigurovaných pomocí $wgLocalisationCacheConf):

  • "db" (výchozí) - ukládá zprávy do mezipaměti v databázi
  • "file" (výchozí, pokud je nastaveno $wgCacheDirectory) - používá CDB k ukládání zpráv do mezipaměti v místním souboru
  • "accel" - k ukládání dat používá APC nebo jinou mezipaměť operačních kódů

Možnost "file" používá Wikimedia Foundation a je doporučena, protože je rychlejší než přechod do databáze a spolehlivější než mezipaměť APC, zejména proto, že APC není kompatibilní s PHP verze 5.5 nebo novější.

Přidávání nových zpráv

Výběr klíče zprávy

Viz také: Příručka:Pravidla pro psaní kódu

Klíč zprávy musí být globálně jedinečný. To zahrnuje jádro MediaWiki a všechna rozšíření a vzhledy.

V názvech zpráv se držte malých písmen, číslic a pomlček; většina ostatních znaků je mezi méně praktickými nebo nefungujícími vůbec. Podle konvence MediaWiki první znak nerozlišuje velká a malá písmena a ostatní znaky rozlišují malá a velká písmena.

Při pojmenovávání prosím dodržujte globální nebo místní konvence. U předpon použijte standardní prefix, nejlépe název předpony psaný malými písmeny, za kterým následuje pomlčka ("-"). Výjimky jsou:

Zprávy používané rozhraním API
Musí začínat znaky apihelp-, apiwarn-, apierror-. Za tuto předponu vložte předponu rozšíření. (Všimněte si, že tyto zprávy by měly být v samostatném souboru, obvykle pod includes/i18/api.)
Zprávy související s protokolem
Musí začínat znaky logentry-, název-logu-, popis-logu.
Uživatelská práva
Klíč pro název práva, jak je zobrazen na Special:ListGroupRights, musí začínat right-. Název akce, která doplňuje větu "Z následujících důvodů nemáte oprávnění $2:" musí začínat action-.
Revisions tags
Značky revizí musí začínat tag-.
Special page titles
Speciální názvy stránek musí začínat special-.

Další věci, které je třeba vzít v úvahu při vytváření zpráv

  1. Ujistěte se, že pro zprávu používáte vhodné zpracování (analýzu, nahrazení {{, escapování pro HTML atd.)
  2. Pokud je vaše zpráva součástí jádra, měla by být obvykle přidána k languages/i18n/en.json, ačkoli některé součásti, jako je Installer, EXIF tagy a ApiHelp, mají své vlastní soubory zpráv.
  3. Pokud je vaše zpráva v rozšíření, přidejte ji do souboru i18n/en.json nebo en.json v příslušném podadresáři. Zejména zprávy API, které vidí pouze vývojáři a ne většina koncových uživatelů, jsou obvykle v samostatném souboru, například i18n/api/en.json. Pokud má rozšíření mnoho zpráv, můžete vytvořit podadresáře pod i18n. Všechny adresáře zpráv, včetně výchozího i18n/, musí být uvedeny v sekci MessagesDirs v extension.json nebo v proměnné $wgMessagesDirs .
  4. Udělejte si pauzu a zvažte znění zprávy. Je to co nejjasnější? Může to být špatně pochopeno? Pokud je to možné, vyžádejte si komentáře od jiných vývojářů nebo lokalizátorů. Postupujte podle Internacionalizačních rad.
  5. Přidejte dokumentaci do qqq.json ve stejném adresáři.
  6. The sequence of the messages in the file should roughly conform to the features of your project. Put messages from the same feature next to each other. This helps translators stay focused and be efficient and consistent.
  7. Put the messages that are expected to be the most basic and the most frequently used in the beginning of the file, and the messages that are rarer and more technically advanced towards the end.


Zprávy, které by se neměly překládat

  1. Ignored (ignorované) zprávy jsou ty, které by měly existovat pouze v anglickém souboru zpráv. Jsou to zprávy, které by neměly vyžadovat překlad, protože odkazují pouze na jiné zprávy nebo jazykově neutrální funkce, např. zprávu "{{SITENAME}}".
  2. Optional (volitelné) zprávy mohou být přeloženy pouze v případě, že jsou změněny v cílovém jazyce.

Označení takových zpráv:

Odebírání existujících zpráv

Odstraňte ji z en.json a qqq.json. Neobtěžujte se jinými jazyky. Aktualizace z translatewiki.net je zpracují automaticky.

Kromě toho zkontrolujte, zda se zpráva objeví kdekoli v konfiguraci translatewiki, například v seznamu volitelných nebo nejpoužívanějších zpráv (měl by stačit jednoduchý git grep). V případě potřeby jej z těchto seznamů odstraňte.

Změna existujících zpráv

  1. Zvažte aktualizaci dokumentace zprávy.
  2. Změňte klíč zprávy, pokud staré překlady nejsou vhodné pro nový význam. To zahrnuje také změny ve zpracování zpráv (parsování, escapování, parametry atd.). Zlepšení frázování zprávy bez technických změn obvykle není důvodem pro změnu klíče. Na translatewiki.net budou překlady označeny jako zastaralé, aby na ně mohli cílit překladatelé. Změna klíče zprávy nevyžaduje komunikaci s týmem i18n nebo podání žádosti o podporu. Pokud však máte zvláštní okolnosti nebo dotazy, zeptejte se na #translatewiki připojit se nebo na stránce podpory na translatewiki.net .
  3. Pokud rozšíření podporuje translatewiki.net , změňte prosím pouze anglickou zdrojovou zprávu anebo klíč a doprovodný záznam v qqq.json. V případě potřeby se tým translatewiki.net postará o aktualizaci překladů, označí je jako zastaralé, vyčistí soubor nebo přejmenuje klíče tam, kde je to možné. To platí také v případě, že měníte pouze věci, jako jsou značky HTML, které byste mohli změnit v jiných jazycích, aniž byste těmito jazyky mluvili. Většina z těchto akcí proběhne v translatewiki.net a dorazí do Gitu s přibližně jednodenním zpožděním.

Dokumentace zprávy

Pro dokumentaci zpráv existuje pseudojazykový kód qqq. Je to jeden z kódů ISO 639 vyhrazený pro soukromé použití. Tam neuchováváme překlady každé zprávy, ale shromažďujeme anglické věty o každé zprávě: Říká nám, kde se používá, dává rady, jak ji přeložit, a vyjmenovává a popisuje její parametry, odkazuje na související zprávy a tak dále. Na translatewiki.net se tyto rady zobrazují překladatelům, když upravují zprávy.

Programátoři musí zdokumentovat každou zprávu. Dokumentace zpráv je nezbytným zdrojem – nejen pro překladatele, ale pro všechny správce modulu. Kdykoli je do softwaru přidána zpráva, musí být přidána také odpovídající položka qqq. Revize, které tak nečiní, jsou označeny "V-1", dokud nebude přidána dokumentace.

Dokumentace v souborech qqq by měla být upravována přímo pouze při přidávání nových zpráv nebo při změně existující anglické zprávy způsobem, který vyžaduje změnu dokumentace, například přidání nebo odebrání parametrů. V ostatních případech by měla být dokumentace obvykle upravována v translatewiki. Každý dokumentační řetězec je přístupný na https://translatewiki.net/wiki/MediaWiki:message-key/qqq, jako by to byl překlad. Tyto úpravy budou exportovány do zdrojových úložišť spolu s překlady.

Mezi užitečné informace, které by měly být v dokumentaci, patří:

  1. Práce se zprávami (analýza, escapování, prostý text).
  2. Typ parametrů s ukázkovými hodnotami.
  3. Kde je zpráva použita (stránky, umístění v uživatelském rozhraní).
  4. Jak se zpráva používá tam, kde je použita (název stránky, text tlačítka, atd.).
  5. Jaké další zprávy se používají spolu s touto zprávou nebo na které další zprávy se tato zpráva vztahuje.
  6. Cokoli jiného, co lze pochopit, když je zpráva viděna v kontextu, ale ne, když je zpráva zobrazena samostatně (což je případ, kdy je překládána).
  7. Případně poznámky o gramatice. Například "open" v angličtině může být sloveso i přídavné jméno. V mnoha jiných jazycích se slova liší a je nemožné uhodnout, jak je přeložit bez dokumentace.
  8. Přídavná jména, která popisují věci, jako je "disabled" (zakázáno), "open" (otevřeno) nebo "blocked" (blokováno), musí vždy říkat, co popisují. V mnoha jazycích musí mít přídavná jména rod podstatného jména, které popisují. Může se také stát, že různé druhy věcí potřebují různá přídavná jména.
  9. Pokud má zpráva speciální vlastnosti, například pokud se jedná o název stránky, nebo pokud by neměla být přímým překladem, ale měla by být přizpůsobena kultuře nebo projektu.
  10. Zda se zpráva objeví v souvislosti s jinou zprávou, například v seznamu nebo v nabídce. Znění nebo gramatické rysy slov by pravděpodobně měly být podobné se souvisejícími zprávami. Položky v seznamu by měly také správně souviset se záhlavím seznamu.
  11. Části zprávy, které se nesmí překládat, jako jsou názvy obecných jmenných prostorů, adresy URL nebo značky.
  12. Vysvětlení potenciálně nejasných slov, například zkratky, jako je "CTA" nebo konkrétní žargon, jako "template" (šablona), "suppress" (potlačit) nebo "stub" (útržek). (Všimněte si, že je nejlepší se takovým slovům v první řadě vyhnout!)
  13. Snímky obrazovek (creenshot) jsou velmi užitečné. Neořezávejte – obrázek celé obrazovky, na kterém se zpráva zobrazuje, poskytuje úplný kontext a lze jej znovu použít v několika zprávách.

Několik dalších tipů:

  • Pamatujte, že překladatelé velmi, velmi často překládají zprávy, aniž by skutečně používali software.
  • Překladatelé většinou nemají žádné kontextové informace, ani o vašem modulu, ani o jiných zprávách v něm.
  • Samotná přeformulovaná zpráva je ve většině případů k ničemu.
  • Nepoužívejte žargon návrhářů jako "nav" nebo "comps".
  • Zvažte sepsání glosáře technických termínů, které se používají ve vašem modulu. Pokud to uděláte, odkažte na něj v dokumentace zpráv.

Na další zprávy můžete odkazovat pomocí {{msg-mw|message key}}. Udělejte to prosím, pokud části zpráv pocházejí z jiných zpráv (pokud tomu nelze zabránit), nebo pokud jsou některé zprávy zobrazeny společně nebo ve stejném kontextu.

translatewiki.net poskytuje některé výchozí šablony pro dokumentaci:

  • {{doc-action|[...]}} - pro zprávy action-
  • {{doc-right|[...]}} - pro zprávy right-
  • {{doc-group|[...]|[...]}} - pro zprávy kolem skupin uživatelů (group, member, page, js a css )
  • {{doc-accesskey|[...]}} - pro zprávy accesskey-

Pro více informací se podívejte na stránky šablon.

Internacionalizační rady

Kromě dokumentace překladatelé žádají vývojáře, aby zvážili některé rady, které by jim usnadnily a zefektivnily práci a umožnily skutečnou a dobrou lokalizaci pro všechny jazyky. I když pouze přidáváte nebo upravujete zprávy v angličtině, měli byste si být vědomi potřeb všech jazyků. Každá zpráva je přeložena do více než 300 jazyků a to by mělo být provedeno co nejlepším způsobem. Správná implementace těchto rad vám velmi často pomůže psát lepší zprávy také v angličtině.

Localisation#Help_and_contact_info lists the main places where you can find the assistance of experienced and knowledgeable people regarding i18n.

Use Message parameters and switches properly

That's a prerequisite of a correct wording for your messages.

Avoid message re-use

Překladatelé odrazují od opětovného použití zpráv. To se může zdát neintuitivní, protože kopírování a duplikování kódu je obvykle špatný postup, ale v systémových zprávách je to často potřebné. Ačkoli lze dva pojmy vyjádřit stejným slovem v angličtině, nemusí to nutně znamenat, že je lze vyjádřit stejným slovem v každém jazyce. Dobrým příkladem je "OK": V angličtině se používá pro obecný štítek tlačítka, ale v některých jazycích dávají přednost použití štítku tlačítka souvisejícího s operací, kterou tlačítko provede. Dalším příkladem je prakticky jakékoli přídavné jméno: Slovo jako "multiple" se v mnoha jazycích mění podle pohlaví, takže jej nemůžete znovu použít k popisu několika různých věcí a musíte vytvořit několik samostatných zpráv.

Pokud přidáváte více identických zpráv, přidejte dokumentaci ke zprávě, která popisuje rozdíly v jejich kontextech. Nebojte se práce navíc pro překladatele. Překladová paměť v tom hodně pomáhá a zároveň si zachovává v případě potřeby flexibilitu pro různé překlady.

Vyhněte se fragmentovaným nebo 'patchworkovým' (slátaninám) zprávám

Jazyky mají různé slovosledy a různě složitá gramatická a syntaktická pravidla. Je velmi těžké přeložit "lego" zprávy, tedy zprávy tvořené více kusy textu, případně s určitým nepřímým způsobem (také nazývané "řetězec řetězců").

Je lepší udělat z každé zprávy jednu úplnou frázi. Několik vět lze v případě potřeby obvykle mnohem snadněji spojit do textového bloku. Chcete-li v jedné zprávě zkombinovat několik řetězců, předejte je jako parametry, protože překladatelé je mohou při překladu pro svůj jazyk správně seřadit.

Zprávy, které se navzájem citují

Výjimkou z pravidla mohou být zprávy, které na sebe odkazují: 'Zadejte jméno původního autora do pole označeného "{{int:name}}" a klikněte na "{{int:proceed}}" pro dokončení'. Díky tomu je zpráva konzistentní, když vývojář softwaru nebo provozovatel wiki později změní "name" (jméno) nebo "proceed" (pokračovat). Bez tohoto int-triku by si vývojáři a operátoři museli být vědomi všech souvisejících zpráv, které je třeba upravit, když se cokoli změní.

Nepoužívejte termíny a šablony, které jsou specifické pro konkrétní projekty

MediaWiki používají velmi různorodí lidé v rámci hnutí Wikimedie i mimo něj. Přestože byla původně vytvořena pro encyklopedii, nyní se používá pro různé druhy obsahu. Používejte proto obecné výrazy. Vyhněte se například výrazům jako "article" (článek) a místo toho použijte "page" (stránka), pokud si nejste absolutně jisti, že funkce, kterou vyvíjíte, bude použita pouze na webu, kde se stránky nazývají "articles" (články). Nepoužívejte "village pump", což je název stránky komunity na anglické Wikipedii, a místo toho používejte obecný termín, například "community discussion page" (diskusní stránka komunity).

Nepředpokládejte, že určitá šablona existuje na všech wiki. Šablony jsou pro wiki lokální. To platí jak pro zdrojové zprávy, tak pro jejich překlady. Pokud zprávy používají šablony, budou fungovat pouze tehdy, pokud je šablona vytvořena na každé wiki, kde je funkce nasazena. Nejlepší je úplně se vyhnout používání šablon ve zprávách. Pokud je opravdu musíte použít, musíte to jasně zdokumentovat v dokumentaci ke zprávě a v pokynech k instalaci rozšíření.

Oddělte časy od dat ve větách

Některé jazyky musí mezi datum a čas vložit něco, co gramaticky závisí na jiných slovech ve větě. Nebudou tedy moci používat kombinaci data a času. Ostatním se může tato kombinace zdát vhodná, proto je obvykle nejlepší volbou v takových případech zadat tři hodnoty parametrů (datum/čas, datum, čas) a v každém překladu ponechat buď první, nebo poslední dvě podle potřeby nevyužité.

Vyhněte se {{SITENAME}} ve zprávách

{{SITENAME}} má několik nevýhod. Může to být cokoliv (akronym, slovo, krátká fráze, atd.) a v závislosti na jazyce může vyžadovat použití {{GRAMMAR}} při každém výskytu. Bez ohledu na to, každá zpráva s {{SITENAME}} bude vyžadovat kontrolu ve většině jazyků wiki pro každou novou wiki, na které je nainstalován váš kód. Ve většině případů, kdy pro jazyk neexistuje obecná konfigurace GRAMMAR, budou muset operátoři wiki přidat nebo upravit kód PHP tak, aby fungovali {{GRAMMAR}} pro {{SITENAME}}. To vyžaduje více dovedností a více porozumění než v jiném případě. Je vhodnější mít obecné odkazy jako "this wiki" (tato wiki). To sice instalacím nebrání lokálně měnit tyto zprávy tak, aby používaly {{SITENAME}}, ale alespoň nemusí a mohou odložit přizpůsobení zpráv, dokud wiki již nebude spuštěna a používána.

Vyhněte se odkazům na vizuální rozvržení a pozice

Co se kde vykreslí, závisí na vzhledech. Rozvržení obrazovky jazyků psaných zleva doprava jsou nejčastěji zrcadlená ve srovnání s těmi, která se používají pro jazyky psané zprava doleva, ale ne vždy a u některých jazyků a wiki ne úplně. Ruční zařízení, úzká okna a tak dále mohou pod sebou zobrazovat bloky, které by se na větších displejích objevovaly vedle sebe. Vzhledem k tomu, že skripty a miniaplikace JavaScriptu psané webem a uživatelem mohou a také budou skrývat části nebo přesouvat věci nepředvídatelným způsobem, neexistuje žádný spolehlivý způsob, jak zjistit skutečné rozvržení.

Je nesprávné spojovat informace o rozvržení s jazyky obsahu, protože jazyk uživatelského rozhraní nemusí být jazykem obsahu stránky a rozvržení může být v závislosti na okolnostech kombinací obou. Nevizuální uživatelské agenty, jako jsou akustické čtečky obrazovky a další pomocná zařízení, ani nemají koncept vizuálního rozvržení. Proto byste se ve většině případů neměli odkazovat na pozice vizuálního rozvržení, ačkoli termíny sémantického rozvržení mohou být stále použity ("předchozí kroky ve formuláři" atd.).

MediaWiki nepodporuje zobrazování různých zpráv nebo fragmentů zpráv na základě aktuální směrovosti rozhraní (viz T30997).

Připravovaná podpora prohlížeče a MediaWiki pro psaní shora dolů ve východní a severní Asii[1] způsobí, že rozložení obrazovky bude ještě nepředvídatelnější, alespoň osm možných rozložení (levá/pravá výchozí pozice, horní/dolní výchozí pozice a to, co nastane jako první).

Vyhněte se odkazům na barvy obrazovky

Barva, ve které je něco vykresleno, závisí na mnoha faktorech, včetně vzhledů, skriptů a gadgetů JavaScript napsaných webem a uživatelem a přepisů místního uživatelského agenta z důvodu dostupnosti nebo technologických omezení. Nevizuální uživatelské agenty, jako jsou akustické čtečky obrazovky a další pomocná zařízení, nemají ani koncept barev. Proto byste neměli odkazovat na barvy obrazovky. (Ze stejného důvodu byste se také neměli spoléhat pouze na barvu jako na mechanismus informování uživatele o stavu.)

Mějte prvky zprávy před a za každým vstupním polem

Toto je doporučený návod, který se nestal standardem ve vývoji MediaWiki

Zatímco angličtina umožňuje efektivní využití dotazování ve formuláři položka–dvojtečka–mezera–vstupní pole, mnoho jiných jazyků to tak nemá. I v angličtině často používáte "Vzdálenost: ___ metrech" spíše než "Vzdálenost (v metrech): ___". Ponecháme-li prvky ‎<textarea> stranou, měli byste myslet na každé vstupní pole podle vzoru "Vzdálenost: ___ metrů". Tak:

  • vytvořte dvě zprávy, i když bude 2. v angličtině a některých dalších jazycích prázdná, nebo
  • povolte umístění vstupů pomocí parametrů $i.

Vyhněte se nepřeloženým značkám HTML ve zprávách

Značky HTML, které nevyžadují překlad, jako je uzavření ‎<div>, pravítka nad nebo pod a podobně, by obvykle neměly být součástí zpráv. Zbytečně zatěžují překladatele, zvětšují velikost souboru zpráv a představují riziko náhodné změny nebo přeskočení v procesu překladu. Obecně se ve zprávách vyhněte raw HTML, pokud můžete.

Zprávy jsou často delší, než si myslíte!

Při procházení souborů zpráv v cizích jazycích téměř nikdy nenajdete zprávy kratší než ty čínské, zřídka kratší než ty anglické a obvykle mnohem delší než ty anglické.

Zejména ve formulářích před vstupními poli bývají anglické zprávy stručné a krátké. To se v překladech často neuchovává. Jazyky mohou postrádat technickou slovní zásobu v angličtině a mohou vyžadovat více slov nebo dokonce celé věty k vysvětlení některých pojmů. Například krátká anglická zpráva "TSV file:" může být přeložena do jazyka doslovně:

Sem zadejte název, který označuje sbírku počítačových dat, která se skládá z postupně organizovaných sérií strojopisných řádků, které jsou samy o sobě organizovány jako série informačních polí, kde jsou uvedená pole informací ohraničena a ohraničení mezi nimi jsou jediné znaky toho druhu, které posouvají vozík psacího stroje dále do další předem definované polohy. Tady to je: _____ (děkuji)

Toto je, pravda, extrémní příklad, ale tuto možnost máte. Představte si tuto větu ve sloupci ve tvaru, kde každé slovo zabírá vlastní řádek a vstupní pole je svisle vystředěno v dalším sloupci. :-(

Nepoužívejte velmi blízká, podobná nebo identická slova k označení různých věcí nebo pojmů

Stránky mohou mít například starší revize (konkrétního data, času a úprav), zahrnující minulé verze uvedené stránky. Slova revize a verze lze používat zaměnitelně. Problém nastává, když jsou verzované stránky revidovány a také se zmiňuje revize, tj. proces jejich revize. To nemusí představovat vážný problém, když dvě synonyma "revize" mají různé překlady. Na to však nespoléhejte. Je tedy lepší se použití "revize" aka "verze" úplně vyhnout, aby nedošlo k jeho nesprávné interpretaci.

Základní slova mohou mít nepředvídatelné konotace nebo vůbec neexistují

Některá slova se těžko překládají kvůli jejich velmi specifickému použití v MediaWiki. Některá možná nebudou přeložena vůbec. Například v několika jazycích neexistuje slovo "uživatel" (user) vztahující se k "někomu, kdo něco používá". Podobně v Kölsch anglická slova "namespace" a "apartment" se překládají jako stejné slovo. Také v Kölsch říkají stejným slovem "corroborator and participant" (potvrzující a účastník), protože jakýkoli odkaz na "use" (použití) by příliš silně znamenal "abuse" (zneužívání). Termín "wiki farma" se překládá jako "stáj plná wiki", protože farma s jednou plodinou by byla v rozporu s termíny v jazyce a nepochopena, atd..

Očekávejte nepřeložená slova

Toto je doporučený návod, který se ještě nestal standardem ve vývoji MediaWiki

Není neobvyklé, že vlastní jména, názvy značek, atd. v počítačové angličtině nejsou překládány a místo toho jsou brány jako přejatá nebo cizí slova. V jiném případě mohou někteří zvláště nároční překladatelé označit taková slova jako slova patřící do jiného jazyka pomocí značek HTML, například <span lang="en"></span>.

Možná budete chtít zvážit zajištění toho, aby váš obslužný program pro výstup zpráv předal takové označení beze změny, navzdory zjevným bezpečnostním rizikům.

Povolit vysvětlující vložené značky

Toto je doporučený návod, který se ještě nestal standardem ve vývoji MediaWiki

Někdy se v cílových jazycích vyskytují zkratky, odborné výrazy nebo obecně nejednoznačná slova, kterým nováčci nemusí hned porozumět, ale zkušeným uživatelům počítačů jsou zřejmé. Aby se překladatelé vyhnuli změti obrazovky zdlouhavými vysvětlivkami, aniž by nechali nováčky ve štychu, mohou se překladatelé rozhodnout přidat vysvětlení jako ‎<abbr> anotace, které prohlížeče zobrazí, když na ně najedete myší.

Například základní zpráva MediaWiki exif-orientation-8 o rotaci obrázku, která je v angličtině jednoduše "Rotated 90° CW", v marocké arabštině je přeložena jako:

mḍwwer 90° <abbr title="Ĝks (ṫ-ṫijah) Ĝaqarib s-Saĝa">ĜĜS</abbr>

dává:

mḍwwer 90° ĜĜS

vysvětlení zkratky pro "proti směru hodinových ručiček", když je potřeba.

Možná budete chtít zvážit zajištění toho, aby vaše obsluha výstupu zprávy předala takové označení beze změny, i když je původní zpráva nepoužívá.

V případě potřeby použijte značky ‎<code>, ‎<var> a ‎<kbd>

Když mluvíte o technických parametrech, hodnotách nebo vstupech z klávesnice, označte je jako takové vhodně pomocí značek HTML ‎<code>, ‎<var> nebo ‎<kbd>. Jsou tedy typograficky odsazeny od běžného textu. To čtenářům vyjasní jejich smysl a zabrání zmatkům, chybám a chybným prohlášením. Ujistěte se, že vaše zpracování zpráv umožňuje takové označení.

Symboly, dvojtečky, závorky, atd. jsou součástí zpráv

Mnoho symbolů je také lokalizovatelných. Některá písma mají jiné druhy závorek než latinka. V některých jazycích nemusí být po štítku nebo výzvě k zadání dvojtečka vhodná. Začlenění těchto symbolů do zpráv pomáhá vytvářet lepší a méně anglo-centrické překlady a také snižuje změť kódu.

Například v «norštině», »švédštině», »dánštině«, »němčině« a «japonštině» se používají různé konvence uvozovek.[2]

Pokud potřebujete zalomit nějaký text do lokalizovaných závorek, hranatých závorek nebo uvozovek, můžete použít parentheses ($1) nebo brackets [$1] nebo quotation-marks "$1" zprávy jako takto:

wfMessage( 'parentheses' )->rawParams( /* text to go inside parentheses */ )->escaped()
wfMessage( 'brackets' )->rawParams( /* text to go inside brackets */ )->escaped()
wfMessage( 'quotation-marks' )->rawParams( /* text to go inside quotation marks */ )->escaped()

Neočekávejte, že symboly a interpunkce přežijí překlad

Jazyky psané zprava doleva (na rozdíl od angličtiny) obvykle zaměňují symboly šipek prezentované s odkazy "next" (další) a "previous" (předchozí) a jejich umístění vzhledem k textu zprávy může, ale také nemusí být převráceno. Elipsis může být přeloženo jako "atd." nebo jako slova. Otazníky, vykřičníky, dvojtečky budou umístěny jinde než na konci věty, vůbec a nebo dvakrát. V důsledku toho vždy zahrňte všechny do textu svých zpráv a nikdy se nepokoušejte je vkládat programově.

Použijte tečky

Do ukončete normální věty tečkami. To je pro překladatele často jediný ukazatel, podle kterého pozná, že se nejedná o titulky nebo položky seznamu, které může být potřeba přeložit jinak.

Odkazové kotvy

Odkazy Wikitextu

Kotvy odkazů lze do zpráv vložit několika technickými způsoby:

  1. přes wikitext: … [[stránka wiki|kotva]] …,
  2. přes wikitext: … [nějaká-URL kotva] …, or
  3. text kotvy je zpráva ve jmenném prostoru MediaWiki. Vyhněte se tomu!

To druhé je pro překladatele často obtížné nebo nemožné zvládnout, vyvarujte se fragmentovaných nebo 'chaotickým' zprávám i zde. Ujistěte se, že "nějaká-URL" neobsahuje mezery.

Použijte smysluplné kotvy odkazů

Dejte si pozor na svou formulaci. Odkazové kotvy hrají důležitou roli při hodnocení stránek vyhledávači – jak slova propojená, tak cílová kotva. Ujistěte se, že kotva dobře popisuje cílovou stránku. Vždy se vyhněte běžným a obecným slovům. Například "Click here" (klikněte sem) je absolutně zákázáno,[3], protože cílové stránky téměř nikdy nejsou o "kliknutí sem". Nedávejte to ani do vět kolem odkazů, protože "sem" nebylo místo, kam kliknout. Místo toho použijte přesná akční slova, která říkají, k čemu se uživatel dostane, když bude následovat odkaz, jako například "Můžete nahrát soubor, pokud si přejete."

Viz také Pomozte uživatelům předvídat, kam jdou, a tajemná navigace masa a Hlavní důvody, proč bychom neměli používat klikni sem jako text odkazu.

Vyhněte se žargonu a slangu

Vyhněte se ve zprávách žargonu vývojářů a zkušených uživatelů. Snažte se používat jednoduchý jazyk, kdykoli je to možné. Pokud chcete uživatele upozornit, že se něco stalo nebo nestalo, neříkejte "success" (úspěch), "successfully" (úspěšně), "fail" (neúspěch), "error occurred while" (došlo k chybě) atd. To vychází z pohledu vývojářů, kteří vidí všechno jako pravdivé nebo nepravdivé, ale uživatelé obvykle chtějí vědět, co se skutečně stalo nebo nestalo a co by s tím měli dělat (pokud vůbec). Tak:

  • "Soubor byl úspěšně přejmenován" -> "Soubor byl přejmenován"
  • "Přejmenování souboru se nezdařilo" -> "Soubor s tímto názvem již existuje. Vyberte prosím jiný název."

Dejte si pozor na mezery a zalomení řádků

Lokalizované zprávy MediaWiki se obvykle upravují na wiki buď operacemi wiki na živých wiki nebo překladateli na translatewiki.net. Měli byste si být vědomi toho, jak mezery, zejména na začátku nebo konci vaší zprávy, ovlivní editory:

  • Mezery a konce řádků (nové řádky) na konci zprávy jsou vždy automaticky odstraněny editorem wikitextu. Vaše zpráva nesmí končit mezerou nebo zalomením řádku, protože se při úpravě na wiki ztratí.
  • Mezery a zalomení řádků na začátku nejsou automaticky odstraněny, ale pravděpodobně budou odstraněny náhodně během úprav a je třeba se jim vyhnout.

Začněte a ukončete svou zprávu aktivním textem; pokud kolem něj potřebujete zalomení nového řádku nebo odstavce, váš okolní kód by se měl vypořádat s jeho přidáním do vráceného textu.

There are some messages which require a space at the end, such as 'word-separator' (which consists of just a space character in most languages). To support such use cases, the following HTML entities are allowed in messages and transformed to the actual characters, even if the message otherwise doesn't allow wikitext or HTML formatting:[4]

On a related note, any other syntax elements affected by pre-save transforms also must not be used in messages, as they will be transformed when the message is edited on the wiki.

Použijte standardní velká písmena

Velká písmena překladatelům napoví, co překládají, jako jsou jednotlivá slova, položky seznamu nebo nabídky, fráze nebo celé věty. Správná (standardní) velká písmena můžou také hrát roli při hodnocení vašich stránek vyhledávači. MediaWiki používá case case (Rychlá hnědá liška skáče přes líného psa) ve zprávách rozhraní.

Vždy si pamatujte, že mnoho psacích systémů vůbec nemá velká písmena a některé z těch, které je mají, je používají jinak než angličtina. Proto pro zdůraznění nepoužívejte VŠECHNA VELKÁ PÍSMENA. Použijte CSS nebo HTML ‎<em> nebo ‎<strong> níže:

Důraz

V normálním textu by měly být součástí textů zpráv emphasis tučné písmo nebo kurzíva a podobně. Místní konvence v důrazu se často liší, zvláště některá asijská písma mají svá vlastní. Překladatelé musí být schopni přizpůsobit důraz svým cílovým jazykům a oblastem. Zkuste ve svém uživatelském rozhraní použít "‎<em>" a "‎<strong>", abyste umožnili značkování podle jazyka nebo skriptu.

V moderních rozvrženích obrazovky v anglickém a evropském stylu se důraz používá méně. Uveďte to ve své dokumentaci zprávy, protože to může poskytnout cenné rady, jak překládat. Důraz může a měl by být podle potřeby použit v jiných kulturních kontextech za předpokladu, že o tom překladatelé vědí.

Související odkazy