Help:Extension:Translate/Translation aids/cs

Překladatelská nápověda (translation aids nebo translation helpers) je soubor modulů, které v průběhu překladu nabízejí překladateli další informace ke zprávě. Jako jsou návrhy na překlad zprávy ze strojového překladu nebo překladové paměti. Dokumentace ke zprávě nebo i tak základní věc, jakou je definice zprávy - textu, který se má přeložit.

Mezi informacemi, které jsou součástí souboru zpráv a těmi, které poskytuje překladatelská nápověda je určitý přesah. Ale v podstatě se dá říct, že v souboru zpráv jsou uloženy pouze informace, které jsou nezbytně nutné pro zpracování dobrého překladu: Definice zpráv, jejich překlady, informace o stavu překladu a záznam o posledním překladateli (protože revidovat můžete pouze zprávy, které překládal někdo jiný) atd.

Rozšíření Translate obsahuje několik tříd, které během překladu dodávají pomocné informace. Každá z nich je samostatný modul třídy TranslationAid (třída co se stará o překladatelskou nápovědu), který má implementovanou metodu s názvem getData, vracející vyžádaná data ve strukturovaném formátu (vnořená pole). Moduly lze volat přímo z PHP kódu, nebo přes WebAPI.

Jak používat překladatelskou nápovědu v MediaWiki

Toto je jednoduchý příklad, jak lze získat dokumentaci ke zprávě, je-li dostupná.

$title = Title::newFromText( 'MediaWiki:Jan/de' );
$handle = new MessageHandle( $title );
$group = $handle->getGroup();
$context = RequestContext::newExtraneousContext( $title );

$aid = new DocumentationAid( $group, $handle, $context );

try {
	$data = $aid->getData();
	$docHtml = $aid['html'];
} catch ( TranslationHelperException $e ) {
	return;
}

echo $docHtml . "\n";

Jak volat překladatelskou nápovědu přes API

Jak bylo zmíněno výše, překladatelskou nápovědu lze volat rovněž přes webové API MediaWiki. Pro získání nápovědy, stačí udělat HTTP GET na URL http://translatewiki.net/w/api.php?action=translationaids&title=MediaWiki%3AJan%2Fde . V URL můžete upřesnit formát, ve kterém se má vrátit výsledek. Nejčastěji se využívá JSON a XML. Přístup přes API nevyžaduje autentizaci, ale některé části překladatelské nápovědy, jako je například "inotherlanguages", pracují s uživatelsky zvolenou preferencí jazyka. Chcete-li použít tuto nápovědu, pak se musíte nejdřív přihlásit do API, jak je popsáno v dokumentaci k WebAPI MediaWiki.

Data, která se vrátí mohou vypadat takto (formát json, upravený do čitelnější podoby):

