Home › Page › Localize

Localize

Inherits from SingletonScript.

Important:  Localize defaults to disabled.  To enable localization, open up the Localize.cs file and delete or comment out the “#define DO_NOT_LOCALIZE” line.

Localize is a singleton class that manages swapping between multiple translations of text at runtime.  Localize makes use of the intermediate classes LocalizedString and UnlocalizedString.

UghText makes use of Localize.

Localize is persistant.  It is not unloaded between scene loads.  Common practice is to place an instance of a GameObject with a Localize component in a loading scene before any text would be displayed.  Have a script register for the OnLanguageLoaded event.  When the OnLanguageLoaded event fires it is safe to advance to any scenes that display text.

Localize uses language files to form a key : value lookup table.  Language files are unicode text files in JSON format.  An editor tool exists to automatically generate a language file.  Use the “Custom->Localization->Produce Localization Template” menu option.  This process can take several minutes.  The tool will scour all prefabs in the AssetDatabase, all objects in scenes in the build settings, and all C# files in the AssetDatabase.  When processing a prefab or scene object, the tool will use C# reflection to grab values from any instances of LocalizedString encountered.  When processing C# files, the tool will search the text for calls to the “Localize.Get” function and grab the string literal inside the function call.  This process, while exhaustive, is not perfect.  Results should be monitored.

Localize will automatically load the default language file.  Then it will immediately attempt to load a new language file by searching through the languageAssets array for a matching Application.systemLanguage.

Some editor utilities exist under the “Custom->Localization->Inspect->” submenu.  These utilities were created to help localize a project that was not initially planned for localization.  The “Pull Strings” utility will attempt to output a list of string literals in all C# files that are not preceded with a “Localize.Get” or “UnlocalizedString.UnlocalizedStringMarker” function.  This process is not perfect, but helps to locate the majority of literals in the codebase.  The “Get Unmarked Class Strings” utility will use C# reflection to scour all prefabs in the AssetDatabase for script members of type string and output their location to a file.  This helps to identify string members of classes that might need to be refactored to LocalizedStrings.  The final tool is “Look for TextMeshes without UghTexts.”  This utility will look through all prefabs in the AssetDatabase and output a list of prefabs that have a TextMesh component but do not have an UghText component.  UghText uses LocalizedString while a TextMesh alone does not.

Variables
name type description
defaultLanguageFile TextAsset Link the default language file.
defaultLanguageURL string A URL to find the latest version of the default language. (Leave null if this is not used.)
languageAssets LanguageAsset[] Array of helper class that defines various translation files.
Events
name type description
OnLanguageLoaded void Called when a valid language file has been loaded.
Functions
name type description
LoadDefaultLanguage void Cause the default language to be loaded.
LoadLanguageAsset void Cause the specified language to be loaded.
UseLocalizedLanguage void Cause the language at the specified URL to be loaded.
Get string Returns a localized version of the given string.
GetURL string Given a key, returns a properly formatted file or web address for a localized asset.
GetDynamicKeys KeyCode[] Given a key event name, returns an array of localized KeyCodes.

_

Using Localize in Script

public void LoadDefaultLanguage ()

This function causes Localize to load and use the default language for retrieving translated text.  This function is called automatically during the Awake event before attempting to load any other languages.

public void LoadLanguageAsset(LanguageAsset asset)

Given a LanguageAsset, this function will load and use the specified file for retrieving translated text.  This function is called automatically during the Awake event.  If the LanguageAsset holds both a valid reference name and URL, this function will first load the resource and then attempt to download the language at the URL.

public void UseLocalizedLanguage(string url)

Given the URL to a language file, this function will attempt to download and use the language file for retrieving translated text.

public static string Get(string key)

Given a key, this function will retrieve and return translated text.  Keys are usually a full string in the default language.  This is the primary function used for retrieving translated text.

public static string GetURL(string key)

Given a key, this function will retrieve and return a properly formatted local path or web URL.  This function can be used retrieve the location of localized assets.

public static KeyCode[] GetDynamicKeys(string keyEvent)

Given a key event, this function will retrieve an array of KeyCodes.  This function can be used to localize user input.