Ace3

API / AceLocale-3.0

AceLocale-3.0 manages localization in addons, allowing for multiple locale to be registered with fallback to the base locale for untranslated strings.


AceLocale:GetLocale(application, silent)

Returns localizations for the current locale (or default locale if translations are missing).
Errors if nothing is registered (spank developer, not just a missing translation)

Parameters

application
Unique name of addon / module
silent
If true, the locale is optional, silently return nil if it's not found (defaults to false, optional)

Return value

The locale table for the current language.


AceLocale:NewLocale(application, locale[, isDefault[, silent]])

Register a new locale (or extend an existing one) for the specified application.
:NewLocale will return a table you can fill your locale into, or nil if the locale isn't needed for the players game locale.

Parameters

application
Unique name of addon / module
locale
Name of the locale to register, e.g. "enUS", "deDE", etc.
isDefault
If this is the default locale being registered (your addon is written in this language, generally enUS)
silent
If true, the locale will not issue warnings for missing keys. Must be set on the first locale registered. If set to "raw", nils will be returned for unknown keys (no metatable used).

Return value

Locale Table to add localizations to, or nil if the current locale is not required.

Usage

-- enUS.lua
local L = LibStub("AceLocale-3.0"):NewLocale("TestLocale", "enUS", true)
L["string1"] = true

-- deDE.lua
local L = LibStub("AceLocale-3.0"):NewLocale("TestLocale", "deDE")
if not L then return end
L["string1"] = "Zeichenkette1"


You must login to post a comment. Don't have an account? Register to get one!

  • 2 comments
  • Avatar of mikk mikk Mar 03, 2011 at 16:31 UTC - 1 like

    Note that you can call :NewLocale() more than once to get hold of an already-existing locale. This is useful for using a single translation table for e.g. modules of an addon.

  • Avatar of JackTripper JackTripper Dec 27, 2010 at 15:15 UTC - 0 likes

    Example of defining the translations

    enUS.lua

    --localization file for english/United States
    local L = LibStub("AceLocale-3.0"):NewLocale("PaladinHelper", "enUS", true)
    
    L["i'm cursed"] = true
    L["SpellTooltipFlashOFLight"] = "A quick expensive heal"
    

    One locale file needs to be the "default" locale. In this case when we create the enUS locale, it is indicated to be the default with the 3rd true parameter.
    If the string does not require translation, it can be set to true.

    deDE.lua

    --localization file for german/Germany
    local L = LibStub("AceLocale-3.0"):NewLocale("PaladinHelper", "deDE")
    
    L["i'm cursed"] = "Ich bin verflucht"
    L["SpellTooltipFlashOFLight"] = "Eine schnelle teuer heilen"
    

    arKW.lua

    --localization file for arabic/Kuwait
    local L = LibStub("AceLocale-3.0"):NewLocale("PaladinHelper", "arKW")
    
    L["i'm cursed"] = "ابن ملعون"
    L["SpellTooltipFlashOFLight"] = "وتكلفة علاج سريع"
    

    Place all these files in a \Locale sub-folder, along with an xml file that references them:

    Locales.xml

    <Ui xmlns="http://www.blizzard.com/wow/ui/" 
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="http://www.blizzard.com/wow/ui/
    ..\FrameXML\UI.xsd">
        <Script file="enUS.lua"/>
        <Script file="deDE.lua"/>
        <Script file="arKW.lua"/>
    </Ui>
    

    And reference the Locales.xml file from your toc file:

    PaladinHelper.toc

    ## Interface: 40000
    ## Title: Paladin Helper
    
    ...
    
    --Embedded libraries
    embeds.xml
    
    --Locale Translations
    Locales\Locales.xml
    
    Core.lua
    

    When you wish to access the translated strings from your code, you access the existing locale info:

    Core.lua

    local L = LibStub("AceLocale-3.0"):GetLocale("PaladinHelper")
    
    button1 = L["i'm cursed"]
    button2 =  L["SpellTooltipFlashOFLight"]
    
  • 2 comments