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 know the exact name of the message already). For each group we can gather statistics and each group has unique identifier. And messages are naturally the smallest blocks of text that translators translate one at time. Each message has also a identifier usually referred as key. Key don't need to be unique across message groups.

The intention is to migrate everything to new format based on YAML formatted files. About half of the premade groups are already using YAML configuration.

Standard group configuration format

It is very easy to add message groups using the new standard format. All that needs to be done is to define a namespace and add a configuration file into $wgTranslateGroupFiles; see configuration page for more details. Example:

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

The files itself use 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 line with three dashes, which is the standard document separator in YAML.

Definitions are broken into few top-level items: BASIC, FILES, MANGLER, CHECKER, TAGS, AUTOLOAD 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.
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 supported.
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).

Example:

BASIC:
  id: out-freecol
  label: FreeCol (open source game)
  description: "{{int:bw-desc-freecol}}"
  namespace: NS_FREECOL
  class: FileBasedMessageGroup

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
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 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 directorty. 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.
YamlFFS	Class specific keys
codeAsRoot	If 1 all messages are under a language code (instead of at the root).
FlatPhpFFS	Class specific keys
header	Custom file header. If not given, it defaults to <?php
JavaFFS	Class specific keys
keySeparator	???

The path variables are:

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

Example:

FILES:
  class: JavaFFS
  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:
    - "*"

CHECKER

Checkers run checks on the translated messages. If they find problems, those translations are highlighted for translators.

Key	Description
class*	The checker class to use.
checks*	List of methods in the class given above.

Example:

CHECKER:
  class: ShapadoMessageChecker
  checks:
    - ShapadoVariablesCheck

TAGS

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

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:
    class: YamlFFS
    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

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.

/* Value can be either anything callable, which is called by key as parameter,
 * or it can be instance of MessageGroup.
 */
$wgTranslateCC['wiki-custom'] = 'customMessageGroup';
 
// $id is the "wikigroup" given above
function customMessageGroup( $id ) {
        // List of message keys (just the page names without prefix) is at MediaWiki:wikiname-messages
        $mg = new WikiMessageGroup( $id, 'wikiname-messages' );
        $mg->setLabel( 'Wikiname User Interface Messages' );
        $mg->setDescription( 'This group contains user interface messages used on Wikiname.' );
        return $mg;
}