Documentation

CGLocalization User Manual (1.1)

Click here to access the new site in construction for documentation

CGLocalization is a simple and robust localization system for localizing your project in an easy way. It ships with an intuitive editor window to aid you in the creation of the languages that your project is going to support.

Last Edit Date: 2020-01-31


How to open the Editor Window

To open the editor window go to Window > CGLocalization > Editor


The CGLocalization window opened with the asset used in its translation


How it works?

For localizing your project two assets are required:
  • LocalizationAsset: stores the languages.
  • LocalizationSettings: stores the LocalizationAsset used to localize your project and other settings. Only one instance per project is required.

Localization Settings

When the CGLocalization package is imported to your project, a LocalizationSettings asset is included in the Assets/CGLocalization/Resources/CGLocalization folder. That settings asset is available in the Localization Settings window:


The Localization Settings window

Localization Asset

The localization asset used to localize your project. Initially is assigned the localization asset of the Localization Example (Assets/CGLocalization/Examples/Localization Example.asset). Is recommended to create your own Localization Asset and assign it in this property.

Test Language

If non empty, the language name or locale that you type in this text field, will be used when playing the project in the Editor.

Remember Current Language

If enabled, every time the current language is changed, the name is saved in the PlayerPrefs . Later, when the tool is started again, the current language is restored using that saved name.
If disabled, you must save/load the Localization.Instance.currentLanguageName property manually.

Creating a Localization Asset

To create a new Localization asset there are various ways:
  1. Open the CGLocalization window. If you have selected a Localization asset in the Project View it will be opened, otherwise a message in the CGLocalization Editor window prompts you to click the Create button. Click the button and a dialog box prompts you for the name and location of the Localization asset being created. See next figure:


    The Create new Localization asset button in the window

  2. Select the Assets > Create > Localization menu item in the toolbar.
  3. Open the Welcome window (Window > CGLocalization > Welcome Screen) and click the Create button.


    The Create new Localization asset button in the Welcome window


Languages

Adding Languages

CGLocalization allow you to add all ISO 639-1 languages. The locales with their code and regional identifiers are listed in the Assets/CGLocalization/Resources/CGLocalization/Locales.txt
To add a language, click the Add Language button in the top-left corner and click the language you want to add.

NOTE: You can search by name or locale code.

Custom Languages

Custom languages can be added in two ways:
  1. Add the locale with the code and regional identifier at the end of the Assets/CGLocalization/Resources/CGLocalization/Locales.txt file. (Please read the documentation at the top of the file to use the correct format and avoid errors)
  2. Type your language name in the search text field of the Add Language window. If the typed name is not found, an Add Custom button appears. See next figure:

    NOTE: If you add a custom language in this way, it will not have a locale code. So that, if you want to use this language at runtime, you have to change the language using only the name.

Languages Window

To access to the Languages window click the dropdown menu in the toolbar. The next figure show the dropdown and the window parts numbered:


The Languages window

These are the parts of the window:
  1. The check mark indicates the selected/editing language
  2. Drag button for reorder the languages
  3. Name (The Default Language is bold and italic)
  4. Locale
  5. Options button
NOTE: To select/edit a language just click a name.

Language Options

For each language an Options button is available. The next figure show the available options:


The Spanish language options

Set as Default

The default language, is used when your Localization asset do not contains the end user's system language and the tool is loading the Initial Language. It is also used to preview the localized behaviours in your current open scene while not in runtime.

Sort Keys by Name

All keys, in all languages, inside the editing asset, are sorted by name. (NOTE: This option will be moved out from this window in a future release because is shared for all the languages)
Delete the language. (If the language is the Default, then the first language in the list is assigned as the default)

Export String Values

Export all keys of String type into a file.

NOTE: Select your preferred file format in the Import/Export File Type dropdown in the Settings menu. The supported formats are XML and TXT.


The Import/Export file type option

Let's add some text to a String key and export a simple English language to see how the file formats are exported:

Export to XML

The string values exported to the xml format

Export to TXT

The string values exported to the text format

NOTE: The generated .txt file has the key_name=key_value format

Import String Values

A dialog box prompts you for choose the file and automatically, all the values of the keys that have the same name of the keys in the file are replaced. Check the console in case of errors while importing.

Initial Language

The first time your project runs, in the editor or another platform, the localization tool try to load the end user's system language provided by Application.systemLanguage

