LuaLibraryLocale.wiki
author Wuzzy
Wed, 02 May 2018 22:51:20 +0100
changeset 1340 7f33db983b23
parent 1335 e47b0b5bf153
child 1344 250cb1218787
permissions -rw-r--r--
LuaLibraryTargetPractice: remove label
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1334
d8462452d5e3 LuaLibraryLocale: Edited via web interface
Wuzzy
parents: 1333
diff changeset
     1
#summary Lua library documentation for Locale
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     2
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     3
= Lua library: `Locale` =
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     4
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     5
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
     6
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     7
== `loc(text)` ==
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     8
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     9
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
    10
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    11
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
    12
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    13
 * `text` _must_ be entirely a literal string
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    14
 * The text _must_ be enclosed in double quotes
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    15
 * 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
    16
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    17
Valid example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    18
<code language="lua">
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    19
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
    20
</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    21
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    22
These are all _incorrect_ usages of the `loc` function:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    23
<code language="lua">
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    24
local l
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    25
l = loc( "Hello World")    -- Contains space
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')     -- Not double quotes
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    28
local str = "Hello World"
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    29
l = loc(str)   -- Not a literal string
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    30
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
    31
</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    32
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    33
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
    34
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    35
== `loc_noop(text)` ==
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    36
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
    37
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    38
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.