Help:Extensão:Translate/Auxiliares de tradução

From mediawiki.org
This page is a translated version of the page Help:Extension:Translate/Translation aids and the translation is 47% complete.

Auxiliares de tradução (ou ajudantes de tradução) são módulos que fornecem informações úteis e necessárias para o tradutor ao efetuar uma tradução. Diferentes auxiliares podem fornecer sugestões de memória de tradução e tradução automática, documentação sobre a mensagem ou até mesmo uma coisa tão básica como a definição da mensagem - o texto que precisa ser traduzido.

Há alguma sobreposição entre os dados fornecidos pela coleção de mensagens bem como os auxiliares, mas a regra geral é que a coleção de mensagem só fornece informações que são absolutamente necessárias para apresentar a lista de mensagens: definição, tradução, estado de tradução, último tradutor (porque é possível apenas revisar traduções feitas por outra pessoa), etc .

A extensão Translate vem com muitas classes de auxiliares. Cada classe que estende a classe TranslationAid só precisa implementar um método chamado getData. Ele deve retornar as informações em formato estruturado (arrays aninhados). Estes módulos podem ser chamados diretamente do PHP ou através do WebAPI.

Como usar auxiliares de tradução dentro do MediaWiki

Exemplo simples para obter a documentação de uma mensagem, se disponível.

$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";

Como usar a API dos auxiliares de tradução

As already seen above, translation aids are available via a WebAPI, which is using the MediaWiki WebAPI framework. Getting translation aids is as simple as doing HTTP GET for the URL http://translatewiki.net/w/api.php?action=translationaids&title=MediaWiki%3AJan%2Fde . It provides various different formats, but JSON and XML are the most popular ones. This API does not need authentication, but some translation aids like "inotherlanguages" uses user preferences to determine which languages to use. To use that aid you should log in first, as described in the MediaWiki WebAPI documentation.

Os dados retornados deve ser semelhante a este (mostrado no formato bastante JSON) :

{
	"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"
	}
}

Every requested aid is guaranteed to have a key here (until the request fails miserably), but while we use exceptions in the PHP side, in the JavaScript side each aid may have the key "error" set with the error message set as value. You can see an example of this above with definitiondiff. It signals that it cannot display a diff, because there have been no changes to the definition since last translation.

Exemplo de JavaScript

Here is the same thing for JavaScript. By default the API returns all aids, but you can request specific ones with the prop param. In the example we are using jsonp to work around cross site request limitations. Be aware that you cannot execute any write actions with jsonp, so if you are using this API from JavaScript you will need: to have a proxy; to run the script on the same host; or to load a little helper (not yet implemented) from the target site.

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" );
	} );

Naming conventions and return values

Each translation aid has a unique string identifier. Identifiers should avoid special characters, especially those which are not valid in JavaScript identifiers, like - and *.

The array that is returned by each translation aid is up to the developer, but should follow some general recommendations.

If only one text value is returned, it should use value as the key of the field. Language should be provided in field language. Users of this data should ensure that in HTML and elsewhere the text is tagged properly with the provided language and directionality (not provided here). If there is HTML output, it should be available with key html. Examples of this are message documentation and diffs.

Various kinds of translation suggestions like machine translation and translation memories should use these keys when they make sense:

  • source, source_language and target (target language is implicitly the same as the language of the translation)
  • server: identifier of the service used
  • quality: value in range [0,1], higher value means that the quality of the suggestions is very good.
Ao retornar matrizes, você deve definir o ** campo para conter um nome de elemento. Para tradução automática e memória de tradução, isso é suggestion. Isso é obrigatório pela estrutura do MediaWiki WebAPI. É visível no formato XML, mas no formato JSON a saída é apenas uma lista.

Lista de ajudas padrão

[field] Means that the return value is a list. In PHP that means array with numerical indexes + one with key **; see above why this is needed.

Classe Id Campos Notas
MessageDefinitionAid definition
  • language
  • value
CurrentTranslationAid translation
  • language
  • value
  • fuzzy - (booleano) Se a tradução existe mas necessita de revisão ou atualização.
InOtherLanguagesAid inotherlanguages
  • [suggestion]
    • language
    • value
Depende da preferência do usuário
DocumentationAid documentation
  • language
  • value - Unparsed wiki markup
  • html
MachineTranslationAid mt
  • [suggestion]
    • source
    • source_language
    • target
    • service
Availability depends on language pair support and availability of external services.
UpdatedDefinitionAid definitiondiff
  • value_old
  • value_new
  • revisionid_old
  • revisionid_new
  • language
  • html
Display depends on mediawiki.action.history.diff Resource Loader Module of MediaWiki.
TTMServerAid ttmserver
  • [suggestion]
    • source
    • source_language
    • target
    • service
    • quality
    • local - (boolean) Whether the suggestion is a message in the wiki queried.
    • uri - URL or other resource location indicator.
SupportAid support
  • url
This is a web page where user can be directed to post questions about this message.
InsertablesAid insertables
  • [insertable]
    • display
    • pre
    • post
Strings of untranslatable text that can be inserted into the translation. Fields tell what to display to the user and what is inserted before and after selection.