Add support for gettext message catalogs.

doc/developer.md

@@ -0,0 +1,96 @@
+
+# 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][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 `if`s (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][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.
+
+[gettext]: https://www.gnu.org/software/gettext/

doc/translator.md

@@ -0,0 +1,20 @@
+
+# Intllib translator documentation
+
+#### New interface
+
+Use your favorite tools to edit the `.po` files.
+
+#### Old interface
+
+To translate an intllib-supporting mod to your desired language, copy the
+`locale/template.txt` file to `locale/LANGUAGE.txt` (where `LANGUAGE` is the
+[ISO 639-1 Language Code][ISO639-1] of your language.
+
+Open up the new file in your favorite editor, and translate each line putting
+the translated text after the equals sign.
+
+See `localefile.md` for more information about the file format.
+
+[gettext]: https://www.gnu.org/software/gettext/
+[ISO639-1]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes