API:Lokalizace

From mediawiki.org
This page is a translated version of the page API:Localisation and the translation is 100% complete.
Languages:
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 a apihelp-$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é.
  • 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 hodnoty ApiBase::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žít ApiBase::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 poli ApiBase::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:

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

Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Localisation/cs&oldid=6163285"