API:Localisation/cs

Dokumentuje věci specifické pro lokalizaci API akce MediaWiki. 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.

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.



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 bude stejný jako klíč použitý v tomto poli, zatímco pro moduly přidané do,  nebo  to bude klíč s předponou "query+".


 * Popisová zpráva, dříve vracená metodou [//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#a49b8857e40e254e0af27fd281f3a2230 getDescription], byla rozdělena do dvou: Zpráva  s jednořádkovým shrnutím modulu a   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 . To bylo potlačeno implementací metody [//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#aa0c499873fba5c934b98aae65e61a33d getDescriptionMessage], ale případy, kdy to bylo potřeba, byly vzácné.
 * Zprávy s popisem parametrů, které dříve vracela metoda [//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#a1d9406dc4a7b6e5b69554c492ee464f6 getParamDescription], jsou  (kde   je klíč z [//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#a6806d2768e2bf6ea57e6b081bf4a9f9f getAllowedParams]). To lze přepsat nastavením hodnoty   v datové struktuře vrácené z [//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#a6806d2768e2bf6ea57e6b081bf4a9f9f 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í  nemusí dokumentovat parametr token . Toto je automaticky řešeno ApiBase.
 * V [//doc.wikimedia.org/mediawiki-core/master/php/classApiBase.html#a6806d2768e2bf6ea57e6b081bf4a9f9f getAllowedParams] je k dispozici několik dalších konstant. Podrobnosti viz ApiBase.
 * Parametry s polem pro  mohou použít   k určení, že každá hodnota je zdokumentována samostatně. Tyto zprávy jsou ve výchozím nastavení  . Pokud jsou zprávy pojmenovány podle výchozího nastavení, není třeba zprávy mapovat na hodnoty v poli  (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.



Dokumentace zprávy
Při dokumentování zpráv v použijte následující šablony:


 * doc-apihelp-summary
 * doc-apihelp-description
 * doc-apihelp-extended-description
 * doc-apihelp-param
 * doc-apihelp-paramvalue
 * doc-apihelp-paraminfo
 * doc-apihelp-example



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:


 * pro zmínku o klíčích parametrů a také odkazy na proměnné jako $wgMiserMode.
 * 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.
 * pro zmínku o klíčích nebo hodnotách ve výstupu API.
 * na cokoliv jiného, co je počítačový kód, např. "záhlaví " nebo "stránka ".
 * 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 " " 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  a zprávu lze lokalizovat obvyklým způsobem. Stejně tak pro varování s. Další podrobnosti najdete na stránce.

Chybové zprávy API mají obvykle klíče zpráv začínající na  a varování na. 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í 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ří


 * Akce API MediaWiki
 * Použití funkcí API



Související odkazy

 * – Návrh dokumentu z roku 2014 s informacemi pro převod starých modulů API na současný systém.