Help:Extension:Translate/Translation aids/nl

From Linux Web Expert

Vertaalhulpmiddelen zijn modules die bruikbare en nodige informatie geven aan een vertaler bij het vertalen. Verschillende hulpmiddelen kunnen suggesties geven uit het vertaalgeheugen, machine vertaling, documentatie over het bericht of zelfs uit zoiets eenvoudigs als de definitie van het bericht, de tekst die vertaald moet worden.

Er is wat overlap tussen de gegevens die berichtengroep en de hulpmiddelen aanleveren, maar de regel is dat de berichtengroep alleen de informatie geeft om aan te geven in de lijst met welke berichten vertaald moeten worden: definitie, status van de vertaling, laatste vertaler (men kan alleen vertalingen beoordelen als men die niet zelf heeft vertaald) enz.

De extensie Translate heeft veel classes om het vertalen te ondersteunen. Elke class die de class TranslationAid uitbreidt hoef alleen een methode getData te maken. Die moet dan de gegevens in een genest array gestructureerd teruggeven. Deze modules kunnen direct via PHP worden aangeroepen of via de WebAPI.

Hoe vertaalhulpmiddelen te gebruiken

Een voorbeeld om de documentatie van een bericht op te halen, indien beschikbaar.

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

Hoe de vertaal API te gebruiken

Zoals hierboven al genoemd, vertaalhulpmiddelen zijn beschikbaar via een WebAPI, die het MediaWiki WebAPI framework gebruikt. Met een simpele HTTP GET met de URL http://translatewiki.net/w/api.php?action=translationaids&title=MediaWiki%3AJan%2Fde . Er zijn verschillende formaten mogelijk, maar JSON en XML zijn de populairste. Bij deze API is er geen authenticatie, maar andere hulpmiddelen als "inotherlanguages" gebruiken de gebruikersvoorkeur om te bepalen welke talen er gebruikt moeten worden. Dan is het wel nodig om eerst in te loggen, zoals aangegeven in de MediaWiki WebAPI documentatie.

Het antwoord ziet er ongeveer als volg uit (dit is in json formaat):

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

Elk verzocht hulpmiddel heeft hier een key (als het verzoek niet stukloopt), maar met exceptions aan de PHP-kant, aan de JavaScript kant kan elk hulpmiddel een "error" gezet hebben met een fouttekst als waarde. Hierboven staat een voorbeeld met de definitiondiff. Het geeft aan dat het het verschil niet kan weergeven, de definitie is na de laatste vertaling niet gewijzigd (dat zal hopelijk de normale situatie zijn).

JavaScript voorbeeld

Dit speelt ook bij JavaScript. Standaard geeft de API alle hulpmiddelen, maar u kunt aangeven welke u wilt hebben met de parameter prop. In het voorbeeld gebruiken we jsonp om langs de beperking cross-site te werken. In jsonp kunnen geen schrijfacties worden gedaan, dus bij gebruik van deze API in JavaScript dient u te hebben: een proxy (voor het uitvoeren van het script op dezelfde host) of een 'helper' (nog niet geïmplementeerd) van de doel website.

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

Naamconventies en returnwaarden

Elk vertaalhulpmiddel heeft een identifier, hierin zouden geen speciale tekens moeten voorkomen. Speciale tekens zijn ook de - en de *.

Het array dat elke vertaling wordt teruggegeven wordt door de ontwikkelaar bepaald, maar wij geven de volgende algemene aanbevelingen.

Als er maar een tekstwaarde wordt teruggegeven, dan moet het de value als de key van het veld gebruiken. Taal moet in de code language worden aangegeven. Gebruikers van deze gegevens moeten er zeker van zijn dat in HTML en elders de tekst goed getagd is met de aangegeven taal en taalrichting (hier niet gebruikt). Als er HTML-uitvoer is, dan moet het beschikbaar zijn me de key html. Voorbeelden hiervan zijn de berichtendocumentatie en de 'diffs'.

Meerdere soorten van suggesties zoals machinevertaling en vertaalgeheugen dienen deze keys te gebruiken waar dan zinnig is:

  • source, source_language en target (target taal is impliciet hetzelfde als de taal van de vertaling)
  • server: geeft de gebruikte service aan
  • quality: waarde in bereik [0,1], hoe hoger hoe beter de kwaliteit van de vertaling.
Bij de teruggegeven arrays, dient het veld ** een elementnaam bevatten. Bij machinevertaling en vertaalgeheugen is dat suggestion. Dit wordt voorgeschreven door het MediaWiki WebAPI framework. Het wordt getoond in het XML-formaat, in JSON-formaat is de uitvoer gewoon een lijst.

Lijst van standaard hulpmiddelen

[field] Geeft aan dat het geretourneerde een lijst is. In PHP termen een array met numerieke indexen en een met de **; zie hierboven.

Class ID Velden Opmerkingen
MessageDefinitionAid definition
  • language
  • value
CurrentTranslationAid translation
  • language
  • value
  • fuzzy - (boolean) Als er een vertaling is, maar die moet beoordeeld of aangepast worden.
InOtherLanguagesAid inotherlanguages
  • [suggestion]
    • language
    • value
Hangt af van de gebruikersvoorkeur
DocumentationAid documentation
  • language
  • value - Niet verwerkte opmaak
  • html
MachineTranslationAid mt
  • [suggestion]
    • source
    • source_language
    • target
    • service
Beschikbaarheid hangt af van de ondersteuning van het taalpaar en beschikbaarheid van externe services.
UpdatedDefinitionAid definitiondiff
  • value_old
  • value_new
  • revisionid_old
  • revisionid_new
  • language
  • html
Wat er getoond wordt hangt af van de mediawiki.action.history.diff Resource Loader Module van MediaWiki.
TTMServerAid ttmserver
  • [suggestion]
    • source
    • source_language
    • target
    • service
    • quality
    • local - (boolean) Of de suggestie een bericht is in de benaderde wiki.
    • uri - URL of een andere bronlocatie indicatie.
SupportAid support
  • url
Dit is een webpagina waar de gebruiker naar verwezen kan worden om vragen te stellen over het te vertalen bericht.
InsertablesAid insertables
  • [insertable]
    • display
    • pre
    • post
Teksten van niet te vertalen tekst die toegevoegd kan worden in de vertaling. Velden die aangeven wat er aan de gebruiker getoond wordt en wat er voor en na de selectie wordt toegevoegd.