Help:Extension:Translate/Group configuration

From mediawiki.org

There are many ways of adding message groups to Translate extension. Message groups are collection of messages. Usually they compare to one module in a software and one file (and usually one per language for translations). It is also possible to make groups that include messages from other message groups. For example there can be group that includes all messages in a given software. Groups can also include just subsets of messages, like the most important messages of MediaWiki that should be translated first. These higher level groups do not map directly to files in any particular format, but like all groups they can be exported in Gettext format for use in other translation tools.

Message groups are the high level blocks that translators interact with: to choose a message to work on they first need to select a group, unless they are using translation search. For each group we can gather statistics and each group has a unique identifier. Naturally, messages are the smallest blocks of text that translators translate one at a time. Each message also has an identifier, which is usually called a key. The key doesn't need to be unique across message groups.

Standard group configuration format[edit]

It is easy to add message groups using the YAML format. All you need to do is to define a namespace and add a configuration file to $wgTranslateGroupFiles; see the configuration page for more details. Example:

wfAddNamespace( 1218, 'FUDforum' );
$wgTranslateGroupFiles[] = "$IP/messagegroups/FUDforum/FUDforum.yml";

The file itself uses the YAML syntax. The syntax itself is not described here, but it is easy to learn, and all the premade groups can be used as examples. Remember to use spaces instead of tabs for indentation. Each file can define multiple message groups. Each group definition is separated by a line with three dashes, which is the standard document separator in YAML.

Definitions are broken into few top-level items: BASIC, FILES, MANGLER, VALIDATORS, INSERTABLES, TAGS, AUTOLOAD, LANGUAGES and special TEMPLATE. Some custom groups may add more top-level items. Not all groups need to define all of them.

BASIC[edit]

This section contains basic information about the group, like unique id and name. List of possible keys (mandatory keys are marked with *):

Key Description
namespace* Either namespace id, constant or string where the messages are stored. The namespace must be added beforehand. See the example above.
icon Icon for the message group. Can support any file that MediaWiki can handle and that is uploaded to MediaWiki. Also supports files from shared media repositories.
id* Unique id that identifies this message group.
label* Human readable name of this message group.
description Description of this message group. Full wiki syntax is used.
class* The type of this message group - usually FileBasedMessageGroup or AggregateMessageGroup.
meta Multiple uses. If there are identical message keys for different message groups (usually in the case of branch or subset message groups), only one group can be primary and the other groups should have meta with value of yes.
sourcelanguage Language code of the source language. Defaults to en (English).
codeBrowser Only used in GettextFFS. URL pattern of an online viewer for the repository file(s), where %FILE% and %LINE% will be replaced by the relevant file path and line – as stated in PO files comments for a message – to give translators an informative link within the translation aids for that message. Example: https://github.com/lonvia/waymarked-trails-site/blob/master/django/%FILE%#L%LINE%
support Configures where the "Ask help" button will redirect the translator. You must specify either url or page and optionally params to configure the URL parameters. In parameters you can use %MESSAGE% as a placeholder for the name of the message.

Example:

BASIC:
  id: out-freecol
  label: FreeCol
  icon: wiki://Freecol.png
  description: "{{int:bw-desc-freecol}}"
  namespace: NS_FREECOL
  class: FileBasedMessageGroup
  support:
    url: 
    params:
      title: "Translation issue with message %MESSAGE%"
      body: "[**URL**](https://translatewiki.net/wiki/%MESSAGE%)"

FILES[edit]

This section describes the filesystem layout and format of message files for groups of type FileBasedMessageGroup. List of possible keys (mandatory keys are marked with *):

Key Description
class* Class which defines the format of message files. Examples: YamlFFS, JavaFFS, FlatPhpFFS, ....
codeMap List of language codes that differ from the ones used in MediaWiki. Use the MediaWiki language code as key and the target language code as the value.
sourcePattern* Where to find message files. Path variables are supported.
targetPattern How the exported files are named relative to export directory. Path variables are supported.
definitionFile Use this to define the location of the definition file (with the English source messages) if it does not adhere to the sourcePattern. Path variables are supported.
AppleFFS, AppleInfoPlistFfs
header Custom file header comment.
FlatPhpFFS Class specific keys
header Custom file header. If not given, it defaults to <?php
GettextFFS Class specific keys
CtxtAsKey Special mode where ctxt is used as message key. Should not be used for normal Gettext files.
header Custom file header comment.
keyAlgorithm Allowed values: legacy and simple. Default: simple. Simple provides shorter message keys.
JavaFFS Class specific keys
header Custom file header comment.
keySeparator The character separating key and value. Default is =. Can also be :.
JsonFFS Class specific keys
nestingSeparator The character separating levels when nested objects are flattened intro one key string. By default flattening is not done. Example: { "top": { "nested": "content" } } is converted to (assuming / as separator) message with key top/nested and value content.
includeMetadata Whether to include the @metadata key with author information in the exported files. Defaults to true.
parseCLDRPlurals Whether to parse CLDR plural keywords. Defaults to false.
YamlFFS Class specific keys
codeAsRoot If set to 1, all messages are under a language code (instead of at the root).
nestingSeparator The character separating levels when nested objects are flattened intro one key string. Default value is .. Example: top: { nested: content } is converted to (assuming . as separator) message with key top.nested and value content.
parseCLDRPlurals Whether to parse CLDR plural keywords. Defaults to false.

