LuaLibraryLocale.wiki
author Wuzzy
Wed, 02 May 2018 22:48:07 +0100
changeset 1330 d92ed3272533
parent 1329 bd781e19a52d
child 1333 60d456e83554
permissions -rw-r--r--
LuaLibraries: fix indent
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     1
#summary Lua library documentation: Locale
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     2
#labels LuaLibrary
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     3
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     4
= Lua library: `Locale` =
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     5
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     6
This library allows you to translate strings and should be used whenever a script has text. It loads the appropriate locale file and check automatically.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     7
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     8
== `loc(text)` ==
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     9
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    10
Returns the localised string of `text` or, if it is not found, it returns `text`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    11
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    12
In order for your text to be taken by the string collection tools (so the string becomes available for translation), you have to follow a few simple syntax rules:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    13
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    14
 * `text` _must_ be entirely a literal string
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    15
 * The text _must_ be enclosed in double quotes
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    16
 * You _must_ use the exact character sequence “`loc("`” to initiate the text, no spaces in between are permitted
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    17
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    18
Valid example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    19
<code language="lua">
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    20
AddCaption(loc("Hello World"))  -- Displays “Hello World” translated into your language
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    21
</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    22
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    23
These are all _incorrect_ usages of the `loc` function:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    24
<code language="lua">
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    25
local l
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    26
l = loc( "Hello World")    -- Contains space
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    27
l = loc ("Hello World")    -- Contains space
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    28
l = loc('Hello World')     -- Not double quotes
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    29
local str = "Hello World"
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    30
l = loc(str)   -- Not a literal string
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    31
l = loc(str .. ", how are you?")   -- Only partially a literal string
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    32
</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    33
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    34
Note these examples do _not_ violate Lua syntax, it is in your responsibility to follow the syntax rules listed above.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    35
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    36
== `loc_noop(text)` ==
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    37
Just returns `text`. This function has the same syntax as `loc`. Like for `loc`, the text will be collected to be made available for translation.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    38
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    39
You can use this function if you want a make a string available for translation but don't want the string to be translated right now. This can come in handy if you need to store strings in variables and want do something like `loc(variable_name)` later.