Localization Lib

From WoWWiki

Contents 1 Summary 2 Features 3 Directions For Use By Player 4 Directions For Use By Another Addon 4.1 To use as an embeddable addon 4.2 To use as an addon library 4.3 Code Usage 4.3.1 Localization Files 4.3.2 Registration Before Requesting Strings 4.3.3 Requesting Strings

Summary

Embeddable addon for selecting a global localization for addons.

by AnduinLothar/KarlKFI

-Based on inspiration from Babylonian code by norganna and MentalPower.

-Brought to you without any real xml thanks to Iriel's VirtualFrames.

Available at WoWInterface.

WARNING: A bug was found in Auctioneer that caused the dropdown menu in this addon to malfunction. If you use Auctioneer, please make sure that you are using version 3.4.2 or greater.

Features

- Any addons that utilize this dynamic localization will use the user's prefered locale.

- If no string is found for the prefered locale it will use the client locale.

- If no string is found for the client locale it will use the addon default locale. (Addon default should be set to the most complete localization, usually the locale of the author.)

- Addons can request either a readable string or a string cooresponding to the user's client.

Directions For Use By Player

- Prefered language will be set to client locale the first time you play.

- Any addons that utilize this dynamic localization will use the specified locale.

- To choose another prefered language type '/locale' or use the Earth Feature Frame button, myAddOns Options button or CT Button to show the prompt.

Directions For Use By Another Addon

To use as an embeddable addon

- Put the Localization folder inside your Interface/AddOns/<YourAddonName>/ folder.

- Add Localization\Localization.xml to your toc or load it in your xml before your localization files.

- Add Localization to the OptionalDeps in your toc

To use as an addon library

- Put the Localization folder inside your Interface/AddOns/ folder.

- Add Localization to the Dependencies in your toc

Code Usage

Localization Files

• After the Localization addon has been loaded (by dependency or embedding) load your localizations.

  - The recommended localization format is to use one file for each locale named localization.<locale>.lua EX: localization.en.lua

  (Note: This is not required, but simplifies checking at-a-glance what locales are supported. You can use 2 or 4 character locales as needed.)

  - To register addon localizations by locale for use with Localization.GetString and Localization.GetClientString, use Localization.RegisterAddonStrings(locale, addon, stringTable, eraseOrig, protect)

  - To register addon localizations by locale for use as global strings, use Localization.RegisterGlobalAddonStrings(locale, addon, stringTable, eraseOrig, protect)

  'locale' is a four character string representing the locale of the current batch of strings. EX: "enUS", "enGB", "frFR", "deDE".

  'addon' is a string passed to this and most of the following functions. It must be identical to the AddonName as returned by arg1 of ADDON_LOADED for Load on Demand addons.

  'eraseOrig' is a boolean that if true will cause any previously registered strings for this locale/addon to be erased.

  'protect' is a boolean that will not allow this information to be deleted by RemoveUnusedLocales. For internal use only. Used to protect the language selection screen text.

EX (RegisterAddonStrings):

Localization.RegisterAddonStrings("enUS", "FriendsFacts", {

	Header		= "FriendsFacts";
	HeaderInfo	= "Records and displays friend level, class, location, pvpname, sex, race, and guild.";
	
	Enable		= "Enable FriendsFacts";
	EnableInfo	= "Show/Hide recorded info in the FriendsFrame";
	
	ShowPVPName	= "Show PVP Name";
	ShowPVPNameInfo	= "Show/Hide your friend's PVP Name. Only works after seeing them.";

	TradeCity	= "Trade - City";

})

EX (RegisterGlobalAddonStrings):

Localization.RegisterGlobalAddonStrings("enUS", "ChatScroll", {

	-- Binding Configuration
	BINDING_HEADER_CHATSCROLL_HEADER	= "Chat Scroll";
	BINDING_NAME_CHATSCROLL_TOP		= "Scroll To Top";
	
})

• The difference between the two above methods:

  - Strings registered with RegisterAddonStrings do not assign globals when the locale is changed, RegisterGlobalAddonStrings does.

  - RegisterGlobalAddonStrings assignment requires Localization.AssignAddonGlobalStrings(addon) to be called before the global strings can be used (or after VARIABLES_LOADED, ADDON_LOADED for Load on Demand addons).

  - RegisterGlobalAddonStrings assignments assist in the polution of the global namespace, RegisterAddonStrings assignments are stored only in a table and requested dynamicly.

  - RegisterGlobalAddonStrings assignment allows for use in Bindings.xml where a global string is required.

  - RegisterGlobalAddonStrings assignment allows for faster static lookup if it is required for addons that freqently request the same or multiple strings.

Registration Before Requesting Strings

• Then before using any of the localizations the addon default locale needs to be set using Localization.SetAddonDefault(addon, locale)

EX (SetAddonDefault):

Localization.SetAddonDefault("FriendsFacts", "enUS");

• Optionally, you can also set callback functions that will be executed after each time the prefered locale is changed using Localization.RegisterCallback(key, callback, silent)

  (Note: The key passed here should represent the addon and the action in name. However, it is not addon specific. Zero or more callbacks can be registered by any given addon, but they will all be called at relatively the same time in any unspecified order.)

  - 'silent' is a boolean to dissable text warnings of duplicate callback keys or nil callback functions. The second call would silently unregister the first call's callback:

-- Register Callback
Localization.RegisterCallback("FriendsFactsUpdate", Localization.UpdatePrompt)
-- Unregister Callback
Localization.RegisterCallback("FriendsFactsUpdate", nil, true)

Requesting Strings

• Once these registrations are finished you are ready to call Localization.GetString(addon, stringKey) to return a localized readable string.

  - GetString will first try to return the prefered localization of the string.

  - If it wasn't registered it will be substituted with the client localization of the string.

  - If it wasn't registered it will be substituted with the default localization of the string as determined by Localization.SetAddonDefault.

  - If at any point the requested "enGB" localization of the string isn't registered it will attempt to be replaced by the equivelent "enUS" localization of the string.

EX (GetString):

Localization.GetString("FriendsFacts", "Header")

• It is also recommended that you make an addon file local function for shorter calls.

  (Note: TEXT() used to be a WoW function required for returning strings. Now it is obsolete and merely returns the variable value, thus it is a candidate for replacement. Also, if you're lucky or updating old code you may already have it in your code.)

EX (TEXT):

local function TEXT(key) return Localization.GetString("FriendsFacts", key) end
Localization.GetString("FriendsFacts", "Header") == TEXT("Header")

• Any Strings registered by Localization.RegisterGlobalAddonStrings can be requested simply by using the key passed as a global variable after Localization.AssignAddonGlobalStrings(addon) has been called (or after VARIABLES_LOADED, ADDON_LOADED for Load on Demand addons).

EX (Global Strings):

<Bindings>
	<Binding name="CHATSCROLL_TOP" description="Scroll To Top" header="CHATSCROLL_HEADER">
		ChatScroll_ScrollToTop();
	</Binding>
</Bindings>

• To request a string in the client locale, use Localization.GetClientString(addon, stringKey).

EX (GetClientString):

local index, name = GetChannelName(2);
if ( Localization.GetClientString("FriendsFacts", "TradeCity") == name ) then ...