Help:Extension:Translate/Insertables/ha
Translators (main help page )
- How to translate
- Best practices
- Statistics and reporting
- Quality assurance
- Message group states
- Offline translation
- Glossary
Translation administrators
- How to prepare a page for translation
- Page translation administration
- Unstructured element translation
- Group management
- Move translatable page
- Import translations via CSV
- Working with message bundles
Sysadmins and developers
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 Insertable
s.
Each Insertable
has three parts:
- What to display to the user
- Abin da aka saka kafin matsayi na siginan kwamfuta a cikin fassarar ko abin da ke maye gurbin abin da aka zaɓa.
- 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 translatewiki.net git repository.
User interface
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 – Abin da za a saka kafin zaɓi, ko maye gurbin zaɓi idan
post
ya kasance fanko 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.
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.
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();
// 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 What to show to the user
* @param string $pre Abin da za a saka kafin zaɓi, ko maye gurbin zaɓi idan $post ya kasance fanko
* @param string $post What to insert after selection
*/
public function __construct( $display, $pre = '', $post = '' ) {
$this->display = $display;
$this->pre = $pre;
$this->post = $post;
}
[...]
}