 Warning: | This is abeta feature and we're looking for feedback on how to improve it. There is aperformance issue that should be addressed before we can do a wider roll-out. |
This page documents how to use Message Bundles in Lua modules with the Translate extension using themw.ext.translate.messageBundle Lua library. Message bundles are structured collections of translatable key-value pairs stored in wiki pages using a JSON format. This approach makes it easier to manage interface strings in code, while allowing translators to localize content through the Special:Translate interface. The guide explains how to define, enable, and access these bundles from Lua, along with metadata options.
Translatable modules is a project to define, implement, document, and deploy a framework to improve the ability to translate and share modules. The goal is for user interface strings (messages) in Scribunto modules on multilingual wiki sites, such as Wikidata and Commons, to be easily localized, similarly to core MediaWiki, extensions, and translatable pages.
Read more atTranslatable modules.
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.
Read more atHelp:Extension:Translate/Message Bundles.
We built message bundles to reduce the complexity around localization of Scribunto modules. Since Message bundles are JSON objects, they can be used to store translations that can then be queried and used in Scribunto modules.
This document describes a Lua module that is built into theTranslate extension in order to provide Scribunto modules an API that they can use to query message bundles.
To add message bundle support to the module, add this:
localtmb=require'mw.ext.translate.messageBundle'
Creating a message bundle object to access the message bundle in the pageMessageBundleDemoForever:
--- MessageBundleDemoForever is the name of the page containing the message bundlelocalmb=tmb.new("MessageBundleDemoForever")
The argument can be a string or anmw.title object but it must be the name or title of a valid message bundle page. With this message bundle object, translations will be loaded in the page language, and if certain keys lack translations, fallback languages are loaded.
To load a particular language, you can pass the language code as the second parameter.
--- MessageBundleDemoForever is the name of the page containing the message bundlelocalmb=tmb.new("MessageBundleDemoForever","es")
The message bundle object has the following method(s):
t( key ): Returns translation loaded for a key in the message bundle as anmw.message object (mw.message documentation). Returnsnil if a non-existent key is passed as parameter.getAllTranslations(): Returns atable containing all the keys in the message bundle and their translations as strings.By default, fallback languages are loaded. For example, if you request translation for Brazilian Portuguese (pt-br), and certain keys in the message bundle don't have translations in Brazilian Portuguese, Portuguese (pt) translations will be loaded if present, and if those are missing too, then the source language strings will be loaded.
To create a message bundle object with only Brazilian Portuguese translations, without loading any fallback language:
localmb=tmb.newWithoutFallbacks("MessageBundleDemoForever","pt-br")
Disabling fallback language loading improves performance. If loading of fallback languages is disabled, accessing translations for certain strings may returnnil depending on whether they have been translated.
Given the following message bundle, in a page namedMessageBundleDemoForever with the page content model set toTranslatable message bundle,
{"@metadata":{"priorityLanguages":["es","it"]"description":"You can add an optional tip or note related to the prompt like this.",},"choice1":"a correct answer, $1","choice2":"an incorrect answer","choice3":"an incorrect answer","choice4":"a correct answer","choice5":"Another incorrect answer ...","people-sent-messages":"$1 {{PLURAL:$1|person|people}} sent messages to $1 to congratulate {{GENDER:$1|him|her|them}} upon promotion to administrator"}
A translation administrator should add the message bundle to anaggregate group.
To access the translation for the key:problem.choiceresponse.checkboxgroup.choice.5 inthe page language in which the module is loaded, the following code can be used:
-- Load the translations in the page language in which the module is loadedlocalmb=mw.ext.translate.messageBundle.new("MessageBundleDemoForever")-- Access the needed key-- Assuming the page language where the template is used is English, prints:-- a correct answer, Johnmb:t("choice1"):params('John')
To load translations in a specific language, Spanish in this case:
-- Load the translations for the message bundle in Spanishlocalmb=mw.ext.translate.messageBundle.new("MessageBundleDemoForever","es")-- Access the needed key-- Assuming the choice1 key is translated to Spanish, prints:-- ¡Una respuesta correcta, Johnmb:t("choice1"):params('John');
By default, translations in the fallback language will be loaded. To disable loading language fallback:
-- Load the translations in the page language, but skip using fallbackslocalmb=mw.ext.translate.messageBundle.newWithoutFallbacks("MessageBundleDemoForever",'fr')-- Access the needed key, without loading any fallback translations-- Assuming there are no translations in French, prints nothingmb:t("choice5")
{{GENDER}} and{{PLURAL}} can be used in messages loaded into modules. However, they are not parsed by default, and they require preprocessing. In Lua code, it's done like this:
frame:preprocess(mb:t("people-sent-messages"):plain())
Callingframe:preprocess() ensures that{{GENDER}} and{{PLURAL}} are parsed.:plain() is necessary because by default,t() returns a table, andframe:preprocess() requires a string.