Fandom Developers Wiki
Advertisement

I18n library for message storage in Lua datastores. The module is designed to enable message separation from modules & templates. It has support for handling language fallbacks. This module is a Lua port of I18n-js and i18n modules that can be loaded by it are editable through I18nEdit.

Usage

To use the module, you need to set up your messages in the appropriate place and correct format. The format of your messages should be as follows:

return {
    ["en"] = {
        ["message-name"] = "value"
    },
    ["pl"] = {
        ["message-name"] = "value"
    }
}

Messages can have arguments for substitution in templates/modules - these should be specified in the form $n where n is a integer greater than 0, e.g, "Hello, $1, my name is $2".

Fetching the messages

The message loader will expect your messages to be in a Dev Wiki page such as Module:PAGENAME/i18n, where PAGENAME should be the name of your module. Alternatively, an absolute path can be supplied (if PAGENAME contains a ":").

Once you've set up the messages, there are two ways to fetch them.

1. Import the module into a Lua module and create a datastore instance using the i18n.loadMessages method:

local i18nd = require('Dev:I18n').loadMessages('PAGENAME', 'PAGENAME2')
-- If a PAGENAME contains a ":" the path will be treated as absolute!

2. Fetch messages directly within your template:

Documentation

Package items

i18n.getMsg(frame) (function)
Localized message getter by key. Can be used to fetch messages in a specific language code through uselang parameter. Extra numbered parameters can be supplied for substitution into the datastore message.
Parameters:
  • frame Frame table from invocation. (table)
    • frame.args Metatable containing arguments. (table)
      • frame.args[1] ROOTPAGENAME of i18n submodule. (string)
      • frame.args[2] Key of i18n message. (string)
      • frame.args.lang Default language of message. (string; optional)
