Home › Page › Localize


Revision for “Localize” created on 4 April, 2013 @ 14:06 [Autosave]

Inherits from SingletonScript. <strong>Important:</strong>  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 <a title="LocalizedString" href="http://ugh.graveck.com/wiki/localizedstring">LocalizedString</a> and <a title="UnlocalizedString" href="http://ugh.graveck.com/wiki/unlocalizedstring">UnlocalizedString</a>. <a title="UghText" href="http://ugh.graveck.com/wiki/ugh-scripting-reference/ughtext">UghText</a> 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-&gt;Localization-&gt;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 <a title="LocalizedString" href="http://ugh.graveck.com/wiki/ugh-scripting-reference/localizedstring">LocalizedString</a> 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 <a title="Unity Application doccumentation" href="http://docs.unity3d.com/Documentation/ScriptReference/Application-systemLanguage.html">Application.systemLanguage</a>. Some editor utilities exist under the "Custom-&gt;Localization-&gt;Inspect-&gt;" 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. [table caption="Variables" colwidth=20%|20%] name, type, description defaultLanguageFile,<a href="http://docs.unity3d.com/Documentation/Components/class-TextAsset.html">TextAsset</a>, 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. [/table] [table caption="Events" colwidth=20%|20%] name, type, description OnLanguageLoaded, void, Called when a valid language file has been loaded. [/table] [table caption="Functions" colwidth=20%|20%] 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, <a href="http://docs.unity3d.com/Documentation/ScriptReference/KeyCode.html">KeyCode</a>[], "Given a key event name, returns an array of localized KeyCodes." [/table] <strong>Using Localize in Script</strong> [sourcecode language="csharp"]public void LoadDefaultLanguage ()[/sourcecode] 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. [sourcecode language="csharp"]public void LoadLanguageAsset(LanguageAsset asset)[/sourcecode] 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. [sourcecode language="csharp"]public void UseLocalizedLanguage(string url)[/sourcecode] Given the URL to a language file, this function will attempt to download and use the language file for retrieving translated text. [sourcecode language="csharp"]public static string Get(string key)[/sourcecode] 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. [sourcecode language="csharp"]public static string GetURL(string key)[/sourcecode] 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. [sourcecode language="csharp"]public static KeyCode[] GetDynamicKeys(string keyEvent)[/sourcecode] Given a key event, this function will retrieve an array of KeyCodes.  This function can be used to localize user input.

OldNewDate CreatedAuthorActions
4 April, 2013 @ 14:06 [Autosave] admin
4 April, 2013 @ 14:05 admin
2 April, 2013 @ 21:01 admin
2 April, 2013 @ 20:33 admin
2 April, 2013 @ 20:29 admin
2 April, 2013 @ 20:29 admin
2 April, 2013 @ 20:25 admin
2 April, 2013 @ 20:21 admin
2 April, 2013 @ 20:15 admin
2 April, 2013 @ 20:13 admin
2 April, 2013 @ 20:11 admin
2 April, 2013 @ 20:09 admin
2 April, 2013 @ 20:07 admin
2 April, 2013 @ 19:38 admin
2 April, 2013 @ 19:22 admin
2 April, 2013 @ 19:21 admin
2 April, 2013 @ 17:10 admin
2 April, 2013 @ 17:10 admin