Help:Extension:Translate/Group configuration

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.

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.

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

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%)"

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 *):

The path variables are:

Example:

FILES:
  format: Java
  sourcePattern: %GROUPROOT%/commonist/messages_%CODE%.properties
  targetPattern: commonist/messages_%CODE%.properties

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

Example:

MANGLER:
  class: StringMatcher
  patterns:
    - "*"

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

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

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:

Example:

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

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

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:
    format: Yaml
    codeAsRoot: 1
    codeMap:
      be-tarask: be-TARASK

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.

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:

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.

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;
};

See units group for MediaWiki.