Error: 'missing arguments in i18n.getMsg' (line 271)
Returns: I18n message in localised language. (string)
Usage: {{i18n|getMsg|<source>|<key>|<arg1>|<arg2>|uselang [[:Template: = <]] code>}}
i18n.loadMessages(...) (function)
I18n message datastore loader.
Parameter: ... ROOTPAGENAME/path for target i18n submodules. (string)
Error: 'no source supplied to i18n.loadMessages' (string; line 322)
Returns: I18n datastore instance. (table)
Usage: require('Dev:I18n').loadMessages('1', '2')
i18n.getLang() (function)
Language code getter. Can validate a template's language code through uselang parameter.
Returns: Language code. (string)
Usage: {{i18n|getLang|uselang [[:Template: = <]] code>}}
i18n.main(frame) (function)
Template wrapper for Template:I18n.
Parameter: frame Frame invocation object. (table)
Returns: Module output in template context. (string)
Usage: {{#invoke:i18n|main}}
_i18n.isWikitext(msg) (function)
Checks whether a message contains unprocessed wikitext. Used to optimise message getter by not preprocessing pure text.
Parameter: msg Message to check. (string)
Returns: Whether the message contains wikitext. (boolean)

Data

I18n datastore class. This is used to control language translation and access to individual messages. The datastore instance provides language and message getter-setter methods, which can be used to internationalize Lua modules. The language methods (any ending in Lang) are all chainable.

Data:msg(opts, ...) (function)
Datastore message getter utility. This method returns localized messages from the datastore corresponding to a key. These messages may have $n parameters, which can be replaced by optional argument strings supplied by the msg call.
This function supports named arguments. The named argument syntax is more versatile despite its verbosity; it can be used to select message language & source(s).
Parameters:
  • opts Message configuration or key. (string|table)
    • opts.key Message key to return from the datastore. (string; optional)
    • opts.args Arguments to substitute into the message ($n). (table; optional)
    • opts.sources Source names to limit to (see Data:fromSources). (table; optional)
    • opts.lang Temporary language to use (see Data:inLang). (table; optional)
  • ... Arguments to substitute into the message ($n). (string; optional)
Error: 'missing arguments in Data:msg' (string; line 115)
Returns: Localised datastore message or '<key>'. (string)
Usage:
  • ds:msg{
        key = 'message-name',
        lang = '',
        args = {...},
        sources = {}
    }
    
  • ds:msg('message-name', ...)
Data:parameter(parameter, args) (function)
Datastore template parameter getter utility. This method, given a table of arguments, tries to find a parameter's localized name in the datastore and returns its value, or nil if not present. This method always uses the wiki's content language.
Parameters:
  • parameter Parameter's key in the datastore (string)
  • args Arguments to find the parameter in (table)
Error: 'missing arguments in Data:parameter' (string; line 176)
Returns: Parameter's value or nil if not present (string|nil)
Data:fromSource(...) (function)
Datastore temporary source setter to a specificed subset of datastores. By default, messages are fetched from the datastore in the same order of priority as i18n.loadMessages.
Parameter: ... Source name(s) to use. (string)
Returns: Datastore instance. (Data)
Data:getLang() (function)
Datastore default language getter.
Returns: Default language to serve datastore messages in. (string)
Data:useUserLang() (function)
Datastore language setter to wgUserLanguage.
Returns: Datastore instance. (Data)
Note: Scribunto only registers wgUserLanguage when an invocation is at the top of the call stack.
Data:useContentLang() (function)
Datastore language setter to wgContentLanguage.
Returns: Datastore instance. (Data)
Data:useLang(code) (function)
Datastore language setter to specificed language.
Parameter: code Language code to use. (string)
Returns: Datastore instance. (Data)
Data:inUserLang() (function)
Temporary datastore language setter to wgUserLanguage. The datastore language reverts to the default language in the next Data:msg call.
Returns: Datastore instance. (Data)
Data:inContentLang() (function)
Temporary datastore language setter to wgContentLanguage. Only affects the next Data:msg call.
Returns: Datastore instance. (Data)
Data:inLang(code) (function)
Temporary datastore language setter to a specificed language. Only affects the next Data:msg call.
Parameter: code Language code to use. (string)
Returns: Datastore instance. (Data)

See also

Editing the messages

The editor used for I18n-js translations has also been made to work with translations using this module. Make sure you switch to Lua translations using the option in the edit dropdown on the translation picker screen.

Changelog

June 10, 2018 [ALPHA]‎
KockaAdmiralac: JSON-centric prototype and template testing.
June 12, 2018 (v0.5.0-v0.7.0)
MACH-59330: Port of I18n-js functions and Lua datastore support.
June 13, 2018 (v0.8.0)
MACH-59330: Functional Lua prototype. Code cleanup and testing.
June 16, 2018 (v0.9.0-v0.9.4)
KockaAdmiralac, MACH-59330: Testing and tweaks.
  • Failed testing of JSON support and caching.
  • Subpage /lang detection fix.
July 5, 2018 (v1.0.0 - v.1.0.2) [STABLE]
MACH-59330: Support for absolute source paths.
Technobliterator: Scope default datastore path to w:c:dev.
July 12, 2018 (v1.0.3) [STABLE]
KockaAdmiralac: Support for multiple message datastores.
July 13, 2018 (v1.0.4)
MACH-59330: Permit wikitext parsing in messages.
July 14, 2018 (v1.0.5)
MACH-59330: Respect uselang template parameter when fetching user language.
July 20, 2018 (v1.0.6)
KockaAdmiralac: Add i18nd:in* functions to reflect I18n-js's recently added functionality.
July 26, 2018 (v1.0.7)
MACH-59330: Add support for qqx message keys.
July 28, 2018 (v1.0.7)
MACH-59330: Add i18nd:getLang for Lua modules.
July 28, 2018 (v1.1.0)
MACH-59330: Language detection fixes; uselang as override.
August 15, 2018 (v1.1.1)
MACH-59330: Language detection for qqx.
September 12, 2018 (v1.1.2 - v1.2.0)
MACH-59330: Add i18nd:fromSource; support named parameters in i18nd:msg.
September 12, 2018 (v1.3.0)
MACH-59330: Add template wrapper support through i18n.main.
September 12, 2018 (v1.3.0)
MACH-59330: Add template wrapper support through i18n.main.
November 6 & 13, 2018 (v1.3.1)
MACH-59330: Prioritise subpage language over user language by default.
KockaAdmiralac: Add content language fallback for wikis without {{int:lang}}.
November 19, 2018 (v1.3.2)
MACH-59330: Fix subpage test in i18n.getLang.
November 20, 2018 (v1.3.2)
MACH-59330: Remove support for qqx detection (broken).
Advertisement