Help:Extension:Translate/挿入要素

This page is a translated version of the page Help:Extension:Translate/Insertables and the translation is 40% complete.

Outdated translations are marked like this.

翻訳対象の文字列は、翻訳結果でもそのまま保持されるべきマークアップを含むことがよくあります。マークアップは特殊な文字を多く含むため、タイプするのが低速・困難になる場合があります。 Insertable (インサータブル、挿入要素) は、マークアップの断片であり、翻訳者にはボタンやその他のインターフェイス要素として表示されます。ボタンをクリックすることで、翻訳内の現在のカーソルの位置に、マークアップの断片が挿入されます。

各メッセージ群は1つの InsertablesSuggester を保持できます。このクラスは Insertable の一覧の生成を担当します。各 Insertable は以下の3つの部分で構成されます:

利用者に表示するもの

翻訳内のカーソルの位置の前に何を挿入するか

翻訳内のカーソルの位置の後ろに何を挿入するか

Translate 拡張機能には組み込みの MediaWikiInsertablesSuggester が同梱されています。他の種類のコンテンツの Suggester は translatewiki.net の git リポジトリにあります。

ユーザーインターフェイス

Insertable は翻訳のテキストエリアの下部に表示されます。これにより、どの言語でも不変のマークアップの断片を容易に挿入できるようになります。

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, or $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;
        }
[...]
}