Global Lua Modules/I18n

I18n library for message storage in Lua datastore submodules. 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:

Template installation

Transclusion

Add this template on your wiki:

Site-wide

Template:I18n

Template usage

{{i18n|getMsg|<PAGENAME>|<key>}}

Documentation[]

Package items[]

i18n.getMsg(frame) (function)

Gets a localized message by data module 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 data collection's message.

Parameters:

frame Frame table from invocation. (table)
- frame.args Metatable containing arguments. (table)
- frame.args1 ROOTPAGENAME of i18n submodule. (string; optional)
- frame.args2 Key of i18n message. (string; optional)
  - 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 data loader for message collections.

Parameter: ... ROOTPAGENAME/path for target i18n submodules. (string)

Error: 'no source supplied to i18n.loadMessages' (line 322)

Returns: I18n datastore instance. (table)

Usage: require('Dev:I18n').loadMessages('1', '2')

i18n.getContentLang() (function)

Gets the language code of the wiki or page contents.

Returns: Content language code. (string)

Usage: {{i18n|<getContentLang>}}

i18n.getLang() (function)

Gets the language code of the content. 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() (function)

Gets data message 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).

Data:msg(opts, ...) (function)

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' (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)

Gets localised template parameter from a datastore. 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' (line 176)

Returns: Parameter's value or nil if not present (string|nil)

Data:fromSource(...) (function)

Sets temporary source 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)