These are the steps used to load the initial language:

  1. If you have checked the Remember Current Language in the Localization Settings window, the tool check if exist a saved language name and that one is used. If the option is not checked, nor a language name was saved, the process continue.
  2. If any language name is an exact match of the Application.systemLanguage , then that one is used.
  3. If no exact match found, then the first variant is used. (For this case is recommended to reorder your languages in the Languages Window)
  4. If the exact match nor a variant is found, then the Default Language is used.

Keys

Adding keys

To add keys just click one of the next buttons in the toolbar:


Five common key types added from the toolbar

Removing Keys

To remove a key, just click in the Minus button at the right of each key.

Reordering Keys

To reorder the keys just click the left reorder button and drag the key up or down.


       NewKey4 moved to the top

Note that while you are searching a key by name or type, reordering is not supported.


Searching by Audio type. Reorder buttons are disabled.

Editing Keys in a Separated Window

The Edit Key window is a helper window for speed up the translation inside the Unity editor. In this window you can edit all the values of one key, for each language in your localization asset.
To open the Edit Key window just click the pencil button at the right of the key. The button becomes green to indicate the key is being edited in the window. See the next figure:


The Edit Key window opened with the MainMenu/Options key


Generate a Script of Constants

To generate a script of constants to be used at compile time, click the button in the toolbar and the next auxiliary window will appear:


The Generate Script of Constants window

Window Properties

Namespace

The namespace of the generated class.

Generate Constants by

Generate the constants by Id or Name?

Generate a Class per Type

If checked, a subclass per key type is generated. 

// 'Generated by Id' and 'Generate a Class per Type' checked 
public class LocalizationConsts
{
    public class String
    {
        public const int NewKey177 = 177;
    }

    public class Audio
    {
        public const int NewKey178 = 178;
    }

    public class Texture
    {
        public const int NewKey179 = 179;
    }

    public class Sprite
    {
        public const int NewKey180 = 180;
    }

    public class Prefab
    {
        public const int NewKey181 = 181;
    }
}


// 'Generated by Id' and 'Generate a Class per Type' unchecked 
public class LocalizationConsts
{
    public const int NewKey177 = 177;
    public const int NewKey178 = 178;
    public const int NewKey179 = 179;
    public const int NewKey180 = 180;
    public const int NewKey181 = 181;
}

NOTES:
  • Do not start key names with numbers because you will get an 'Unexpected symbol' compilation error.
  • All the characters in the name of a key that are not letters or numbers are converted to a _ character.
  • A name of a key cannot be the same of the key type.
    For example, a key of Sprite type cannot have the name 'Sprite' because this result in a compile time error: 'Member names cannot be the same as their enclosing type'.

Usage of the Constants

Now, instead of get the value of a key using a name or an identifier like in the next code: 

void Start()
{
    string value = Localization.GetString("NewKey177");
    Debug.Log(value);
}
You can simply avoid runtime errors by using the generated LocalizationConsts class: 

void Start()
{
    string value = Localization.GetString(LocalizationConsts.NewKey177);
    Debug.Log(value);
}

The SelectKeyDropdown Attribute

If you prefer, instead of generating a script of constants, you can use the SelectKeyDropdown attribute to select the identifier or the name of a key in the Inspector using a dropdown. This attribute can be used in conjunction with the SelectKeyType attribute to limit the selection of the key types.

Let's see next example script: 


using UnityEngine;
using CGLocalization;

public class Test : MonoBehaviour
{
    // select a key by id and must be a String key
    [SelectKeyDropdown, SelectKeyType(KeyType.String)]
    public int keyId;
 
    // select a key by name, can be any key type
    [SelectKeyDropdown]
    public string keyName;

    // select a key by id and must be an Audio key
    [SelectKeyDropdown, SelectKeyType(KeyType.Audio)]
    public int audioKey;

    // the attribute is only used with integers and strings
    [SelectKeyDropdown]
    public float key;
}

This is the example script is attached to a GameObject in the Inspector:

To select a key just click a dropdown. If the variable also have the SelectKeyType attribute the available keys are limited to the specified type. See the next figure:


Localized Behaviours

Localized behaviours are used to change a value in a component based on a key assigned in the Inspector.

How to Add a Localized Behaviour

To add Localized Behaviours to your GameObjects go to Components > Scripts > CGLocalization

