Help:Extension:Translate/Group configuration

Translate this page

Documentation for Extension:Translate

Translators (main help page )

Translation administrators

Sysadmins and developers

Translate this template

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

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

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 Gettext format. 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

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
format*	Format of message files. Examples: `Yaml`, `Java`, `FlatPhp` (for a full list, see `FORMATS` in FileFormatFactory.php).
class	Class which defines the format of message files. Deprecated in Translate 2023.07 in favor of `format`.
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.
`Apple`	Format-specific keys
header	Custom file header comment.
`FlatPhp`	Format-specific keys
header	Custom file header. If not given, it defaults to `<?php`
`Gettext`	Format-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.
`Java`	Format-specific keys
header	Custom file header comment.
keySeparator	The character separating key and value. Default is `=`. Can also be `:`.
`Json`	Format-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.
`Yaml`	Format-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:
  format: Java
  sourcePattern: %GROUPROOT%/commonist/messages_%CODE%.properties
  targetPattern: commonist/messages_%CODE%.properties

MANGLER

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

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

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

AUTOLOAD

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

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

GROUPS (for AggregateMessageGroup class)

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

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.

Message groups for interface messages specific to your wiki

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

See units group for MediaWiki.

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.