LuaLibraryLocale.wiki
author Wuzzy
Thu, 10 Oct 2019 22:33:36 +0100
changeset 2006 75df3ddba09c
parent 1408 af21a7367640
permissions -rw-r--r--
LuaGameplay: Clarify limitations of GetRandom
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1372
8f3e1058f2bb LuaLibraryLocale: summary
Wuzzy
parents: 1344
diff changeset
     1
#summary Lua library documentation of Locale; for making your Lua scripts translatable
1344
250cb1218787 LuaLibraryLocale: add label
Wuzzy
parents: 1335
diff changeset
     2
#labels !LuaLibrary
1329
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"
1408
af21a7367640 LuaLibraryLocale: clarify loc(str)
Wuzzy
parents: 1372
diff changeset
    30
l = loc(str)   -- Not a literal string, only use this if you use this together with `loc_noop`
1329
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.