{
	"helpers": {
		"definition": {
			"value": "Jan",
			"language": "en"
		},
		"translation": {
			"language": "de",
			"fuzzy": false,
			"value": "Jan."
		},
		"inotherlanguages": [
			
		],
		"documentation": {
			"language": "en",
			"value": "Abbreviation of January, the first month of the Gregorian calendar",
			"html": "<p>Abbreviation of January, the first month of the Gregorian calendar\n<\/p>"
		},
		"mt": [
			{
				"target": "Jan",
				"service": "Microsoft",
				"source_language": "en",
				"source": "Jan"
			},
			{
				"target": "Jan",
				"service": "Yandex",
				"source_language": "en",
				"source": "Jan"
			}
		],
		"definitiondiff": {
			"error": "No changes"
		},
		"ttmserver": [
			{
				"source": "Jan",
				"target": "Jan.",
				"context": "MediaWiki:Jan",
				"location": "MediaWiki:Jan\/de",
				"quality": 1,
				"wiki": "mediawiki-bw_",
				"service": "TTMServer",
				"source_language": "en",
				"local": true,
				"uri": "https:\/\/translatewiki.net\/wiki\/MediaWiki:Jan\/de"
			}
		],
		"support": {
			"url": "\/\/translatewiki.net\/w\/i.php?title=Support&lqt_method=talkpage_new_thread&lqt_subject_field=About+%5B%5BMediaWiki%3AJan%2Fde%5D%5D"
	}
}

Každý dotaz na překladatelskou nápovědu musí obsahovat klíč (bez něj se vrátí jen oznámení o chybě), to lze na straně PHP kódu ošetřit výjimkou. JavaScript to má ošetřeno tak, že používá jako výchozí hodnotou klíče používá řetězec "error". Ve výše uvedeném ukázkovém výpisu si tohoto indexu můžete povšimnout u pole definitiondiff, kde zpráva pod tímto klíčem oznamuje, že rozdílový soubor není k dispozici, protože v definici zprávy nenastaly od posledního překladu žádné změny.

Příklad použití v JavaScriptu

Následující kód dělá totéž, ale přes JavaScript. Není-li řečeno jinak, vrací API veškerý dostupný obsah překladatelské nápovědy. Parametrem prop si však můžeme vybrat jen tu, která nás zajímá. V následujícím příkladu se používá jsonp, abychom přes něj obešli omezení při přecházení mezi portály. Přes jsonp nelze zapisovat, takže pokud budete chtít pracovat s API přes JavaScript, musíte buď: Použít proxy; spouštět JavaScript skript na stejném hostiteli jako běží API; nebo použít mimo něj na straně cílové stránky pomocnou aplikaci, která však v tomto případě není implementovaná.

apiURL = 'https://translatewiki.net/w/api.php?callback=?';

queryParams = {
	action: 'translationaids',
	title: 'MediaWiki:Jan/de',
	format: 'json'
};

$.getJSON( apiURL, queryParams )
	.complete( function( data ) {
		console.log( data );
	} )
	.fail( function () {
		console.log( "Failed" );
	} );

Pravidla pojmenování a návratové hodnoty

Každá překladatelská nápověda používá svůj jedinečný identifikátor, kterým je alfanumerický řetězec. Ten nesmí obsahovat diakritiku, speciální znaky, ani znaky - a *.

Pole, které vrací každá ze tříd překladatelské nápovědy, zpracovává vývojář, mělo by však splňovat následující obecná doporučení.

Je-li návratovou hodnotou pouze jeden textový řetězec, můžete použít rovnou jako index řetězec value. Kód jazyka je pod indexem language. Na základě těchto údajů již lze zajistit, aby byl text řádně označkován, ve správném jazyce a také ve správném směru (informace o směrovosti textu je dána jazykem, proto není součástí návratové hodnoty). Obsahuje-li návratové pole také kód v HTML, bude dostupný pod indexem html. Může to být kupř. dokumentace k překládané zprávě, nebo kód s informací o rozdílech.

U navrhovaných překladů, ať už pochází ze strojového překladu nebo překladové paměti, lze použít tyto indexy:

source, source_language a target (kód jazyka do kterého se překládá v poli pod indexem language).
server: Identifikátor použité služby.
quality: Hodnota v rozmezí [0,1], vyšší hodnota znamená, že kvalita návrhů je velmi dobrá.

Je-li návratovou hodnotou pole, pak je pod indexem ** uloženo jméno příslušného prvku. U zpráv, které pochází ze strojového překladu, nebo překladové paměti je to suggestion. To je dáno API MediaWiki. Jméno prvku je jinak vidět pouze u výstupu v XML formátu. V JSON formátu se vypíše pouze seznam zpráv.

Seznam standardních modulů překladatelské nápovědy

[field] znamená, že návratovou hodnotou indexované buňky je pole. V PHP to je pole buněk s numerickými indexy a jedním řetězcovým indexem **; viz výše.

Třída	ID	Pole	Poznámka
MessageDefinitionAid	definition	language value
CurrentTranslationAid	translation	language value fuzzy - (boolean) Pokud překlad existuje, ale potřebuje revizi nebo aktualizaci.
InOtherLanguagesAid	inotherlanguages	[suggestion] language value	Závisí na uživatelském nastavení.
DocumentationAid	documentation	language value - Bez interpretace wiki značek html
MachineTranslationAid	mt	[suggestion] source source_language target service	Dostupnost závisí na podpoře párování překladů a dostupnosti externích služeb.
UpdatedDefinitionAid	definitiondiff	value_old value_new revisionid_old revisionid_new language html	Zobrazení závisí na mediawiki.action.history.diff MediaWiki modulu ResourceLoader.
TTMServerAid	ttmserver	[suggestion] source source_language target service quality local - (boolean) Zda mají být návrhy na překlad zprávy součástí dotazu ve wiki. uri - URL nebo jiný indikátor umístění zdroje.
SupportAid	support	url	Webová stránka, kde může uživatel nalézt s dalšími i informace k překládané zprávě.
InsertablesAid	insertables	[insertable] display pre post	Řetězec nepřeložitelného textu, který může být vložen do překladu. Pole říká co se zobrazí uživateli a co se vloží před a po jeho výběru.

<translate> Documentation for <tvar|ext>Rozšíření:Translate</></translate>

<translate> Translators</translate> (<translate> main help page</translate> )

<translate> Translation administrators</translate>

<translate> Sysadmins and developers</translate>

<translate> Translate this template</translate>