Jump to content

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 100% complete.
Languages:
PD Poznámka: Úpravou této stránky souhlasíte s uvolněním vašeho příspěvku pod licencí CC0. Více informací získáte na stránce nápovědy veřejné domény. PD
i18n dokumenty
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.

Přepsání zpráv na wiki se doporučuje pouze v následujících případech:

  • Zpráva obsahuje závažnou chybu, kterou je třeba co nejdříve opravit. V tomto případě se doporučuje opravit tuto chybu také ve zdrojovém kódu, pokud je v angličtině, nebo v překladu na translatewiki, pokud tomu tak není. Po nasazení opravy by měla být stránka s místním přizpůsobením odstraněna.
  • Pokud místní wiki používá jinou terminologii. Mnoho zpráv používá například slovo "page", ale anglická Wikipedie místo toho často říká "article".
  • Místní zpráva se pokouší přidat nějakou jedinečnou funkcionalitu, například pro miniaplikaci nebo šablonu. (V takovém případě se stále doporučuje zvážit změnu zdrojové zprávy nebo tuto funkci zapouzdřit do rozšíření, aby si ji ostatní wikiny mohli pohodlně užít, aniž by museli ručně kopírovat přizpůsobení.)

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, /zu, /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.
Verze MediaWiki:
≥ 1.18

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

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.

Verze MediaWiki:
≥ 1.38
Gerrit change 765385

Před MediaWiki 1.38 nebyly klávesy záložních zpráv zobrazeny, což ztěžovalo identifikaci zdroje některých zpráv, zejména navigačních karet. Od verze MediaWiki 1.38 jsou klíče záložních zpráv zobrazeny oddělené lomítky (/).

Verze MediaWiki:
≥ 1.43
Gerrit change 1025837

Před MediaWiki 1.43 nebyly zobrazeny ani klíče pro přepisování zpráv (pomocí háčků jako MessageCacheFetchOverrides), což ztěžovalo identifikaci zdroje zpráv přepsaných rozšířeními (jako je WikimediaMessages ). Od verze MediaWiki 1.43 je klíč zprávy přepsání zobrazen za znakem rovná se (=).

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í převedena 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

Tato část se týká použití souborů MessagesXx.php pro lokalizaci zpráv, které bylo zastaralé v roce 2014. Soubory se však stále používají pro konfiguraci specifickou pro jiný jazyk .

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

Chcete-li migrovat systémové zprávy 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 systému gettext, který 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, že seznam použitých zpráv a seznam zdrojových textů pro tyto klíče mohou být nesynchronizované. 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.

Aby se klíče zpráv lépe spravovaly a snáze se hledaly, pište je vždy celé 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 udělejte to pouze v případě, že rozhodně existuje více možností, [1] a nezapomeňte přidat komentář se seznamem možných výsledných klíčů. Například: 

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

Viz také konvence kódování pro dynamické identifikátory.

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 Příručka:Zprávy 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 wikinám 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 wikin Wikimedia Foundation přistupuje k některým zprávám z rozšíření WikimediaMessages , což jim umožňuje standardizovat zprávy na wikinách 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
(výchozí) 		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)
Verze MediaWiki:
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-, log-name-, log-description.
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-.
Značky revizí
Značky revizí musí začínat tag-.
Speciální názvy stránek
Speciální názvy stránek musí začínat special-.
Extension descriptions
Extension descriptions must begin with the extension name and end with -desc.

They appear in the table on Special:Version, and their content must briefly explain what the extension does.

Pohlaví

Anglické zprávy téměř nikdy nepotřebují různá slova, která se mění kvůli pohlaví uživatele. Angličtina to potřebuje pouze u zájmen ve třetí osobě "on" a "ona", ale ta jsou ve zprávách překvapivě vzácná. Pokud je to nutné, použijte he nebo they.

