The Localization subsystem is designed to allow your project to be translated into different languages. If you've decided to enable this system on your project, translations will automatically be injected into your files based on the formatting outlined in this article.

Here is an example substitution:

@localization(locale="enUS", format="lua_table")@

The example turns into something that looks like this:

{ ["Some key"] = "Some value" }

Take me to...

• Arguments
• Example usage
  • enUS.lua
  • deDE.lua
  • enUS.lua
  • deDE.lua

Arguments

Note: only locale and format are required.

• locale
  • one of "enUS", "frFR", "deDE", etc. You'll see a full list of each possible locale on your project's localization page.
• format
  • if "lua_table", then it will look like { ["Some key"] = "Some value" }
  • if "lua_additive_table", then it will look like L["Some key"] = "Some value"
• key
  • Inserts the translation for the given phrase key. If this is used, the format argument is ignored.
• handle-unlocalized - what to do when you have an unlocalized string.
  • if "english", then it will output the english value.
  • if "comment", then it will output the english value, but comment it out the line.
  • if "blank" (default), then it will output "", but comment out the line.
  • if "ignore", then no line will be printed out.
• escape-non-ascii - whether to escape non-ASCII (unicode) strings as escape strings instead of raw UTF-8
  • if false (default), then you get a string like "Über"
  • if true, then you get a string like "\195\156ber"
• prefix-values
  • This will prefix all value strings the given string. For WoW, the default is nothing. For other games, especially those which are unicode-aware, the prefix could be something along the lines of "L". e.g. "Hello" vs. L"Hello"
• table-name - used in format="lua_additive_table" only.
  • This defines the name of the table to add to. For WoW, the default is "L". For WAR, the default is "T".
• same-key-is-true
  • true - if the key is the same as the value, then make the value = true rather than the value itself.
  • false (default) - no special action when value == key.
• namespace
  • "" (default) - the base namespace, all namespaces derive from this and phrases not attached to a namespace are on this base.
  • "Monkey" - the "Monkey" namespace. This varies based on your project.
  • "Monkey/Banana" - the "Monkey/Banana" subnamespace. This varies based on your project.
• handle-subnamespaces
  • "none" (default) - don't show subnamespaces at all
  • "subtable" - show subnamespaces as a lua sub-table.
  • "concat" - concatenate the namespace with the key.
• namespace-delimiter - used when handle-subnamespaces="concat"
  • "/" (default) - concatenate with / as the delimiter.
  • "." - use "." instead.
  • "any other string" - use "any other string" instead.

Example usage

Here's an example of AceLocale-3.0 usage with this new system:

enUS.lua

local debug = false --@debug@ debug = true --@end-debug@ local L = LibStub("AceLocale-3.0"):NewLocale("MyAddon", "enUS", true, debug) --@localization(locale="enUS", format="lua_additive_table", same-key-is-true=true, handle-subnamespaces="concat")@

local L = LibStub("AceLocale-3.0"):NewLocale("MyAddon", "deDE") if not L then return end --@localization(locale="deDE", format="lua_additive_table", handle-subnamespaces="concat")@

You're probably wondering about the @debug@ statement, but that's so that in development, you pass in an argument into :NewLocale that makes it so nonexistent translations don't error.

The resultant code will look like this:

enUS.lua

local debug = false --[===[@debug@ debug = true --@end-debug@]===] local L = LibStub("AceLocale-3.0"):NewLocale("MyAddon", "enUS", true, debug) L["Hello, World!"] = true L["How are you today?"] = true L["AwesomeModule/Eat some pie"] = "Eat some pie"

deDE.lua

local L = LibStub("AceLocale-3.0"):NewLocale("MyAddon", "deDE") if not L then return end L["Hello, World!"] = "Hallo, Welt!" -- L["How are you today?"] = "" L["AwesomeModule/Eat some pie"] = "Geh Kuchen essen"