Help:Extension:Translate/挿入要素
翻訳対象の文字列は、翻訳結果でもそのまま保持されるべきマークアップを含むことがよくあります。 マークアップは特殊な文字を多く含むため、タイプするのが低速・困難になる場合があります。 Insertable (インサータブル、挿入要素) は、マークアップの断片であり、翻訳者にはボタンやその他のインターフェイス要素として表示されます。 ボタンをクリックすることで、翻訳内の現在のカーソルの位置に、マークアップの断片が挿入されます。
各メッセージ群は1つの InsertablesSuggester
を保持できます。
このクラスは Insertable
の一覧の生成を担当します。
各 Insertable
は以下の3つの部分で構成されます:
- 利用者に表示するもの
- 翻訳内のカーソルの位置の前に何を挿入するか
- 翻訳内のカーソルの位置の後ろに何を挿入するか
Translate 拡張機能には組み込みの MediaWikiInsertablesSuggester
が同梱されています。
他の種類のコンテンツの Suggester は translatewiki.net の git リポジトリにあります。
ユーザーインターフェイス
Configuration
Here's a sample configuration change in a YAML file,
INSERTABLES:
# pre-bundled insertable
- class: RegexInsertablesSuggester
params: "/\$[a-zA-Z0-9]+/"
# custom insertable
- class: FreeColInsertablesSuggester
AUTOLOAD:
FreeColInsertablesSuggester: Suggester.php
Pre-provided / Bundled insertables
Following is a list of bundled insertables.
HtmlTagInsertablesSuggester
This insertable will display suggestion for any HTML tags found inside the source string.
For example:
- Message: This <a href="abc">link</a>link takes you to the home page.
- Suggester displayed:
<a href="abc"></a>
MediaWikiInsertablesSuggester
This insertable will display various suggestion for MediaWiki related wikitext messages. These include suggestion for,
- Parameters like
$1user
which are present in API Help messages.
PLURALS
,GENDER
,GRAMMAR
- Suggestions for HTML tags.
NumericalParameterInsertablesSuggester
This insertable will display suggestions for numerical parameters such as $1
, $2
, $33
RegexInsertablesSuggester
This insertable is a general purpose insertable that can be used to display suggestions based on a custom regular expression.
Example:
# simple example
# matches and suggests: $abc
- class: RegexInsertablesSuggester
params: "/\$[a-zA-Z0-9]+/"
# complex example using named captures.
# matches: [abc](ac)
# suggester displayed: [](ac)
- class: RegexInsertablesSuggester
params:
regex: /(?<pre>\[)[^]]+(?<post>\]\([^)]+\))/
display: $pre $post
pre: $pre
post: $post
Parameter description,
- regex – The regex to use for identifying insertables. Mandatory.
- display – What to show to the user. Not mandatory, defaults to matched value.
- pre – What to insert before selection, or replace selection if
post
remains empty Not mandatory, defaults to matched value. - post – What to insert after selection. Not mandatory, defaults to matched value.
TranslatablePageInsertablesSuggester
Used primarily on translatable pages to provide suggester for variables like $abc
.
UrlInsertablesSuggester
This insertable finds URLs (that are normally unchanged in translations) and suggests them for insertion.
Adding a custom insertable
In case existing insertables are not sufficient to meet your requirements, it is possible to add custom insertables.
既存のファイル ベースのメッセージ群である「FreeCol」に Insertable 対応を追加する例を示します。 YAML ファイルは簡潔にするため一部省略されています。 新たに追加された行が強調されています。
FreeCol.yaml:
---
BASIC:
id: out-freecol
label: FreeCol
description: "A strategy game"
namespace: NS_FREECOL
class: FileBasedMessageGroup
FILES:
class: JavaFFS
sourcePattern: %GROUPROOT%/freecol/data/strings/FreeColMessages_%CODE%.properties
definitionFile: %GROUPROOT%/freecol/data/strings/FreeColMessages.properties
targetPattern: freecol/data/strings/FreeColMessages_%CODE%.properties
INSERTABLES:
- class: FreeColInsertablesSuggester
AUTOLOAD:
FreeColInsertablesSuggester: Suggester.php
Suggester.php:
class FreecolInsertablesSuggester {
public function getInsertables( $text ) {
$insertables = array();
$matches = array();
// %name% の形式の変数を見つける。
// これは Checker.php での正規表現と同一。
preg_match_all( '/%[a-zA-Z_]+%/', $text, $matches, PREG_SET_ORDER );
$new = array_map( function( $match ) {
// $match[0] は完全一致であり、部分一致は一切使用しない。
// 挿入した位置の末尾にカーソルを設定したいため、"pre" フィールドに文字列全体を設定する。
return new Insertable( $match[0], $match[0] );
}, $matches );
return $insertables;
}
}
Insertable のパラメーターは以下の通りです:
class Insertable {
/**
* @param string $display 利用者に表示するもの
* @param string $pre 選択の前に挿入するもの
* @param string $post 選択の後ろに挿入するもの
*/
public function __construct( $display, $pre = '', $post = '' ) {
$this->display = $display;
$this->pre = $pre;
$this->post = $post;
}
[...]
}