Module locale
Localization.
Use these facilities to enable the localization of your application.
The main facility here is the T function. You should prepend a “T” to any string literal in your code intended for human consumption. At run-time this string will be replaced with a version in the user’s language, if such exists.
Functions
format_number(n[, precision]) | Formats a number according to the locale. |
format_plural(singular, plural, n [, translate_only]) | Translates a string, plural version. |
Global functions
E"string" | Marks programmer-facing error messages. |
N"string" | Marks a string for translation. |
Q"ctx|string" | Translates a string, with context. |
T"string" | Translates a string. |
Functions
- format_number(n[, precision])
-
Formats a number according to the locale.
In most English-speaking countries, for example, this means that a comma is added every three digits, and that a period is used as the decimal mark. This is also the case (for this function alone; not as a general rule in the computing world) for the POSIX locale. Other locales have other rules.
-- en_US, or POSIX/C assert(locale.format_number(1234567.89) == "1,234,567.89") -- da_DK assert(locale.format_number(1234567.89) == "1.234.567,89") -- nl_NL assert(locale.format_number(1234567.89) == "1234567,89")
You may set the number of digits to show after the decimal mark with the optional precision argument.
See also utils.text.format_size.
- format_plural(singular, plural, n [, translate_only])
-
Translates a string, plural version.
This function translates a string based on a number, and embeds the number in the string (as per the rules of string.format).
local n = 5 alert(locale.format_plural("%d file", "%d files", n))
(See another example at ui.Panel:files.)
If the optional translate_only argument is true, the embedding is skipped. Thus, the following is equivalent to the code above:
alert(locale.format_plural("%d file", "%d files", n, true):format(n))
Global functions
- E"string"
-
Marks programmer-facing error messages.
There are two kinds of error messages: those intended for end-users, which you'd mark with T, and those intended for programmers, which you'd mark with E.
We don’t want programmers' messages to be translated. That’s because programmers may post them on public forums asking for help, and having these messages in Swahili (for example) instead of English will result in (1) developers not being able to help and (2) developers' blood pressure rising.
E, therefore, does nothing. It’s a “no-op”. So, you may ask, why use it at all? To show the reader of the code that a T wasn’t omitted by negligence. And, in the future, if we change our policy, E might behave just like T.
- N"string"
-
Marks a string for translation.
You'll seldom use this “marker” in your Lua code. A similar marker is frequently used in C programs but scripting languages like Lua don’t have the limitations that make this marker a necessity in C.
This function is a no-op. It exists only for the benefit of the translation extractor.
Use this function when a string is to be stored in some “database” in English and at a later stage translated.
local db = { N"one", N"two", N"three" } for _, s in ipairs(db) do print(T(s)) end
- Q"ctx|string"
-
Translates a string, with context.
Sometimes the same English source string, especially when it’s composed of a single word, has to be translated differently in different contexts. For example, the English word “Open” may be either an adjective describing the state of a file or a verb describing a command to carry out. While in English the two words happen to look the same, this may not be the case in other languages.
Q is similar to T except that it lets you prefix the string with a token (“qualifier”, hence the letter Q) to differentiate the contexts. This token is passed down to the POT file so human translators can see it but is removed when the Q function actually runs.
local dialog = ui.Dialog(T"DialogTitle|Open")
The qualifier is everything till the first “|”.
- T"string"
-
Translates a string.
Use it for strings that are intended for humans (as opposed to ones intended for the machine, like IDs, which don’t need translation).
alert(T"Hello World!")
The string argument should be a literal. It can’t be a variable (unless used in tandem with N). That’s because a tool (a POT extractor) analyzes the source code itself and extracts all such marked strings.
For a similar reason you can’t concatenate strings like this:
-- This is wrong! alert(T("My name is " .. name .. " and I'm from " .. country))
For “linguistic” reasons neither can you do:
-- This is wrong! alert(T"My name is " .. name .. T" and I'm from " .. country))
Instead you should use :format, as in:
-- correct! alert(T"My name is %s and I'm from %s":format(name, country))