Help:Extension:Translate/Insertables

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  . This class is responsible for generating a list of s.  Each   has three parts:


 * 1) What to display to the user
 * 2) What is inserted before cursor position in the translation
 * 3) What is inserted after cursor position in the translation

Translate extension comes with   built-in. Suggesters for other type of content can be found in the [https://phabricator.wikimedia.org/diffusion/GTWN/browse/groups translatewiki.net git repository].

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

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 linklink takes you to the home page.
 * Suggester displayed:

MediaWikiInsertablesSuggester
This insertable will display various suggestion for MediaWiki related wikitext messages. These include suggestion for,


 * Parameters like   which are present in API Help messages.


 * Suggestions for HTML tags.

NumericalParameterInsertablesSuggester
This insertable will display suggestions for numerical parameters such as,  , or

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

Example:

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.

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

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 help>Special:MyLanguage/Help:Extension:Translate/Group configuration example|trimmed for brevity. The newly added lines are highlighted.

FreeCol.yaml:

Suggester.php:

The parameters to Insertable are: