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
[edit]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
[edit]To create a message bundle:
- Start creating a wiki page.
- 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.
- Save the wiki page.
- Go to Page information for the newly created wiki page.
- Change the page content model to Translatable message bundle. This is done on Special:ChangeContentModel.
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
[edit]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, wgPageLanguageUseDB
should be set to true
.
Defining priority languages
[edit]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
[edit]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
[edit]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 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
[edit]Message bundles do not appear on Special:PageTranslation
. They can be translated by:
- Clicking Translate this message bundle at the top of the message bundle page.
- Going to
Special:Translate
page and then searching or the name of the wiki page that was created in the group selector component.
Moving a message bundle
[edit]This process is similar to moving translatable pages. See the following documentation.
Deleting a message bundle
[edit]This process is similar to deleting translatable pages. See the following documentation.
Still to do
[edit]- Ensure that Translation statistics for message bundles work (T360842)
- Ensure that message group stats for message bundles work
Implement fuzzy for translations that are out of date- Provide option to not fuzzy translations for message bundle when source string changes (T317736)
- 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?) Change display format for Message bundle source pages to display JSON in a properly formatted manner.- Remove tags from message bundle page when content model is changed to something else from Translatable message bundle.