After you had added a localized behaviour to your game object a small blue world icon is shown at the right of the name of the game object in the Hierarchy view.


The blue world icon means that the Text gameobject contains a LocalizedBehaviour

The next step is to pick up a key name in the LocalizedBehaviour inspector. In this case we added a LocalizedUIText component, so that we have to pick a key of String type.


Picking up a String Key

Note: Use / characters in key names to group keys and keep a clean popup when picking up a key.


Main menu keys grouped


The popup organized by grouping

Creating a new Localized Behaviour

To create a new localized behaviour you must to extend your class from the Localized Behavior class.

Let's create a localized font script for a text component.

Create a new script and name it LocalizedFont.cs. Copy and paste the next code and read the comments: 


using UnityEngine;
using UnityEngine.UI;
using CGLocalization;

[SelectKeyType(KeyType.Object)] // Limit the dropdown menu to pick up only a key with an Object type
[RequireComponent(typeof(Text)] // Require the Text component
public class LocalizedFont : LocalizedBehaviour
{
    Text m_text;
 
    // The AssignObject method is invoked every time the current language is changed in play mode
    // and every time a value is changed in the default language in the CGLocalization editor window.
    // If you need to assign strings values override the AssignString(string) method. 
    protected override void AssignObject(Object obj)
    {
        if (!m_text)
            m_text = GetComponent<Text>();

        m_text.font = obj as Font; // assign the obj as a font 
    }
}

Now to add the font key follow the next steps:

  1. Import three font files to your project.
  2. Go to Window > CGLocalization > Welcome Screen and click the Localization Example localization asset to open it.

  3. Click the Add Object Key button in the toolbar to add the Object key and name it Font.

  4. Now click the Edit in Window button to add a font per language easily.
  5. Add the fonts like in the next image:

It's time to assign our created LocalizeFont script to a GameObject with a Text component attached to change the font based on the current language.

Open up the Localized Behaviours scene located at Assets/CGLocalization/Examples/Scenes/Localized Behaviours.unity and select the Text GameObject of the Button - Play in the Hierarchy. See next image:

Now add the LocalizeFont script and select the Font key. The Inspector looks like this next image:

Now hit Play!!! Change the language using the three button (English, Español and Français) in the middle of the Game View and observe how the font in the Play text is changed

English (Arial)
Spanish (Consola)
French (Gothic)

Change the Current Language at Runtime

To access or change the current language at runtime, assign a name or locale in one of the next properties: 


Localization.Instance.currentLanguageName
Localization.Instance.currentLanguageLocale

Example:


// change the language to Spanish by name
Localization.Instance.currentLanguageName = "Spanish";
// change the language to Spanish by locale
Localization.Instance.currentLanguageLocale = "es";
// change the language to Spanish (United States) by locale and region
Localization.Instance.currentLanguageLocale = "es_US"; // en-US is also allowed

Assigning Variants

If you assign a language name or locale that is not included in your localization asset, the tool will use the first variant that match the name. (For this case is recommended to reorder your languages in the Languages Window)

Let's assume that we have the next languages in our localization asset:

  • English
  • English (United States)
  • French (Haiti)
  • French

Localization.Instance.currentLanguageName = "English (Canada)"; // assigns 'English'
Localization.Instance.currentLanguageName = "French (France)";  // assigns 'French (Haiti)'
Localization.Instance.currentLanguageName = "Spanish";          // do not change the language

Get Values at Runtime

Values can be obtained using the name or the identifier of a key.


string     stringValue  = Localization.Instance.GetString("StringKeyName");
AudioClip  audioValue   = Localization.Instance.GetAudio("AudioKeyName");
Sprite     spriteValue  = Localization.Instance.GetSprite("SpriteKeyName");
Texture    textureValue = Localization.Instance.GetTexture("TextureKeyName");
GameObject prefabValue  = Localization.Instance.GetPrefab("PrefabKeyName");
Object     objectValue  = Localization.Instance.GetObject(125);

TIP: The above methods internally call helper methods to validate that a key is not null and has the correct type. If you know the type of a key beforehand, you can invoke the GetKey() method instead, check that the key is not null, and use the value (key.stringValue or key.objectValue). This is the way the localized behaviours works.


Check if a given Language is Supported 


bool IsSupported(SystemLanguage language)
bool IsSupported(string languageName)
bool IsSupportedLocale(string locale)

NOTE: The above methods do an exact match searching.