Help:Extension:Translate/Message Bundles

Message bundles contain strings in key-value JSON format that, representing a message group that can be translated. Each key represents a translation unit and the value is the translation unit source that can be translated.

Unlike translatable pages, message bundles do not have translation pages.

Enabling message bundle integration

By default the message bundle integration is disabled, to enable it update your LocalSettings.php to add,

$wgTranslateEnableMessageBundleIntegration = true;

To be able to set source language of the message bundles to be different that the default wiki language, set $wgPageLanguageUseDB:

$wgPageLanguageUseDB = true;

We also recommend allowing translation administrators the ability to change the content model of pages (editcontentmodel right).

See Manual:$wgPageLanguageUseDB for more details.

Creating a message bundle

To create a message bundle,

1. Start creating a wiki page.
2. Paste JSON content where the key and value are both strings. The key is the translation unit id and the value is the translation unit source.
3. Save the wiki page.
4. Go to Page information for the newly created wiki page.
5. Change the page content model to Translatable message bundle.

Example of a message bundle:

{
  "@metadata": {
    "sourceLanguage": "fr",
    "priorityLanguages": [
      "es",
      "en"
    ]
  },
  "greetings": "hello",
  "body": "This is the body of the bundle.",
  "salutations": "Good bye",
  "signed": "Abijeet Patro"
}

The content under @metadata is not translatable.

Declaring a source language

To define the source language for a message bundle, add an object with the @metadata key in the message bundle content, and add the sourceLanguage key.

For example to set the source language to French:

{
  "@metadata": {
	  "sourceLanguage": "fr"
  }
}

To update the source language, the wgPageLanguageUseDB should be set to true.

Defining priority languages

To define priority languages for a message bundle message group, define priorityLanguages inside the @metadata object in the message bundle content.

For example to set the priority language of a message bundle to Spanish, Italian, Hindi and Odia:

{
  "@metadata": {
	  "priorityLanguages": [ "es", "it", "hi", "or" ]
  }
}

Additionally the key allowOnlyPriorityLanguages inside @metadata can be set to true to disable translations to non priority languages completely.

Defining a label

Labels defined in the message bundle @metadata will be used in the group selector on Special:Translate and as the page display title.

{
  "@metadata": {
	  "label": "My message bundle title"
  }
}

Structure of message bundle

Assume a message bundle MB-2024 is created with the following structure:

{ 
  "@metadata": {
	  "sourceLanguage": "fr"
  },
  "key-a": "hello",
  "key-b": "This is the body of the bundle.",
  "key-c": "Good bye"
}

The above message bundle has the source language fr.

When the message bundle is created the following pages will be automatically created:

• Translations:MB-2024/key-a/fr
• Translations:MB-2024/key-b/fr
• Translations:MB-2024/key-c/fr

If a key-a is translated to English then, the page Translations:MB-2024/key-a/en will be created with the translation.

Message bundles do not have translation pages.

Translating a message bundle

Message bundles do not appear on Special:PageTranslation. They can be translated by going to Special:Translate page and then searching or the name of the wiki page that was created in the group selector component.

On selecting the message bundle, the translation units will be displayed for translation.

Moving a message bundle

This process is similar to moving translatable pages. See the following documentation.

Deleting a message bundle

This process is similar to deleting translatable pages. See the following documentation.

Still to do

1. Ensure that Translation statistics for message bundles work (task T360842)
2. Ensure that message group stats for message bundles work
3. Implement fuzzy for translations that are out of date
4. Provide option to not fuzzy translations for message bundle when source string changes (task T317736)
5. Create a page where message bundles can be viewed similar to Special:PageTranslation (maybe core could provide a way to list all pages with a given content model?)
6. Change display format for Message bundle source pages to display JSON in a properly formatted manner.
7. Remove tags from message bundle page when content model is changed to something else from Translatable message bundle.