Jump to content

Příručka:Zprávy API

From mediawiki.org
This page is a translated version of the page Manual:Messages API and the translation is 99% complete.
Outdated translations are marked like this.
Languages:
i18n dokumenty

Zprávy MediaWiki lze v kódu použít prostřednictvím třídy Message a jejích přidružených metod.

Parametry zprávy

Některé zprávy mají parametry. Jsou reprezentovány $1, $2, $3, … v (statických) textech zpráv a nahrazovány za běhu. Typickými hodnotami parametrů jsou čísla ("3" v "Smazat 3 verze?"), nebo uživatelská jména ("Bob" v "Stránka naposledy upravena Bobem"), názvy stránek, odkazy a tak dále, nebo někdy jiné zprávy. Mohou být libovolně složité.

Seznam parametrů definovaných pro každou konkrétní zprávu je umístěn ve speciálním souboru "qqq.json" umístěném ve složce "languages/" MediaWiki - více v dokumentaci zprávy.

Je vhodnější používat celá slova s magickými slovy PLURAL, GENDER a GRAMMAR. Například, {{PLURAL:$1|subpage|subpages}} je lepší než sub{{PLURAL:$1|page|pages}}. Usnadňuje vyhledávání.

Odkazování na jiné zprávy

Někdy je vhodné odkazovat na dílčí zprávy ve zprávě, např. ve frázích jako "Use the X button" (použijte tlačítko X) nebo "Visit the Y page" (navštivte stránku Y), abyste zajistili, že překlady budou konzistentní. Chcete-li to provést, můžete použít následující syntaxi:

  • {{int:X}} - pro použití dílčí zprávy v jazyce rozhraní. Často se používá při odkazování na tlačítka formuláře nebo navigaci na webu, např. showpreview.
  • {{MediaWiki:Y}} - pro použití dílčí zprávy v jazyce obsahu. Používá se, když dílčí zpráva definuje přeložitelný název místní stránky, např. mainpage, grouppage-sysop, policy-url.
  • {{#Special:Z}} - použít název speciální stránky v jazyce obsahu.

Pokud potřebujete něco složitějšího (např. použitá dílčí zpráva závisí na konfiguraci), analyzujte ji ve svém kódu a předejte celou dílčí zprávu jako parametr.

Příklad: 

Before saving, use the {{int:foo-test}} button to test the changes. Visit [[{{MediaWiki:foo-help}}|the help page]] to learn more.Customize this feature at [[{{#Special:Preferences}}]].

Přepínače zpráv…

Hodnoty parametrů občas ovlivňují přesné znění nebo gramatické variace ve zprávách. Neuchylujeme se k ošklivým konstrukcím jako "$1 (sub)page(s) of his/her userpage", protože ty jsou pro uživatele špatné a my to umíme lépe. Místo toho vytváříme přepínače, které jsou analyzovány podle hodnot, které budou známy za běhu. Text statické zprávy pak poskytuje každou z možných voleb v seznamu, před kterým je uveden název přepínače a odkaz na hodnotu, která je rozdílem. To se podobá způsobu, jakým se v MediaWiki nazývá Parsovací funkce . K dispozici je několik typů spínačů. Tyto fungují pouze v případě, že pro zprávy provedete úplnou analýzu nebo transformaci {{.

…pro čísla přes PLURAL

MediaWiki podporuje množná čísla, což přispívá k hezčímu vzhledu produktu. Například: 

'undelete_short' => 'Undelete {{PLURAL:$1|one edit|$1 edits}}',

Pokud má být pro konkrétní číslo uveden explicitní tvar množného čísla, je to možné s následující syntaxí: 

'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.'

Uvědomte si použití PLURAL na všech číslech
Viz též: translatewiki:Plural


Když je třeba do textu zprávy vložit číslo, mějte na paměti, že některé jazyky budou muset v něm používat PLURAL, i když je vždy větší než 1. Důvodem je to, že PLURAL v jiných jazycích než v angličtině může dělat velmi odlišné a složité rozdíly, nesrovnatelné s angličtinou 1st, 2nd, 3rd , 4th, … 11th, 12th, 13th, … 21th, 22nd, 23rd, … atd.

Nepokoušejte se zadat tři různé zprávy pro případy jako "žádné položky započítány", "započítána jedna položka", "započítáno více položek". Raději nechte jednu zprávu vzít je všechny a nechte na překladatelích a PLURAL, aby pro ně náležitě ošetřili případné rozdíly v prezentaci v jejich příslušných jazycích.

Pokud je to možné, vždy uveďte číslo jako parametr. Pokud je to možné, vždy přidejte do zdrojových zpráv syntaxi {{PLURAL:}}, i když to v angličtině nedává smysl. Překladatele vede syntaxe.

Zlomková čísla jsou podporována, ale pravidla pro množné číslo nemusí být úplná.

Předávání počtu položek seznamu jako parametrů zprávám o seznamech

Nepředpokládejte, že existuje pouze jednotné a množné číslo. Mnoho jazyků má více než dvě formy, které závisí na skutečném použitém čísle, a musí používat gramatiku, které se liší podle počtu položek seznamu při vyjádření toho, co je uvedeno v seznamu viditelném pro čtenáře. Kdykoli tedy váš kód vypočítá seznam, zahrňte count( $list ) jako parametr do nadpisů, úvodních zpráv, zápatí a dalších zpráv o seznamu, i když se počet v angličtině nepoužívá. Existuje neutrální způsob, jak mluvit o neviditelných seznamech, takže můžete mít odkazy na seznamy na dalších stránkách, aniž byste museli předem počítat položky.

…pro uživatelská jména přes GENDER

'foobar-edit-review' => 'Please review {{GENDER:$1|his|her|their}} edits.'

Pokud ve zprávě odkazujete na uživatele, předejte do zprávy uživatelské jméno jako parametr a do dokumentace ke zprávě přidejte zmínku, že pohlaví je podporováno. Pokud je pravděpodobné, že v překladech pro jazyky se skloňováním pohlaví bude použit GENDER, přidejte jej explicitně do zdrojové zprávy v anglickém jazyce.

Pokud oslovujete přímo aktuálně přihlášeného uživatele, ponechte uživatelské jméno jako prázdný parametr: 

'foobar-logged-in-user' => 'You said {{GENDER:|you were male|you were female|nothing about your gender}}.'
Verze MediaWiki:
≥ 1.31
Gerrit change 398772

Pokud do zprávy zahrnete uživatelské jméno (např. "$1 vám poděkoval."), zvažte jeho předání nejprve přes wfEscapeWikitext(), abyste zajistili, že znaky jako * nebo ; nebudou interpretovány.

Uživatelé mají gramatické rody
Viz též: translatewiki:Gender


Když zpráva hovoří o uživateli nebo se týká uživatele nebo oslovuje uživatele přímo, uživatelské jméno by mělo být předáno zprávě jako parametr. Jazyky, které musí nebo chtějí používat správnou gramatiku závislou na pohlaví, tak mohou učinit. To by mělo být provedeno i v případě, že se uživatelské jméno nemá objevit ve zprávě, jako například v "informujte uživatele na jeho diskusní stránce", což je lepší udělat "informujte uživatele na {{GENDER:$1 |his|her|jejich}} diskusní stránce" také v angličtině.

To neznamená, že jste vyzýváni k "sexualizaci" jazyka zpráv: Používejte, prosím, genderově neutrální jazyk, kdykoli to lze udělat srozumitelně a přesně.

…při použití kontextu uvnitř vět pomocí GRAMMAR

K dispozici jsou také gramatické transformace pro aglutinační jazyk (Q171263) (spojovací). Například pro finštinu, kde bylo absolutní nutností učinit jazykové soubory nezávislými na webu, tj. odstranit odkazy z Wikipedie. Ve finštině se "about Wikipedia" změní na "Tietoja Wikipediasta" a "you can upload it to Wikipedia" se změní na "Voit tallentaa tiedoston Wikipediaan". Přípony se přidávají podle toho, jak se slovo používá, plus drobné úpravy základu. Existuje dlouhý seznam výjimek, ale protože bylo potřeba přeložit pouze několik slov, jako je název webu, nemuseli jsme jej zahrnout.

MediaWiki má gramatické transformační funkce pro více než 20 jazyků. Některé z nich jsou jen slovníky pro názvy stránek Wikimedie, ale jiné mají jednoduché algoritmy, které selžou ve všech případech kromě těch nejběžnějších.

Ještě předtím, než MediaWiki měla doplňkovou gramatickou transformaci, měla nominativní/genitivní rozlišení pro názvy měsíců. Toto rozlišení je u některých jazyků nutné, pokud chcete do vět nahradit názvy měsíců.

Filtrování speciálních znaků v parametrech a zprávách

Dalším (mnohem jednodušším) problémem se substitucí parametrů je escapování HTML. Přestože je MediaWiki mnohem jednodušší, dělá to docela špatně.

Použití zpráv v PHP

Varování Varování: Ujistěte se, že vždy používáte jeden z výstupních režimů uvedených níže

Zde je jednoduchý příklad: 

$out = Xml::submitButton( wfMessage( 'submit' )->text() );

wfMessage() je globální funkce, která funguje jako obal pro třídu Message a vytváří objekt Message. Tento příklad pak vyvolá metodu zprávy text(), která načte text zprávy 'submit' v aktuálním jazyce, provede určité jazykové transformace (jako je pohlaví a množné číslo) a vrátí text zprávy bez kódování speciálních znaků.

Zde je složitější příklad pomocí zprávy, která se počítá a podporuje lingvistické zpracování množného čísla: 

$out = Xml::label( wfMessage( 'numberofpages' )->numParams( $count )->text() );

Následující části vysvětlují kód.

Parametry

Dostali jsme zprávu, jako je tato: 

{
    "msg": "Values are $1, $2"
}

Parametry zprávám, které je potřebují, předáváte několika způsoby: 

wfMessage( 'msg', 'param1', 'param2' )->plain();
wfMessage( 'msg' )->params( 'param1', 'param2' )->plain();
wfMessage( 'msg', [ 'param1', 'param2' ] )->plain();

První přístup je nejběžnější, druhý přístup použijte při míchání různých typů parametrů a třetí můžete použít k dynamické konstrukci objektů zpráv z jiných dat. Existují různé typy parametrů: 

wfMessage( 'msg' )->params( $username )->plain();
wfMessage( 'msg' )->rawParams( $link )->plain();
wfMessage( 'msg' )->plaintextParams( $userInput )->plain();

wfMessage( 'msg' )->numParams( $count )->plain();
wfMessage( 'msg' )->durationParams( $duration )->plain(); // MediaWiki 1.22+
wfMessage( 'msg' )->expiryParams( $expiry )->plain(); // MediaWiki 1.22+
wfMessage( 'msg' )->timeperiodParams( $period )->plain(); // MediaWiki 1.22+
wfMessage( 'msg' )->sizeParams( $size )->plain(); // MediaWiki 1.22+
wfMessage( 'msg' )->bitrateParams( $bitrate )->plain(); // MediaWiki 1.22+
params()
Normální parametr nahrazování zprávy.
rawParams()
Nahrazuje parametr poté, co byla zpráva jinak zpracována. To znamená, že tyto parametry nejsou k dispozici pro funkce analyzátoru, ani nejsou escapovány, pokud je použit escapující výstupní formát (viz níže). Ujistěte se, že je správně sami escapujete.
plaintextParams()
Jako rawParams(), ale escapuje. To je užitečné, když předáváte uživatelský vstup, který může obsahovat wikitext, který by neměl být analyzován.

Každá funkce z druhé skupiny před substitucí naformátuje hodnotu specifickým způsobem. Pokud zpráva používá {{PLURAL:}}, musí být použito numParams(). V některých případech ji možná nebudete chtít používat, i když máte číslo, například ID revize. Ostatní funkce odpovídají jazykovým funkcím formatDuration, formatExpiry, formatTimePeriod, formatSize a formatBitrate a jsou pouze zkratkami pro jejich přímé volání.


Jazyk

Chcete-li přepsat jazyk, ve kterém chcete zprávu odeslat, existuje jedna metoda a jedna zkratka pro běžný případ použití jazyka obsahu wiki. V druhém případě můžete použít buď kód jazyka, nebo objekt jazyka. Uplatňují se obvyklé jazykové nouzové řetězce, takže skutečná zpráva, kterou dostanete, může být v jiném jazyce, než je požadováno, pokud překlad neexistuje. 

wfMessage( 'message-key' )->inContentLanguage();
wfMessage( 'message-key' )->inLanguage( $lang );

Výstupní režimy a escapování

Třída Message, a tedy objekt vrácený wfMessage(), má pět výstupních režimů:

  • plain() - vrátí text zprávy tak, jak je. Nahrazují se pouze parametry[1]
  • text() - transformuje text zprávy (viz MessageCache::transform()), který transformuje všechny {{}} včetně šablon a funkcí analyzátoru jako PLURAL a GENDER, ale neescapuje ani neodstraňuje
  • escaped() - totéž jako 'text', ale také jej escapuje pro použití v HTML
  • parse() - analyzuje text zprávy z wikitextu do HTML a čistí (MessageCache::parse(), která volá Parser)
  • parseAsBlock() - výstup je zabalen do prvku HTML na úrovni bloku, pokud již není, podobně jako OutputPage::addWikiMsg

Pamatujte, že funkce Html:: uniknou všemu, co je do nich vloženo, takže s těmito funkcemi používejte formát text(), abyste se vyhnuli dvojitému escapování. Nejběžnějším výstupním formátem je tedy text(). Také se ujistěte, že používáte parse() nebo parseAsBlock(), pokud zpráva obsahuje wikitext, jinak bude wikitext pouze escapován a vydán jako prostý text.

Při použití wfMessage() nebo $this->msg() byste měli vždy zadat typ výstupu. Je vhodné, když text() posíláte přes addWikiText().

Jaký výstupní režim použít

Obecně řečeno, nejběžnější režimy, které budete používat, jsou ->parse() a ->text(). Na většině míst, kde je podporováno značení HTML, použijete ->parse() a na místech, kde se obsah stane kódem html nebo kde není podporováno značení HTML, použijete ->text().

Některé běžné případy:

  • Pokud vkládáte zprávu do textové části (třetí argument) Html::element, použijte ->text(). Můžete také zvážit místo toho použití Html::rawElement() a použití režimu ->parse().
  • Pokud vkládáte text (třetí argument) Html::rawElement(), měli byste obecně použít ->parse().
  • Pokud vkládáte do atributů (druhý argument) Html::rawElement() nebo Html::element(), použijte ->parse()
  • Pokud ručně vytváříte html atributy, měli byste použít ->escaped(). Nikdy byste však neměli vytvářet html atributy ručně
  • Pro $out->addWikiText(), kde $out je objekt OutputPage, použijte ->text() nebo ->plain(). Zvažte však, zda byste místo toho raději nepoužili $out->addWikiMsg.
  • Místo $out->addHTML() použijte ->parse()

Zřetězení metod

Většina metod zpráv vrací aktuální objekt, takže můžete pohodlně volat jednu po druhé, abyste provedli operaci s objektem, než konečně vrátíte jeho text. Toto se nazývá řetězení metod. Zde je příklad: 

wfMessage( 'key' )
	->params( 'apple' )
	->numParams( $numOfApples )
	->setContext( $context )
	->inContentLanguage()
	->parse()

Další způsoby tisku zpráv

Obecná funkce zpráv v MediaWiki je wfMessage. Protože však ve zprávě může hodnota kouzelných slov záviset na kontextu, existují pro tuto funkci různé obaly, které automaticky nastaví správný kontext.

OutputPage má několik metod, které se připojují přímo k vygenerovanému výstupu. Ty užitečné jsou: 

$out->addWikiMsg( 'pageheader' );
$out->wrapWikiMsg( '<div class="error">\n$1\n</div>', [ 'someerrormessage', $user->getName() ] );

Oba výše uvedené analyzují wikitext v kontextu aktuální stránky před jeho připojením do výstupní vyrovnávací paměti.

Třídy rozšiřující ContextSource mají metodu msg, která automaticky nastavuje aktuální kontext (jazyk, aktuální stránka atd.). Proto se doporučuje použít $this->msg() pro tyto třídy, jako jsou speciální stránky. Zde je neúplný seznam těchto tříd:[2]

  • CategoryViewer
  • HTMLForm
  • LogEventsList
  • DifferenceEngine
  • OutputPage
  • IndexPager
  • ImageHistoryList
  • ApiBase
  • ChangesList
  • Skin
Varování Varování: Třída QuickTemplate a její podtřídy (BaseTemplate) mají metodu s názvem msg, která se liší od metody ContextSource. V těchto třídách $this->msg() jednoduše vypíše escapovaný text zprávy.

Příklady správného použití: 

wfMessage( 'key' )->numParams( 567 )->text();
$this->msg( 'key' )->numParams( 567 )->parse();

Příklady nesprávného použití: 

wfMessage( 'key', 345 )->parseInline(); # Číslo není správně naformátováno
$this->msg( 'key', 345 )->numParams( 234 )->plain() # Plurální syntaxe se nepřevádí do prostého formátu

Používání zpráv v JavaScriptu

Viz též: ResourceLoader/Core modules#mediaWiki.message
Tato stránka se zabývá pouze jádrem MediaWiki. Podívejte se místo toho na konkrétní dokumentaci pro modul jquery.i18n.

Získávání zpráv klientem

Abychom mohli zprávy používat, musíme se ujistit, že zprávy jsou nejprve dostupné na straně klienta. To lze provést pomocí modulu ResourceLoader (nejběžnější) nebo API dotazu z JavaScriptu (vzácné).

Použití modulu ResourceLoader

Viz též: Manual:$wgResourceModules
Toto je nejběžnější způsob doručování zpráv. Toto byste měli používat, pokud k tomu nemáte dobrý důvod.

Použijeme ResourceLoader, abychom se ujistili, že zprávy jsou dostupné na straně klienta. Za tímto účelem ve svých modulech ResourceLoader definujte zprávy, které se mají exportovat na stranu klienta.

Pokud plánujete použít mw.message(…).parse() ke generování HTML z wikitextu ve zprávách rozhraní, pak je důležité načíst modul mediawiki.jqueryMsg.

Příklad (extension.json): 

{
	"ResourceModules": {
		"ext.abuseFilter.edit": {
			"scripts": "ext.abuseFilter.edit.js",
			"messages": [
				"abusefilter-edit-syntaxok",
				"abusefilter-edit-syntaxerr",
				"abusefilter-http-error",
				"abusefilter-edit-throttle-placeholder",
				"abusefilter-edit-tag-placeholder",
				"abusefilter-edit-warn-leave",
				"unknown-error",
				"jan",
				"feb",
				"mar"
			],
			"dependencies": [
				"mediawiki.util",
				"mediawiki.api",
				"mediawiki.confirmCloseWindow",
				"jquery.textSelection",
				"jquery.spinner",
				"oojs-ui-core",
				"oojs-ui-widgets"
			]
		}
	}
}

Použití dotazu API z JavaScriptu

Toto není běžný způsob načítání zpráv. Tuto možnost byste měli používat pouze v případě, že existuje dobrý důvod, proč nemůžete použít výše uvedenou metodu modulu ResourceLoader.

Můžete použít následující kód:

Verze MediaWiki:
≥ 1.27
 
// Kdy: Modul 'mediawiki.api' je načten a stránka je připravena
$.when( mw.loader.using( [ 'mediawiki.api', 'mediawiki.jqueryMsg' ] ), $.ready )
    // Poté: Načtěte zprávy, které potřebujete (pokud ještě nejsou načteny)
    .then( () => new mw.Api().loadMessagesIfMissing( [ 'january', 'february', 'march' ] ) )
    // Pak: Pracujte s nimi
    .then( doStuff );

Chcete-li získat zprávy v jiném jazyce, než je jazyk UserLanguage, použijte getMessages místo loadMessagesIfMissing a zadejte cílový jazyk jako pole "amlang" volitelného druhého parametru, například takto: 

// Kdy: Modul 'mediawiki.api' je načten. Není třeba čekat, až bude stránka připravena.
$.when( mw.loader.using( [ 'mediawiki.api' ] ) )
    // Pak: Získejte nějaké zprávy v French (kód jazyka 'fr')
    .then( () => new mw.Api().getMessages( [ 'january', 'february', 'march' ], { amlang: 'fr' } ) )
    // Pak: Pracujte s nimi
    .then( doStuff );
// doStuff je funkce, která obdrží jako svůj první parametr objekt, který vypadá takto:
// { february: "février", january: "janvier", march: "mars" }


Použití zpráv

Zprávy definované ve výše uvedeném příkladu budou dostupné na straně klienta a bude k nim přístup mw.message( 'message-key-name' ).

Například: 

$( '<div>' ).text( mw.message( 'translate-msggroupselector-projects' ).text() );

Všimněte si, jak používáme metodu jQuery text ke správnému escapování našeho výstupu při použití formátu mw.message text.

Pokud vaše zpráva obsahuje formátování wikitextu, můžete místo toho použít následující: 

$( '<div>' ).append( mw.message( 'translate-msggroupselector-projects' ).parseDom() );

Zde používáme metodu jQuery append pro vložení uzlů DOM vrácených formátem parseDom mw.message.

Ve starším kódu se také můžete setkat s následujícím: (parseDom nebyl k dispozici až do MediaWiki 1.27) 

$( '<div>' ).html( mw.message( 'translate-msggroupselector-projects' ).escaped() );
$( '<div>' ).html( mw.message( 'translate-msggroupselector-projects' ).parse() );

Existují i další správné kombinace, ale kdykoli je to možné, držte se výše uvedených vzorů, abyste se vyhnuli zranitelnosti XSS a usnadnili pochopení pro ostatní.

Do zprávy můžeme také předat dynamické parametry (tj. hodnoty pro $1, $2 atd.), jak je uvedeno níže. 

$( '<div>' ).text( mw.message( 'hello-user', username ).text() );

Ve výše uvedených příkladech si uvědomte, že zpráva by měla být definována v souboru i18n. Pokud klíč zprávy není nalezen v žádném souboru i18n, výsledkem bude klíč zprávy v zakřivených lomených závorkách U+29FC/U+29FD (součást matematických symbolů), například '⧼message-key-foo⧽'. Ve starších verzích MediaWiki byl klíč zprávy vrácen v lomených závorkách ASCII, například '<message-key-foo>', což mohlo generovat neplatné nebo falešné prvky HTML. V případě, že klíč zprávy neexistuje, metoda .exists() vráceného objektu zprávy také vrátí hodnotu false namísto true.

Chcete-li použít zprávu, která nesmí projít analyzátorem (např. při předávání dat JSON jako zprávy nebo když bude zpráva použita jako předem načtený text stránky), použijte: 

mw.message( 'foobar' ).plain()

Možnosti formátu

Pokud neurčíte výstupní formát, mw.message pouze vrátí objekt Message. Pro výstup samotné zprávy byste měli zadat výstupní formát. Formáty jsou většinou stejné jako na stránce PHP:

  • mw.message( 'foobar' ).plain() Vrátí text zprávy tak, jak je. Nahrazují se pouze parametry.
  • mw.message( 'foobar' ).text() Transformuje text zprávy (všechny podporované bloky {{}} jsou nahrazeny transformovanými výsledky). Podrobnosti o tom, co je podporováno, najdete v #Podpora funkcí v JavaScriptu. Například některá klíčová slova ({{int:}} (ale pouze bez parametrů), {{GENDER}}, {{SITENAME}} atd.) fungují, ale transkluze (např. {{MediaWiki:}}) a Magická slova na straně serveru jako {{NUMBEROFEDITS}} nebo {{ns:Project}} nefungují,
  • mw.message( 'foobar' ).escaped() HTML kódovaná verze text.
  • mw.message( 'foobar' ).parse() Analyzuje text zprávy z wikitextu do HTML. Podporuje vše od režimu text, stejně jako většinu odkazů a umožňuje uvedené HTML.
  • mw.message( 'foobar' ).parseDom() Jako parse(), ale místo řetězce HTML vrátí kolekci jQuery.
Varování Varování: Pokud není načten modul mediawiki.jqueryMsg, všechny výše uvedené metody se chovají v podstatě jako plain() s možným escapováním.
Neexistuje žádný ekvivalent parseAsBlock. V případě potřeby zabalte výstup sami do blokového prvku.

Parametry

Parametry lze zadat jako další argumenty k mw.message(). Mohou být předány jako řetězce nebo jako uzly DOM / kolekce jQuery.

Na rozdíl od PHP je wikitext v parametrech neanalyzován. Ve skutečnosti se všechny parametry řetězce chovají jako plaintextParams().

Parametry DOM/jQuery lze použít k dosažení ekvivalentu rawParams().

Jiné formáty parametrů nejsou podporovány. Místo numParams() musíte čísla před předáním jako parametry naformátovat pomocí mw.language.convertNumber(). 

$( '<div>' ).text( mw.message( 'translate-msggroupselector-view-subprojects', mw.language.convertNumber( count ) ).text() );

Podpora funkcí v JavaScriptu

Varování Varování: Podpora Wikitextu ve zprávách JS vyžaduje načtení modulu mediawiki.jqueryMsg, jinak budou tyto funkce tiše ignorovány.

Zprávy JavaScript podporují pouze malou podmnožinu syntaxe wikitextu. Mezi podporované funkce patří:

  • Interní odkazy (kromě pipe triku)
  • Explicitní externí odkazy (žádné automaticky číslované a bezplatné odkazy)
  • Magická slova SITENAME, PAGENAME, PAGENAMEE, $2, $3, (v MW 1.38+) SERVERNAME
  • Funkce analyzátoru PLURAL, GENDER, GRAMMAR, int, ns, formatnum, lc, uc, lcfirst, ucfirst
  • HTML tagy, které jsou povoleny ve wikitextu (HTML musí být ve správném formátu)
  • HTML entity &#039;, &quot;, &lt;, &gt;, &amp;
  • Značka ‎<nowiki>

Zvláštní syntaxe wikitextu, která nejsou podporovány:

  • Šablony
  • Nemístní odkazy na interwiki
  • Všechny ostatní funkce analyzátoru a kouzelná slova
  • Moduly (například Module:String)
  • Všechny ostatní značky podobné XML (značky rozšíření)
  • Tučné a kurzíva ''', '' (místo toho použijte ‎<b>, ‎<i>)
  • Seznamy používající *, # (místo toho použijte ‎<ul> nebo ‎<ol>, ‎<li>)
  • Seznamy definic / odsazení pomocí ;, : (místo toho použijte ‎<dl>, ‎<dt>, ‎<dd>)
  • Více odstavců (místo toho použijte ‎<p>)
  • Samouzavírací HTML tagy
  • Komentáře <!-- -->
  • Některé typy vnoření (např. {{PLURAL:$1|<strong>$1</strong>}})

Šablonu doc-jqueryMsg lze použít k dokumentu takových zpráv, aby překladatelé věděli, která omezení wikitextu platí.

mw.msg

Funkce mw.msg() se běžně používá jako zkratka pro mw.message().text().

Export zpráv prostřednictvím zpětných volání ResourceLoader

Pokud potřebujete zpracovat zprávu na serveru a odeslat výsledek klientovi (např. protože potřebujete analyzovat zprávu pomocí funkcí analýzy, které nejsou podporovány v JS), můžete to udělat pomocí souborů balíčku callback ve vašem modulu ResourceLoader. Pokud to uděláte, dejte pozor, abyste použili $context->msg(), protože použití wfMessage() způsobí chyby.

Používání zpráv v Lua

Moduly napsané v Lua pomocí Scribunto fungují podobně jako šablony a mají přístup ke zprávám MediaWiki. Knihovna Lua MediaWiki obsahuje třídu mw.message pro zpracování zpráv. Úplné rozhraní API naleznete v úplné dokumentaci knihovny zpráv Lua. Zde je jednoduchý příklad: 

local p = {}

function p.nmembers( frame )
	local nmembersMsg = mw.message.new( 'nmembers' )
	nmembersMsg:numParams( 3 ) -- Tím je zajištěna lokalizace čísel
	-- Zobrazí zprávu v jazyce wiki. frame:preprocess rozšiřuje klauzuli {{plural}}.
	return frame:preprocess( nmembersMsg:plain() )
end

return p

Poznámky o pohlaví, gramatice, množném čísle

Viz také #Přepínání zprávy…. Samotná syntaxe je zdokumentována na stránce Nápověda:Magická slova#Lokalizace a souvisejících stránkách.

Obecně platí, že magická slova GENDER, GRAMMAR a PLURAL fungují identicky v PHP i JavaScriptu.

  1. Aby fungovaly, musíte použít text, escaped, parse nebo parseAsBlock výstupní formáty.
  2. Musíte předat příslušný parametr jako normální parametr do zprávy.
    • Parametr je číslo pro PLURAL. Uživatelské jméno ve formátu prostého textu nebo wikitextu na GENDER v PHP. Pohlaví z předvoleb nebo objekt uživatele na GENDER v JavaScriptu (viz níže).
    • Chcete-li v PHP povolit množné číslo a správnou lokalizaci čísel, musíte pro číslo použít numParams, viz také #Řetězení.
    • Chcete-li v JavaScriptu povolit množné číslo a správnou lokalizaci čísel, musíte pro číslo použít mw.language.convertNumber

Příklad syntaxe PLURAL

# Jednoduché množné číslo
'key' => '$1 crying {{PLURAL:$1|baby|babies}}'

GENDER v JavaScriptu

Vyžaduje explicitní jqueryMsg, viz #Používání zpráv v JavaScriptu.

Pokud máte zprávu, řekněme "message-key-gender-foo": "{{GENDER:$1|he|she|they}} created an article", v JavaScriptu, můžete ji použít, jak je uvedeno níže: 

mw.message( 'message-key-gender-foo', 'male' ).text(); // vrátí 'he created an article'
mw.message( 'message-key-gender-foo', 'female' ).text(); // vrátí 'she created an article'
mw.message( 'message-key-gender-foo', 'unknown' ).text(); // vrátí 'they created an article'

Namísto přímého předání pohlaví můžeme předat jakýkoli objekt "podobný uživateli" s volbou pohlaví. Například aktuální uživatelský objekt mw.user. 

var user = mw.user; // současný uživatel
mw.message( 'message-key-gender-foo', user ).text(); // vrácená zpráva bude založena na pohlaví aktuálního uživatele.

Pokud je předané pohlaví neplatné nebo neznámé, použije se genderově neutrální forma, tak jak je definována pro každý jazyk. Pokud záměrně chcete neutrální formu, předejte 'unknown'.

Nakonec, pokud chcete použít pohlaví aktuálního uživatele, můžete předat prázdný řetězec: 

// následující řádek ilustruje obsah zprávy, tento fragment můžete spustit na konzoli pro vývojáře
mw.messages.set( 'message-key-gender-foo', '{{GENDER:$1|male|female|unknown}}' );
mw.user.options.values.gender = 'female'; // dočasně manipulovat s vaší preferencí pohlaví
mw.message( 'message-key-gender-foo', '' ).text(); // návratová hodnota závisí na vaší preferenci pohlaví

PLURAL v JavaScriptu

To vyžaduje explicitní jqueryMsg, viz #Používání zpráv v JavaScriptu.

Pokud máte zprávu, řekněme 'message-key-plural-foo' => 'There {{PLURAL:$1|is $1 item|are $1 items}}' , v JavaScriptu, můžete ji použít, jak je uvedeno níže: 

mw.message( 'message-key-plural-foo', count ).text();
// vrátí 'There is 1 item', pokud count = 1 (počet)
// vrátí 'There are 6 items', pokud count = 6 (počet)

Pomoc s nahrazením zastaralých funkcí wfMsg*

Tyto funkce byly odstraněny počínaje MediaWiki 1.27 LTS.

Kód používající tyto funkce má často nesprávné escapování a další problémy s kvalitou kódu, takže se také doporučuje

  • nahradit všechny funkce Xml:: jejich ekvivalenty Html::, což usnadňuje dělat správnou věc;[3]
  • pokud je to možné, vyhněte se globálům a použijte msg() (viz nad);
  • kde to je vhodné, nahraďte htmlspecialchars() ->escaped().
Změna kódu Popis
Namísto:
wfMsg( 'key' );

napište:

wfMessage( 'key' )->text();
  
Namísto:
wfMsgExt( 'key', SOME_FORMAT, 'apple' );

napište:

wfMessage( 'key', 'apple' )->SOME_FORMAT_FUNCTION();
 Druhý parametr určuje výstupní režim, obvykle vyjádřený jako pole jako array( 'escape' ), ale někdy stejně jako 'escape': Je třeba jej nahradit podle #Režimy výstupu a escapování, jako ->escaped().
Namísto:
wfMsgExt( 'key', array( 'parse' ), 'apple' );

napište:

wfMessage( 'key', 'apple' )->parseAsBlock();
 Použije úplnou analýzu a zabalte výstup do značek HTML na úrovni bloku.
Namísto:
wfMsgExt( 'key', array( 'parseinline' ), 'apple' );

napište:

wfMessage( 'key', 'apple' )->parse();
 Použije úplnou analýzu. Parseinline se používá, protože je užitečnější při předběžném vytváření HTML. Při běžném používání je lepší použít OutputPage::(add|wrap)WikiMsg.
Namísto:
wfMsgExt( 'key', array( 'parsemag' ), 'apple', 'pear' );

napište:

wfMessage( 'key', 'apple', 'pear' )->text();
 Místa, kde nelze použít HTML. {{-transformace je dokončena.
Namísto:
wfMsgHtml( 'key', 'apple' );

napište:

wfMessage( 'key' )->rawParams( 'apple' )->escaped();
 wfMsgHtml neescapuje parametry: Pro získání stejného výsledku musíte použít rawParams. Zkontrolujte, zda je parametr skutečně bezpečný pro výstup HTML. Pokud je zpráva poté vydána jako HTML, musíte použít escaped() pro bezpečnost: Také escapuje parametry a to není vždy žádoucí, i když na tom nezáleží, např. když je parametrem číslo.
Namísto:
wfMsgForContent( 'key' );

napište:

wfMessage( 'key' )->inContentLanguage()->text();
 Získání zprávy v jazyce obsahu wiki ($wgLanguageCode ).
Namísto:
wfMsgForContentNoTrans( 'key' );

napište:

wfMessage( 'key' )->inContentLanguage()->plain();
 Získání zprávy v jazyce obsahu wiki ($wgLanguageCode ), ale zprávu netransformujte.
Namísto:
wfEmptyMsg( 'key', $message = wfMsgForContent( 'key' ) );

napište:

wfMessage( 'key' )->inContentLanguage()->isBlank();
 Zkontroluje, zda je 'klíčová' zpráva v jazyce obsahu wiki prázdná. Často je isDisabled() vhodnější a měl by být použit místo něj.
Namísto:
wfMsgReal( $error['message'], $error['params'] );

napište:

?
 Neexistuje jednoduchá výměna, záleží na parametrech. V první řadě by neměl být nikdy použit.
Namísto:
wfMsgGetKey

napište:

?
 Neexistuje jednoduchá výměna, záleží na parametrech. V první řadě by neměl být nikdy použit.


Související odkazy

Poznámky pod čarou

  1. ↑ I když je použití tohoto režimu k zobrazení obsahu HTML možné, doporučuje se použít wikitext a použít režim parse() k jeho transformaci do HTML.
  2. ↑ Obecněji řečeno, použijte $this->msg() v nestatických funkcích objektů IContextSource.
  3. ↑ Například Xml::tags() není escapována.
Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:Messages_API/cs&oldid=6895919"