Jump to navigation Jump to search
This page is a translated version of the page Help:Extension:Translate/Insertables and the translation is 2% complete.
Other languages:
Deutsch • ‎English • ‎français • ‎čeština • ‎русский • ‎中文 • ‎日本語

Translatable strings often contain markup that should be retained as-is in the translation. Typing that markup can be slow and difficult because special characters are common. Insertable is a piece of markup that is presented to the translator as a button or other interface element. Clicking the button inserts the piece of markup into the translation to the current cursor position.

Each message group can have one InsertablesSuggester. This class is responsible for generating a list of Insertables. Each Insertable has three parts:

# What to display to the user # What is inserted before cursor position in the translation # What is inserted after cursor position in the translation

Translate extension comes with MediaWikiInsertablesSuggester built-in. Suggesters for other type of content can be found in the git repository.

Uživatelské rozhraní

Insertables show in the bottom of the translation text area. They provide quick access for inserting pieces of mark-up that does not vary per language.


Here's a sample configuration change in a YAML file,

2   # pre-bundled insertable
3   - class: RegexInsertablesSuggester
4     params: "/\$[a-zA-Z0-9]+/"
5   # custom insertable
6   - class: FreeColInsertablesSuggester
9   FreeColInsertablesSuggester: Suggester.php

Pre-provided / Bundled insertables

Following is a list of bundled insertables.


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>


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.
  • Suggestions for HTML tags.


This insertable will display suggestions for numerical parameters such as $1, $2, or $33


This insertable is a general purpose insertable that can be used to display suggestions based on a custom regular expression.


 1   # simple example
 2   # matches and suggests: $abc
 3   - class: RegexInsertablesSuggester
 4     params: "/\$[a-zA-Z0-9]+/"
 5   # complex example using named captures.
 6   # matches: [abc](ac) 
 7   # suggester displayed: [](ac)
 8   - class: RegexInsertablesSuggester
 9     params:
10       regex: /(?<pre>\[)[^]]+(?<post>\]\([^)]+\))/
11       display: $pre $post
12       pre: $pre
13       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. Not mandatory, defaults to matched value.
  • post - What to insert after selection. Not mandatory, defaults to matched value.


Used primarily on translatable pages to provide suggester for variables like $abc.

Adding a custom insertable

In case existing insertables are not sufficient to meet your requirements, it is possible to add custom insertables.

Here is an example about adding insertables support for existing file based message group: FreeCol. The YAML file has been trimmed for brevity. The newly added lines are highlighted.


  id: out-freecol
  label: FreeCol
  description: "A strategy game"
  namespace: NS_FREECOL
  class: FileBasedMessageGroup
  class: JavaFFS
  sourcePattern: %GROUPROOT%/freecol/data/strings/
  definitionFile: %GROUPROOT%/freecol/data/strings/
  targetPattern: freecol/data/strings/

  - class: FreeColInsertablesSuggester

  FreeColInsertablesSuggester: Suggester.php


class FreecolInsertablesSuggester {
	public function getInsertables( $text ) {
		$insertables = array();

		$matches = array();
		// Find variables of format %name%
		// This is the same regular expression as in Checker.php
		preg_match_all( '/%[a-zA-Z_]+%/', $text, $matches, PREG_SET_ORDER );
		$new = array_map( function( $match ) {
			// $match[0] is full match, and we don't have any submatches here
			// Since we want the cursor to be at the end of the insertion, we put the whole thing into the "pre" field.
			return new Insertable( $match[0], $match[0] );
		}, $matches );

		return $insertables;

The parameters to Insertable are:

class Insertable {
         * @param string $display <span lang="en" dir="ltr" class="mw-content-ltr">What to show to the user</span>
         * @param string $pre <span lang="en" dir="ltr" class="mw-content-ltr">What to insert before selection</span>
         * @param string $post <span lang="en" dir="ltr" class="mw-content-ltr">What to insert after selection</span>
        public function __construct( $display, $pre = '', $post = '' ) {
                $this->display = $display;
                $this->pre = $pre;
                $this->post = $post;