Help:Extension:Translate/Message Bundles/Lua reference - MediaWiki

Help:Extension:Translate/Message Bundles/Lua reference - MediaWiki
Jump to content
From mediawiki.org
Help:Extension:Translate
Message Bundles
Warning:
This is a
beta
feature and we're looking for feedback on how to improve it. There is a
performance 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 the
mw.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.
Background information
edit
Why translatable modules?
edit
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 at
Translatable modules
What are message bundles?
edit
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 at
Help:Extension:Translate/Message Bundles
What is this project trying to do?
edit
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 the
Translate extension
in order to provide Scribunto modules an API that they can use to query message bundles.
API reference
edit
Initialization
edit
To add message bundle support to the module, add this:
local
tmb
require
'mw.ext.translate.messageBundle'
Message bundle object
edit
Creating a message bundle object to access the message bundle in the page
MessageBundleDemoForever
--- MessageBundleDemoForever is the name of the page containing the message bundle
local
mb
tmb
new
"MessageBundleDemoForever"
The argument can be a string or an
mw.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 bundle
local
mb
tmb
new
"MessageBundleDemoForever"
"es"
Fields and methods
edit
The message bundle object has the following method(s):
t( key )
: Returns translation loaded for a key in the message bundle as an
mw.message
object (
mw.message documentation
). Returns
nil
if a non-existent key is passed as parameter.
getAllTranslations()
: Returns a
table
containing all the keys in the message bundle and their translations as strings.
Fallback language
edit
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:
local
mb
tmb
newWithoutFallbacks
"MessageBundleDemoForever"
"pt-br"
Disabling fallback language loading improves performance. If loading of fallback languages is disabled, accessing translations for certain strings may return
nil
depending on whether they have been translated.
Use cases
edit
Given the following message bundle, in a page named
MessageBundleDemoForever
with the page content model set to
Translatable 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 an
aggregate group
Accessing translation for a key
edit
To access the translation for the key:
problem.choiceresponse.checkboxgroup.choice.5
in
the 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 loaded
local
mb
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, John
mb
"choice1"
):
params
'John'
Accessing translation for a key in a particular language
edit
To load translations in a specific language, Spanish in this case:
-- Load the translations for the message bundle in Spanish
local
mb
mw
ext
translate
messageBundle
new
"MessageBundleDemoForever"
"es"
-- Access the needed key
-- Assuming the choice1 key is translated to Spanish, prints:
-- ¡Una respuesta correcta, John
mb
"choice1"
):
params
'John'
);
Enabling/disabling fallback language loading
edit
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 fallbacks
local
mb
mw
ext
translate
messageBundle
newWithoutFallbacks
"MessageBundleDemoForever"
'fr'
-- Access the needed key, without loading any fallback translations
-- Assuming there are no translations in French, prints nothing
mb
"choice5"
Using GENDER and PLURAL
edit
{{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
"people-sent-messages"
):
plain
())
Calling
frame:preprocess()
ensures that
{{GENDER}}
and
{{PLURAL}}
are parsed.
:plain()
is necessary because by default,
t()
returns a table, and
frame:preprocess()
requires a string.
Future changes
edit
The methods in the module do not provide additional information about the translations, such as the current state (fuzzy, normal, reviewed, etc.) or which fallback language is being used in case the translation is not available in the requested language. We will be adding additional methods to provide these features.
Retrieved from "
Help
Extension:Translate/Message Bundles/Lua reference
Add topic