intllib/doc/developer.md

Intllib developer documentation

In order to enable it for your mod, copy some boilerplate into your source file(s). What you need depends on what you want to support.

There are now two main interfaces: one using the old plain text file method, and one using the new support for gettext message catalogs (.mo). Read below for details on each one.

You will also need to optionally depend on intllib, to do so add intllib? to an empty line in your depends.txt. Also note that if intllib is not installed, the getter functions are defined so they return the string unchanged. This is done so you don't have to sprinkle tons of ifs (or similar constructs) to check if the lib is actually installed.

New interface

You will need to copy the file lib/intllib.lua into the root directory of your mod, then include this boilerplate code in files needing localization:

-- Load support for intllib.
local MP = minetest.get_modpath(minetest.get_current_modname())
local S, NS = dofile(MP.."/intllib.lua")

Use the usual gettext tools (xgettext, msgfmt, etc.), to generate your catalog files in a directory named locale.

Note: Drop the .mo file directly as locale/$lang.mo. Not in locale/$lang/LC_MESSAGES/$domain.mo!

You should also provide the source .po and .pot files.

Basic workflow

This is the basic workflow for working with gettext

Each time you have new strings to be translated, you should do the following:

cd /path/to/mod
/path/to/intllib/tools/xgettext.sh file1.lua file2.lua ...

The script will create a directory named locale if it doesn't exist yet, and will generate the file template.pot. If you already have translations, the script will proceed to update all of them with the new strings.

The script passes some options to the real xgettext that should be enough for most cases. You may specify other options if desired:

xgettext.sh -o file.pot --keyword=blargh:4,5 a.lua b.lua ...

NOTE: There's also a Windows batch file xgettext.bat for Windows users, but you will need to install the gettext command line tools separately. See the top of the file for configuration.

Once a translator submits an updated translation, you should run the msgfmt tool:

msgfmt locale/ll_CC.po -o locale/ll_CC.mo

Old interface

You will need this boilerplate code:

-- Boilerplate to support localized strings if intllib mod is installed.
local S
if minetest.get_modpath("intllib") then
    S = intllib.Getter()
else
    -- If you don't use insertions (@1, @2, etc) you can use this:
    S = function(s) return s end

    -- If you use insertions, but not insertion escapes this will work:
    S = function(s,a,...)a={a,...}return s:gsub("@(%d+)",function(n)return a[tonumber(n)]end)end

    -- Use this if you require full functionality
    S = function(s,a,...)if a==nil then return s end a={a,...}return s:gsub("(@?)@(%(?)(%d+)(%)?)",function(e,o,n,c)if e==""then return a[tonumber(n)]..(o==""and c or"")else return"@"..o..n..c end end) end
end

Next, for each translatable string in your sources, use the S function (defined in the snippet) to return the translated string. For example:

minetest.register_node("mymod:mynode", {
    -- Simple string:
    description = S("My Fabulous Node"),
    -- String with insertions:
    description = S("@1 Car", "Blue"),
    -- ...
})

Then, you create a locale directory inside your mod directory, and create a "template" file (by convention, named template.txt) with all the translatable strings (see Locale file format below). Translators will translate the strings in this file to add languages to your mod.