nalc/intllib
1
0
Fork 0
mirror of https://github.com/minetest-mods/intllib.git synced 2024-11-14 06:20:31 +01:00
Code Issues Releases Wiki Activity

Reorganize README

Browse Source
This commit is contained in:
Diego Martinez 2016-05-08 16:48:32 -03:00
parent 0c7b30464c
commit dda75d975d
1 changed files with 91 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
README.md
View File

@ -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>
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.
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.
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