diff options
| -rw-r--r-- | doc/developer.md | 78 |
1 files changed, 27 insertions, 51 deletions
diff --git a/doc/developer.md b/doc/developer.md index 7375cfd..551f188 100644 --- a/doc/developer.md +++ b/doc/developer.md @@ -1,12 +1,15 @@ # 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. +## Enabling internationalization -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 (`.po`). -Read below for details on each one. +In order to enable internationalization for your mod, 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") 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 @@ -14,19 +17,26 @@ 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 +Once you have the code in place, you need to mark strings that need +translation. For each translatable string in your sources, use the `S` +function (see above) to return the translated string. For example: -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: + minetest.register_node("mymod:mynode", { + -- Simple string: + description = S("My Fabulous Node"), + -- String with insertions: + description = S("@1 Car", "Blue"), + -- ... + }) - -- Load support for intllib. - local MP = minetest.get_modpath(minetest.get_current_modname()) - local S, NS = dofile(MP.."/intllib.lua") +The `NS` function is the equivalent of `ngettext`. It should be used when the +string to be translated has singular and plural forms. For example: -Use the usual `xgettext` command line tool from [gettext][gettext], to -generate your catalog files in a directory named `locale`. + -- The first `count` is for `ngettext` to determine which form to use. + -- The second `count` is the actual replacement. + print(NS("You have one item.", "You have @1 items.", count, count)) -### Basic workflow +## Generating and updating catalogs This is the basic workflow for working with [gettext][gettext] @@ -36,8 +46,9 @@ Each time you have new strings to be translated, you should do the following: /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. +and will generate the file `template.pot` (a template with all the translatable +strings). 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: @@ -48,39 +59,4 @@ 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. -## 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/ |