diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/developer.md | 96 | ||||
| -rw-r--r-- | doc/translator.md | 20 |
2 files changed, 116 insertions, 0 deletions
diff --git a/doc/developer.md b/doc/developer.md new file mode 100644 index 0000000..9408b1a --- /dev/null +++ b/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/ diff --git a/doc/translator.md b/doc/translator.md new file mode 100644 index 0000000..3c278e8 --- /dev/null +++ b/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 |