API:Lokalizace
Tato stránka je součástí dokumentace k API Action MediaWiki. |
Verze MediaWiki: | ≥ 1.25 Gerrit change 160798 |
Dokumentuje věci specifické pro lokalizaci API akce MediaWiki (api.php
).
Obecné komentáře k lokalizaci MediaWiki najdete na stránce Localisation.
Soubory zpráv
Lokalizační zprávy pro jádro MediaWiki jsou umístěny pod includes/api/i18n.
U rozšíření pro zprávy, které se používají pouze pro dokumentaci API a které většina koncových uživatelů nevidí, měly být v samostatném souboru s použitím běžných mechanismů pro více souborů. Viz lokalizační dokumentace o přidávání nových zpráv.
Zprávy nápovědy
Pojmenování
Zprávy nápovědy pro moduly API mají jmenný prostor pomocí "cesty k modulu", což je řetězec používaný pro parametr "modules" action=help. Pro moduly přidané do $wgAPIModules bude stejný jako klíč použitý v tomto poli, zatímco pro moduly přidané do $wgAPIPropModules , $wgAPIListModules nebo $wgAPIMetaModules to bude klíč s předponou "query+".
- Popisová zpráva, dříve vracená metodou getDescription(), byla rozdělena do dvou: Zpráva
apihelp-$path-summary
s jednořádkovým shrnutím modulu aapihelp-$path-extended-description
obsahující jakoukoli další dokumentaci na úrovni modulu. Ty mohou být potlačeny odpovídajícími metodami, ale případy, kdy je to potřeba, jsou vzácné.- Před 1.30 se používala zpráva
apihelp-$path-description
. To bylo potlačeno implementací metody getDescriptionMessage(), ale případy, kdy to bylo potřeba, byly vzácné.
- Před 1.30 se používala zpráva
- Zprávy s popisem parametrů, které dříve vracela metoda getParamDescription(), jsou
apihelp-$path-param-$name
(kde$name
je klíč z getAllowedParams()). To lze přepsat nastavením hodnotyApiBase::PARAM_HELP_MSG
v datové struktuře vrácené z getAllowedParams().- Parametry s popisem podobným jako "Když jsou k dispozici další výsledky, pokračujte pomocí tohoto" by měly místo předefinování duplicitní zprávy používat api-help-param-continue.
- Parametry řazení nabývající hodnot "newer" (novější) a "older" (starší) (se souvisejícími parametry "start" (začátek) a "end" (konec)) by měly místo předefinování duplicitní zprávy používat api-help-param-direction.
- Moduly využívající tokeny CSRF implementací
needsToken()
nemusí dokumentovat parametr token. Toto je automaticky řešeno ApiBase. - V getAllowedParams() je k dispozici několik dalších konstant. Podrobnosti viz ApiBase.
- Parametry s polem pro
ApiBase::PARAM_TYPE
mohou použítApiBase::PARAM_HELP_MSG_PER_VALUE
k určení, že každá hodnota je zdokumentována samostatně. Tyto zprávy jsou ve výchozím nastaveníapihelp-$path-paramvalue-$name-$value
. Pokud jsou zprávy pojmenovány podle výchozího nastavení, není třeba zprávy mapovat na hodnoty v poliApiBase::PARAM_HELP_MSG_PER_VALUE
(stále musí existovat, ale může zůstat prázdné). - Všechny příklady musí mít popisný text. Názvy zpráv by měly být v souladu s
apihelp-$path-example-$arbitrarySuffix
.
Dokumentace zprávy
Při dokumentování zpráv v qqq.json použijte následující šablony:
{{doc-apihelp-summary|cesta modulu}}
{{doc-apihelp-description|cesta modulu}}
{{doc-apihelp-extended-description|cesta modulu}}
{{doc-apihelp-param|cesta modulu|název parametru}}
{{doc-apihelp-paramvalue|cesta modulu|název parametru|hodnota parametru}}
{{doc-apihelp-paraminfo|cesta modulu|název značky s informacemi o parametru}}
{{doc-apihelp-example|cesta modulu}}
Formátování zpráv
Všechny zprávy by měly končit tečkou a měly by být gramatickými větami. Parametry předávané zprávám ve výchozím nastavení najdete v šablonách propojených z #dokumentace ke zprávám.
Používejte sémantické označení wikitextu ve zprávách:
<var>
pro zmínku o klíčích parametrů a také odkazy na proměnné jako $wgMiserMode.<kbd>
pro možné hodnoty parametrů, zmínku o parametrech s hodnotami (včetně odkazů na jiné moduly) a zmínku o vstupních hodnotách v ukázkových dokumentech.<samp>
pro zmínku o klíčích nebo hodnotách ve výstupu API.<code>
na cokoliv jiného, co je počítačový kód, např. "záhlavímax-age
" nebo "stránka<head>
".- Při použití sémantického označení nepotřebujete další uvozovky.
Pokud potřebujete odkazovat na jiné moduly API, zadejte odkaz na Special:ApiHelp a formátovač nápovědy udělá správnou věc.
Například "[[Special:ApiHelp/query+tokens|action=query&meta=tokens]]
" se v dokumentaci používá pro různé parametry token.
Odkaz Special:ApiHelp se správně vykreslí jako ukotvený odkaz na stránce, pokud je na stejné stránce nápovědy (příklad).
Podobně odkaz na konfigurační proměnné MediaWiki, jako je $wgMiserMode, by měl odkazovat na dokumentaci na mediawiki.org.
Stránky odkazované v příkladech by obecně neměly být propojeny, protože tyto odkazy na mnoha wikinách pravděpodobně neexistují.
Chyby a varování
Chyby jsou vyvolány voláním $this->dieWithError( $messageObjectOrKey );
a zprávu lze lokalizovat obvyklým způsobem.
Stejně tak pro varování s $this->addWarning( $messageObjectOrKey );
.
Další podrobnosti najdete na stránce API:Errors and warnings .
Chybové zprávy API mají obvykle klíče zpráv začínající na apierror-
a varování na apiwarn-
.
V dokumentaci ke zprávě můžete použít {{doc-apierror}}
.
Text v odpovědích API
ApiBase, a tedy všechny moduly API, jsou také kontextovými zdroji.
Ke zprávám by se obecně mělo přistupovat pomocí $this->msg()
a samotný modul API by měl být obecně předán, když je potřeba IContextSource.
Zprávy by neměly být libovolně zahrnuty do výstupu, protože by to pro klienta mohlo být užitečné.
Zlepšení lokalizací na translatewiki
Na translatewiki.net můžete přidávat a vylepšovat překlady zpráv nápovědy API stejným způsobem jako ostatní základní zprávy MediaWiki. Mezi relevantní skupiny zpráv patří
Související odkazy
- API/Architecture_work/i18n – Návrh dokumentu z roku 2014 s informacemi pro převod starých modulů API na současný systém.