Updated readme, in an attempt to make it more readable

1 files changed, 90 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..518e698
--- /dev/null
+++ b/README.md
@@ -0,0 +1,90 @@
+
+#Internationalization Lib for Minetest
+By Diego Martínez (a.k.a. "Kaeza").
+Released as WTFPL.
+
+This mod is an attempt at providing internationalization support for mods
+(something Minetest currently lacks).
+
+##How do I use it?
+In order to enable it for your mod, copy the following code snippet and paste
+it at the beginning of your source file(s):
+
+```lua
+-- 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
+```
+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
+if the lib is actually installed.
+
+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", {
+	description = S("My Fabulous Node"),
+	<...>
+})
+```
+
+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'):
+
+```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.
+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.
+
+Thanks for reading up to this point.
+Should you have any comments/suggestions, please post them in the forum topic.
+
+Let there be translated texts! :P
+
+\--
+
+Yours Truly,
+Kaeza