Mnoho dalších jazyků však potřebuje různá slova v závislosti na pohlaví uživatele, a to nejen pro zájmena ve třetí osobě, ale i pro jiná zájmena, stejně jako pro slovesa v různých časech (např. "vytvořeno", "vymazáno"), podstatná jména (např. "mentor", "administrátor"), přídavná jména (např. "nový") atd. Angličtina je proto užitečná pouze ve zprávách, když je použito slovo GENDER. To dává překladatelům nápovědu, že GENDER lze ve zprávě použít. Také se vyhne varováním na translatewiki o chybějících parametrech, když chybí volitelný parametr uživatelského jména (to se stává zvláště často ve zprávách záznamu protokolu).

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. Pořadí zpráv v souboru by mělo zhruba odpovídat funkcím vašeho projektu. Umístěte zprávy ze stejné funkce vedle sebe. To pomáhá překladatelům udržet pozornost a být efektivní a konzistentní.
  7. Na začátek souboru umístěte zprávy, u kterých se očekává, že budou nejzákladnější a nejčastěji používané, a na konec zprávy, které jsou vzácnější a technicky vyspělejší.

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 prvky, jako jsou značky HTML, které byste mohli změnit v jiných jazycích, aniž byste těmito jazyky hovořili. 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ázané), "open" (otevřené) nebo "blocked" (blokované), 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 (Screenshot) 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 "hamburger", "nav" nebo "comps".
  • Zvažte sepsání slovníku 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 uvádí hlavní místa, kde můžete najít pomoc zkušených a znalých lidí ohledně i18n.

Správně používání parametrů zpráv a přepínačů

To je předpokladem správné formulace vašich zpráv.

Vyhněte se opětovnému použití zprávy

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. Zprávy tvořené více kusy textu, případně s určitou nepřímostí, nazývané také "řetězení řetězců", v kódu, který nelze přímo ovládat překladateli, se v žargonu vývojářů nazývají "lego" nebo "patchwork" (slátaniny) zprávy. Správně přeložit "lego" zprávy je prakticky nemožné.

Udělejte z každé zprávy ú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í

Hlavní stránka: Manual:Messages API#Referring to other messages

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

Zprávy pište v přirozeném jazyce

Pokud je to možné, pište zprávy přirozeným lidským jazykem. Zkuste si zprávu přečíst nahlas a zamyslete se: je to něco, co zní jako správná gramatická angličtina, kterou lidé mluví? Pokud je to v angličtině složité, těžko vyslovitelné nebo jakkoli nepřirozené, bude to pro překladatele a uživatele v jiných jazycích ještě těžší.

Vyhněte se interpunkci, která je příliš technická nebo byrokratická nebo kterou nelze přečíst nahlas. Lomítko (/) by mělo být obvykle nahrazeno or. And/or by mělo být nahrazeno and nebo or. Věty spojované čárkou, by měly být rozděleny do kratších vět.

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 wikinách. Šablony jsou pro wikiny 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 ve větách časy od dat

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 fungoval {{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 wikin 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[2] 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ů JavaScriptu 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.)

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> značkami, pravítka nad nebo pod a podobně, by obvykle neměly být součástí zpráv. Představují bezpečnostní rizika, zbytečně zatěžují překladatele, zvětšují velikost souboru zpráv a mohou být náhodně změněny nebo přeskočeny v procesu překladu. Obecně, pokud můžete, se ve zprávách vyhněte raw HTML.

Přeložené 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 přeložené zprávy kratší než čínské a jen zřídka kratší než anglické. Často však najdete překlady, které jsou mnohem delší než 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..

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.[3]

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, který chcete vložit do závorek */ )->escaped()
wfMessage( 'brackets' )->rawParams( /* text, který chcete vložit do závorek */ )->escaped()
wfMessage( 'quotation-marks' )->rawParams( /* text přejde do uvozovek */ )->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žití teček

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] …
  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,[4], 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 hmoty 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 wikinách 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.

Některé zprávy vyžadují na konci mezeru, například 'oddělovač slov' (který se ve většině jazyků skládá pouze z mezery). Pro podporu takových případů použití jsou ve zprávách povoleny následující entity HTML a transformovány na skutečné znaky i když zpráva jinak neumožňuje formátování wikitextu nebo HTML:[5]

Související poznámka, jakékoli další prvky syntaxe ovlivněné transformací před uložením nesmí být také použity ve zprávách, protože budou transformovány, pokud bude zpráva na wiki upravena.

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

Poznámky pod čarou

  1. ↑ Některé lintry odmítnou seznamy zpráv pouze s jednou položkou, např.: mediawiki/msg-doc nepřijímá platné dokumenty s jedním záznamem.
  2. ↑ http://dev.w3.org/csswg/css3-writing-modes/
  3. ↑ w:Quotation_mark#Summary_table
  4. ↑ http://www.w3.org/QA/Tips/noClickHere
  5. ↑ https://github.com/wikimedia/mediawiki/blob/REL1_34/includes/cache/MessageCache.php#L887
Retrieved from "https://www.mediawiki.org/w/index.php?title=Help:System_message/cs&oldid=6759173"