Help:Extension:Translate/翻訳支援

翻訳支援 (あるいは翻訳ヘルパーとも) は翻訳中に役立つ必要な情報を翻訳者に提供する、モジュール群のことを指します。翻訳支援には種類があり、翻訳メモリや機械翻訳の訳文、メッセージに関する説明文書、あるいはメッセージの定義 – 翻訳の必要がある文までお勧めします。

message collectionと翻訳支援が提供するデータには重複が見られますが、基本的にメッセージ収集機能にはメッセージの一覧を抽出するために欠かせない情報しか提供できません。それらはつまり定義、翻訳、翻訳状況、直前の翻訳者 (査読できるのは自分以外の人の訳文に限定されるため) 等に相当します。

翻訳にはたくさんの支援クラスが伴います。翻訳支援機能クラスを拡張するどのクラスも、唯一、getDataと呼ばれる方式を実装するだけで処理します。返す情報は構造化 (入れ子状の列) されます。これらのモジュールはPHPから直接呼び出すか、WebAPIを介することもできます。

MediaWiki 内での翻訳支援の使用方法

メッセージの説明文書を利用できる場合にそれを取得する、単純な例です。

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

翻訳支援 API の使用方法

上記の例で見たとおり、翻訳支援はWebAPIを介して利用でき、その場合、MediaWiki WebAPIのフレームワークを使用します。翻訳支援の利用手順は簡単で、URL http://translatewiki.net/w/api.php?action=translationaids&title=MediaWiki%3AJan%2Fde の入手にHTTP GETを当てるのと同様です。書式は何種類かありますが、JSON及びXMLが最も一般的に利用されています。このAPIには認証は不要ですが、翻訳支援によっては、「inotherlanguages」のように使用言語の判定に利用者の個人設定を使用します。左記の翻訳支援は、MediaWiki WebAPIの説明文書に書いてあるとおり、ログインしてから使います。

以下のようなデータが返ってくるはずです (読みやすく整形した 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"
	}
}

どの翻訳支援機能を呼び出すにも、ここにキーが必ずありますが (呼び出しが残念ながら失敗した場合を除く)、PHP側で例外を使えても、JavaScript側ではどの支援機能にもキー「エラー」とそれに伴う値としてエラーメッセージが設定してある場合が考えられます。上記でdefinitiondiffを使うと、例を見ることができます。直前の翻訳に対して何も変更が加わっていないため、差分の表示は不可能と返してきます。

JavaScript の例

JavaScriptの例を示します。既定ではAPIはすべての翻訳支援を返しますが、prop引数を用いると返すものを特定します。例ではjsonpを用いて、サイト横断の制限を回避しました。ただし要注意点は、jsonpを利用するとホワイトアクションは不可のため、JavaScriptでこのAPIを使用する時のコツは以下のとおりです。proxyを利用するか、同じホスト上でスクリプトを走らせるか、別途、軽いヘルパー (未実装) を対象サイトから読み込みます。

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

命名規則と戻り値

各翻訳支援には唯一の識別子文字列があります。識別子では特殊文字、特に JavaScript の識別子として有効ではない文字 (-、* など) を避けるべきです。

各翻訳支援が戻す配列は開発者ごとに異なるものの、一般的な推奨事項は守らなければなりません。

もし値として文字列を返す場合、フィールドのキーとしてvalueが必須です。languageフィールドには言語が必須です。このデータの利用者はHTMLでもどこでも、文字列に指定された言語と書記方向 (このページでは未提供) を漏れなくタグ付けする必要があります。HTML出力が提供できる場合は、キーhtmlを付与して提示します。例えば、メッセージの説明文書や差分がこれに該当します。

訳文のお勧めは、例えば機械翻訳や翻訳メモリからの出力には、適する場合は次のキーを使用します。

• source, source_language and target (target language is implicitly the same as the language of the translation)
• server: 使用するサービスの識別子
• quality: [0,1]値を用い、値が大きいほど指示された例が適合している。

注記: 配列を返すとき、**フィールドに必ず要素名を入力し、機械翻訳および翻訳メモリに対してはsuggestionと記入します。これはMediaWiki WebAPIフレームワークが義務づける条件です。表示はXML形式ですが、JSON形式では単なるリストしか出力しません。

標準の支援の一覧

[フィールド名] は、戻り値がリストであることを意味しています。PHP では、添字が整数の配列にキー ** が追加されたものです。これが必要な理由は前述の通りです。

クラス	ID	フィールド	注記
MessageDefinitionAid	definition	language value
CurrentTranslationAid	translation	language value fuzzy - (真偽値) 翻訳が存在するものの、査読または更新が必要な場合は true。
InOtherLanguagesAid	inotherlanguages	[suggestion] language value	利用者の個人設定に依存
DocumentationAid	documentation	language value - 構文解析前のウィキ マークアップ html
MachineTranslationAid	mt	[suggestion] source source_language target service	利用できるかどうかは、言語の対に対応しているかどうか、および外部サービスを利用できるかどうか、に依存します。
UpdatedDefinitionAid	definitiondiff	value_old value_new revisionid_old revisionid_new language html	表示は、MediaWiki の mediawiki.action.history.diff リソース ローダー モジュールに依存します。
TTMServerAid	ttmserver	[suggestion] source source_language target service quality local - * server: 使用するサービスの識別子 uri - URL または他のリソースの場所を示す識別子
SupportAid	support	url	これは、このメッセージについて利用者が質問を投稿できるウェブページです。
InsertablesAid	insertables	[insertable] display pre post	翻訳不可能な文字列を翻訳内に挿入することができます。フィールドは利用者に表示する内容、選択の前後それぞれに挿入する内容を示します。

Extension-Translate
Extension:Translate の説明文書 翻訳者 (メインヘルプページ ) 翻訳方法 最善手法 統計と報告 品質の保証 メッセージ群の状態 オフライン翻訳 用語集 翻訳管理者 翻訳するページの準備方法 ページ翻訳の管理 構造化されていない要素の翻訳 群の管理 システム管理者と開発者 インストール 設定の構成 翻訳の拡張 ファイル形式対応 (FFS) 挿入要素 このテンプレートを翻訳