The path variables are:

Variable Description
%CODE% Language code (affected by codeMap)
%MWROOT% Path to MediaWiki installation
%GROUPROOT% Defined by $wgTranslateGroupRoot.
%GROUPID% Message group id

Example:

FILES:
  class: JavaFFS
  sourcePattern: %GROUPROOT%/commonist/messages_%CODE%.properties
  targetPattern: commonist/messages_%CODE%.properties

MANGLER[edit]

Mangler is a way to mungle message keys to avoid conflicting message keys in multiple groups:

Key Description
class* Which type of mangler to use. Example: StringMatcher
StringMatcher Class specific keys
patterns* List of patterns. "*" can be used as a wildcard.
prefix* If the above patterns match a message, the message key will be prefixed with this prefix.

Example:

MANGLER:
  class: StringMatcher
  patterns:
    - "*"

VALIDATORS[edit]

This section allows to define pre-defined or custom validators.

VALIDATORS:
  # pre-defined validator
  - id: InsertableRegex
    enforce: true
    insertable: true
    params: /\$[a-z0-9]+/
  # custom validator
  - class: MyCustomValidator
    enforce: true

AUTOLOAD:
  MyCustomValidator: Validator.php

INSERTABLES[edit]

This section allows to define a class which suggests insertables or use pre-defined insertables. The classes can be autoloaded as described in the AUTOLOAD section.

INSERTABLES:
  # pre-defined insertable
  - class: HtmlTagInsertablesSuggester
  # custom insertable
  - class: FreeColInsertablesSuggester

AUTOLOAD:
  FreeColInsertablesSuggester: Insertable.php

TAGS[edit]

It is possible to assign tags to messages. Each tag takes list of message keys (after mangling). "*" can be used as wildcard. The following tags are supported:

Key Description
optional These messages are not shown by default, and they do not count as untranslated messages when calculating translation percentages.
ignored These messages are not shown at all.

Example:

TAGS:
  optional:
    - lang_locale
    - lang_dir
  ignored:
    - charset

AUTOLOAD[edit]

This item takes list of class names with filenames as values. This way custom classes can be bundled easily with your custom message groups. The path should be relative to the location of the group configuration file itself.

Example:

AUTOLOAD:
  ShapadoMessageChecker: Checker.php

TEMPLATE[edit]

There is a handy shortcut if you are defining multiple similar message groups. To avoid repetition, have the first definition start with this key. You can use any other top-level keys as subkeys for this item. All other groups will use these definitions as default values. Each group can of course override the default value from the template.

Example:

TEMPLATE:
  BASIC:
    namespace: NS_SHAPADO
    class: FileBasedMessageGroup
    description: "{{int:bw-desc-shapado}}"

  FILES:
    class: YamlFFS
    codeAsRoot: 1
    codeMap:
      be-tarask: be-TARASK

GROUPS (for AggregateMessageGroup class)[edit]

This key only takes list of group ids this message group consists of.

Example:

GROUPS:
  - out-shapado-ads
  - out-shapado-announcements
  - out-shapado-answers
  - out-shapado-badges

Wildcards are supported. In this case the aggregate group will not recursively include itself even if it matches a pattern. Example:

GROUPS:
  - out-shapado-*

Wildcards can be problematic if you have nested aggregate groups, because some groups can be included multiple times: both directly and via the included aggregate groups.

LANGUAGES[edit]

This key makes it possible to allow and disallow translation into specific languages for the group. Translation into disallowed languages will be blocked.

LANGUAGES:
  include:
    - en
  exclude:
    - he
    - or
Warning Warning: MLEB 2021.10: Below configuration no longer supported
LANGUAGES:
  whitelist:
    - en
  blacklist:
    - he
    - or

Allowed ("include") entries override any values in the disallowed ("exclude") list. If an allowed entry is * that means all languages are allowed. The allowed list is also optional.

Message groups for interface messages specific to your wiki[edit]

Example of message group for custom user interface of the wiki, for example for localized sidebar. Add the following code into your LocalSetting.php and replace wikiname with something meaningful.

$wgHooks['TranslatePostInitGroups'][] = function ( &$list, &$deps, &$autoload ) {
	$id = 'wiki-custom';
	$mg = new WikiMessageGroup( $id, 'wikiname-messages' );
	$mg->setLabel( 'Wikiname User Interface Messages' );
	$mg->setDescription( 'This group contains user interface messages used on Wikiname.' );
	$list[$id] = $mg;
}

Shortcut for MediaWiki extensions[edit]

See units group for MediaWiki.