Scripting

This documentation describes the most common ways to interact with the Localization System via C# scripts.

You can download additional scripting examples from the package manager window, in the Localization package’s Samples section.

LocalizedString

A LocalizedString accesses specific entries from within a String Table.

You can use the LocalizedString in a user script. It serializes and displays its own editor, which you can use to select the table and table entry, and edit the localized values inline, without opening the Tables window.

The LocalizedString editor in Unity.

The LocalizedString provides a StringChanged event. The script calls the event whenever the selected Locale changes. This makes your code simpler and more efficient, because the script only calls it when it needs to update the LocalizedString.


public class LocalizedStringWithEvents : MonoBehaviour
{
    public LocalizedString myString;

    string localizedText;

    /// <summary>
    /// Register a ChangeHandler. This is called whenever the string needs to be updated.
    /// </summary>
    void OnEnable()
    {
        myString.StringChanged += UpdateString;
    }

    void OnDisable()
    {
        myString.StringChanged -= UpdateString;
    }

    void UpdateString(string s)
    {
        localizedText = s;
    }

    void OnGUI()
    {
        EditorGUILayout.LabelField(localizedText);
    }
}

Dynamic Strings

Sometimes you might need to update a localized string, such as when using Smart Strings or String.Format with arguments that have since changed. Calling GetLocalizedString with the arguments always updates the string. When you use the StringChanged event, you can use the RefreshString function to request an update, and the Arguments property to configure the arguments that format the string.


/// <summary>
/// This example expects a Smart String with a named placeholder of `TimeNow`, such as "The time now is {TimeNow}".
/// </summary>
public class LocalizedStringSmart : MonoBehaviour
{
    public LocalizedString myString;

    string localizedText;

    public float TimeNow => Time.time;

    /// <summary>
    /// Register a ChangeHandler. This is called whenever we need to update our string.
    /// </summary>
    void OnEnable()
    {
        myString.Arguments = new[] { this };
        myString.StringChanged += UpdateString;
    }

    void OnDisable()
    {
        myString.StringChanged -= UpdateString;
    }

    void UpdateString(string s)
    {
        localizedText = s;
    }

    void OnGUI()
    {
        // This calls UpdateString immediately (if the table is loaded) or when the table is available.
        myString.RefreshString();
        GUILayout.Label(localizedText);
    }
}

LocalizedAsset

LocalizedAsset is a generic class that accesses localized versions of Unity assets from within an Asset Table.

You can use the LocalizedAsset in a user script. It serializes and displays its own editor, which you can use to select the table and table entry, and edit the localized values inline, without opening the Tables window.

The LocalizedAsset editor in Unity.

The LocalizedString provides an AssetChanged event. The script calls the event whenever a new localized asset is available, such as when the game language changes. This makes your code simpler and more efficient, because the script only calls it when it needs to update the LocalizedAsset.

To use a LocalizedAsset, you need to create a concrete version of the class and mark it as Serializable.

For example, to support localizing font assets, you could define the following class:

using System;
using UnityEngine;
using UnityEngine.Localization;

[Serializable]
public class LocalizedFont : LocalizedAsset<Font> {}

In this example, you can now add LocalizedFont to a script, and LocalizedString will call the AssetChanged event when a localized Font asset is available.

The following Unity assets are already supported:

Type	Class
AudioClip	`LocalizedAudioClip`
GameObject/Prefab	`LocalizedGameObject`
Material	`LocalizedMaterial`
Sprite	`LocalizedSprite`
Texture	`LocalizedTexture`

TableReference

Use the TableReference struct to reference an Asset Table or String Table. To reference a table, you can use either the table's name or its unique GUID. It is usually safer to use the GUID, because you might decide to change the table name in future, which would require you to manually update your references, but the GUID always stays the same.

TableEntryReference

Use the TableEntryReference struct to reference an entry in an Asset Table or String Table. To reference a table, you can use either the table entry's name or its unique Key ID, an unsigned long integer. It is usually safer to use the Key ID, because you might decide to change the table entry name in future, which would require you to manually update your references, but the Key ID always stays the same.

Using AsyncOperationHandle

Unity does not hold all localized assets in memory ready for use. Instead, it loads them on demand when it needs them, and unloads them when it no longer needs them. Because of this, localized Assets might not be immediately available, and Unity might need to load them from disk or fetch them from a server. To facilitate this, Unity uses the AsyncOperationHandle as an interface to all requests. When an Asset is not immediately available, the localization system returns an AsyncOperationHandle. When the operation has finished, the AsyncOperationHandle provides a Completed event to notify Unity. It calls this during LateUpdate. If the request has already completed (for example, when the requested data is already loaded from a previous request, or during preloading), you can check the IsDone property for immediate access via the Result property. Alternatively, the Completed event still occurs in LateUpdate, allowing for all code to follow the same path. You can also yield on an AsyncOperationHandle inside a coroutine.

To force an operation to complete on the main thread, call WaitForCompletion. See Synchronous Workflow for further details.

This example demonstrates how to create a way for the person playing a game to select the language (defined in the Localization system by Locale) they want to use in the game. To add a UI dropdown menu to the Scene, go to GameObject > UI > Dropdown, and attach the following script:


using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.Localization.Settings;
using UnityEngine.UI;

public class LocaleDropdown : MonoBehaviour
{
    public Dropdown dropdown;

    IEnumerator Start()
    {
        // Wait for the localization system to initialize
        yield return LocalizationSettings.InitializationOperation;

        // Generate list of available Locales
        var options = new List<Dropdown.OptionData>();
        int selected = 0;
        for (int i = 0; i < LocalizationSettings.AvailableLocales.Locales.Count; ++i)
        {
            var locale = LocalizationSettings.AvailableLocales.Locales[i];
            if (LocalizationSettings.SelectedLocale == locale)
                selected = i;
            options.Add(new Dropdown.OptionData(locale.name));
        }
        dropdown.options = options;

        dropdown.value = selected;
        dropdown.onValueChanged.AddListener(LocaleSelected);
    }

    static void LocaleSelected(int index)
    {
        LocalizationSettings.SelectedLocale = LocalizationSettings.AvailableLocales.Locales[index];
    }
}

You can see a more advanced version of this script in the Localization package samples.

Editor

Use the Editor scripting class LocalizationEditorSettings to make changes to Localization assets.

The following example shows how to update a collection by adding support for a new Locale.


// Create the new Locale
var locale = Locale.CreateLocale(SystemLanguage.Spanish);
AssetDatabase.CreateAsset(locale, "Assets/Spanish.asset");
LocalizationEditorSettings.AddLocale(locale);

// Get the collection
var collection = LocalizationEditorSettings.GetStringTableCollection("My String Table");

// Add a new table
var newTable = collection.AddNewTable(locale.Identifier) as StringTable;

// Add a new entry to the table
var entry = newTable.AddEntry("Hello", "Hola");

// Add some metadata
entry.AddMetadata(new Comment { CommentText = "This is a comment"});

// We need to mark the table and shared table data entry as we have made changes
EditorUtility.SetDirty(newTable);
EditorUtility.SetDirty(newTable.SharedData);