diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 131 |
1 files changed, 92 insertions, 39 deletions
@@ -1,12 +1,39 @@ -#Internationalization Lib for Minetest -By Diego MartÃnez (a.k.a. "Kaeza"). +# Internationalization Lib for Minetest + +By Diego MartÃnez (kaeza). Released as WTFPL. This mod is an attempt at providing internationalization support for mods (something Minetest currently lacks). -##How do I use it? +## How to use + +### For end users + +To use this mod, just [install it](http://wiki.minetest.net/Installing_Mods) +and enable it in the GUI. + +The mod tries to detect the user's language, but since there's currently no +portable way to do this, it tries several alternatives, and uses the first one +found: + + * `language` setting in `minetest.conf`. + * If that's not set, it uses the `LANG` environment variable (this is + always set on Unix-like OSes). + * If all else fails, uses `en` (which basically means untranslated strings). + +In any case, the end result should be the +[ISO 639-1 Language Code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) +of the desired language. Also note that (currently) only up to the first two +characters are used, so for example, the settings `de_DE.UTF-8`, `de_DE`, +and `de` are all equal. + +Some common codes are `es` for Spanish, `pt` for Portuguese, `fr` for French, +`it` for Italian, `de` for German. + +### For mod developers + In order to enable it for your mod, copy the following code snippet and paste it at the beginning of your source file(s): @@ -26,61 +53,87 @@ else 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 ``` -You will also need to optionally depend on intllib, to do so add "intllib?" to -a empty line in your depends.txt. Also note that if intllib is not installed, -the S() function is defined so it returns the string unchanged. This is done -so you don't have to sprinkle tons of 'if's (or similar constructs) to check + +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 `S` function is defined so it returns 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. -Next, for each "translatable" string in your sources, use the S() function +Next, for each translatable string in your sources, use the `S` function (defined in the snippet) to return the translated string. For example: ```lua 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, with files -named after the two-letter ISO Language Code of the languages you want to -support. Here's an example for a Spanish locale file ('es.txt'): +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. + +### For translators + +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](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) +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 *Locale file format* below for more information about the file format. + +## Locale file format + +Here's an example for a Spanish locale file (`es.txt`): ```cfg -# Lines beginning with a pound sign are comments and are effectively ignored -# by the reader. Note that comments only span until the end of the line; -# there's no support for multiline comments. +# A comment. +# Another comment. +This line is ignored since it has no equals sign. Hello, World! = Hola, Mundo! String with\nnewlines = Cadena con\nsaltos de linea String with an \= equals sign = Cadena con un signo de \= igualdad ``` -Since there's currently no portable way to detect the language, this library -tries several alternatives, and uses the first one found: - - `language` setting in `minetest.conf` - - `LANG` environment variable (this is always set on Unix-like OSes). - - Default of `"en"`. -Note that in any case only up to the first two characters are used, so for -example, the settings `"de_DE.UTF-8"`, `"de_DE"`, and `"de"` are all equal. -Windows users have no `LANG` environment variable by default. To add it, do -the following: - - Click Start->Settings->Control Panel. - - Start the "System" applet. - - Click on the "Advanced" tab. - - Click on the "Environment variables" button - - Click "New". - - Type "LANG" (without quotes) as name and the language code as value. - - Click OK until all dialogs are closed. -Alternatively for all platforms, if you don't want to modify system settings, -you may add the following line to your 'minetest.conf' file: - language = <language code> - -Also note that there are some problems with using accented, and in general -non-latin characters in strings. Until a fix is found, please limit yourself -to using only US-ASCII characters. +Locale (or translation) files are plain text files consisting of lines of the +form `source text = translated text`. The file must reside in the mod's `locale` +subdirectory, and must be named after the two-letter +[ISO 639-1 Language Code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) +of the language you want to support. + +The translation files should use the UTF-8 encoding. + +Lines beginning with a pound sign are comments and are effectively ignored +by the reader. Note that comments only span until the end of the line; +there's no support for multiline comments. Lines without an equals sign are +also ignored. + +Characters that are considered "special" can be "escaped" so they are taken +literally. There are also several escape sequences that can be used: + + * Any of `#`, `=` can be escaped to take them literally. The `\#` + sequence is useful if your source text begins with `#`. + * The common escape sequences `\n` and `\t`, meaning newline and + horizontal tab respectively. + * The special `\s` escape sequence represents the space character. It + is mainly useful to add leading or trailing spaces to source or + translated texts, as these spaces would be removed otherwise. + +## Final words Thanks for reading up to this point. -Should you have any comments/suggestions, please post them in the forum topic. +Should you have any comments/suggestions, please post them in the +[forum topic](https://forum.minetest.net/viewtopic.php?id=4929). For bug +reports, use the [bug tracker](https://github.com/minetest-mods/intllib/issues/new) +on Github. Let there be translated texts! :P |