Class LocalizedString

Provides a way to reference a StringTableEntry inside of a specific StringTable and request the localized string.

Inheritance
Object
LocalizedReference
LocalizedString
Inherited Members
Namespace: UnityEngine.Localization
Syntax
public class LocalizedString : LocalizedReference

Constructors

LocalizedString()

Initializes and returns an empty instance of a LocalizedString.

Declaration
public LocalizedString()

LocalizedString(TableReference, TableEntryReference)

Initializes and returns an instance of a LocalizedString.

Declaration
public LocalizedString(TableReference tableReference, TableEntryReference entryReference)
Parameters
Type Name Description
TableReference tableReference

Reference to the String Table Collection. This can either be the name of the collection as a string or the Collection Guid as a System.Guid.
TableEntryReference entryReference

Reference to the String Table Collection entry. This can either be the name of the Key as a string or the long Key Id.
Examples

This example shows the different ways to construct a LocalizedString.

public LocalizedString usingNames = new LocalizedString("My String Table", "My Game Text");

public LocalizedString usingTableNameAndEntryId = new LocalizedString("My String Table", 4324324541);

public LocalizedString usingTableGuidAndEntryId = new LocalizedString(new System.Guid("6e79ded14bc9e0a4d9bf2b8aac246bfe"), 323453434);

public LocalizedString usingTableGuidAndEntryName = new LocalizedString(new System.Guid("6e79ded14bc9e0a4d9bf2b8aac246bfe"), "Start Game");

This example shows how a LocalizedString could be set up in the Editor. By using the Guid and Id the table and entry references will not be lost if the table collection name or entry name was to be changed. Note: The performance benefits to using a Guid and Id are negligible.

public LocalizedString GenerateLocalizedStringInEditor()
{
    // The main advantage to using a table Guid and entry Id is that references will not be lost when changes are made to the Table name or Entry name.
    var collection = LocalizationEditorSettings.GetStringTableCollection("My String Table");
    var entry = collection.SharedData.GetEntry("Start Game");
    return new LocalizedString(collection.SharedData.TableCollectionNameGuid, entry.Id);
}

Properties

Arguments

Arguments that will be passed through to Smart Format. These arguments are not serialized and will need to be set at runtime.

Declaration
public IList<object> Arguments { get; set; }
Property Value
Type Description
IList<Object>

CurrentLoadingOperation

The current loading operation for the string when using StringChanged or null if one is not available. A string may not be immediately available, such as when loading the StringTable asset, so all string operations are wrapped with an . See also RefreshString()

Declaration
public AsyncOperationHandle<LocalizedDatabase<StringTable, StringTableEntry>.TableEntryResult>? CurrentLoadingOperation { get; }
Property Value
Type Description
Nullable<AsyncOperationHandle<LocalizedDatabase.TableEntryResult<>>>

HasChangeHandler

Returns true if StringChanged has any subscribers.

Declaration
public bool HasChangeHandler { get; }
Property Value
Type Description
Boolean

Methods

ForceUpdate()

Declaration
protected override void ForceUpdate()
Overrides

GetLocalizedString()

Provides a translated string from a StringTable with the TableReference and the the translated string that matches TableEntryReference.

Declaration
public AsyncOperationHandle<string> GetLocalizedString()
Returns
Type Description
AsyncOperationHandle<String>

Returns the loading operation for the request.
Remarks

The Completed event provides a notification once the operation has finished and the string has been found or an error has occurred. A string table may have already been loaded during a previous operation or when using Preload mode. Check the property to see if the string table has already been loaded and the translated string is immediately available. See Async operation handling for further details.

Examples

This example shows how GetLocalizedString() can be used to request an updated string when the SelectedLocale changes.

public class LocalizedStringGetExample : MonoBehaviour
{
public Text myText;

public LocalizedString myString = new LocalizedString
{
    TableReference = "My String Table",
    TableEntryReference = "My Game Text"
};

void OnEnable()
{
    LocalizationSettings.SelectedLocaleChanged += LocaleChanged;
    LoadString();
}

void OnDisable()
{
    LocalizationSettings.SelectedLocaleChanged -= LocaleChanged;
}

void LocaleChanged(Locale locale)
{
    LoadString();
}

void LoadString()
{
    var operation = myString.GetLocalizedString();
    UpdateString(operation);
}

void UpdateString(AsyncOperationHandle<string> value)
{
    if (!value.IsDone)
    {
        // Defer the callback until the operation is finished
        value.Completed += UpdateString;
        return;
    }

    myText.text = value.Result;
}
}

GetLocalizedString(IList<Object>)

Provides a translated string from a StringTable with the TableReference and the the translated string that matches TableEntryReference.

Declaration
public AsyncOperationHandle<string> GetLocalizedString(IList<object> arguments)
Parameters
Type Name Description
IList<Object> arguments

The arguments to pass into the Smart String formatter or String.Format.
Returns
Type Description
AsyncOperationHandle<String>

Returns the loading operation for the request.

GetLocalizedString(Object[])

Provides a translated string from a StringTable with the TableReference and the the translated string that matches TableEntryReference.

Declaration
public AsyncOperationHandle<string> GetLocalizedString(params object[] arguments)
Parameters
Type Name Description
Object[] arguments

The arguments to pass into the Smart String formatter or String.Format.
Returns
Type Description
AsyncOperationHandle<String>

Returns the loading operation for the request.

RefreshString()

Provides a way to force a refresh of the string when using StringChanged.

Declaration
public bool RefreshString()
Returns
Type Description
Boolean

Returns true if a new refresh could be requested or false if it could not, such as when CurrentLoadingOperation is still loading.
Remarks

This will only force the refresh if there is currently no active CurrentLoadingOperation, if one is still being executed then it will be ignored and false will be returned. If a string is not static and will change during game play, such as when using format arguments, then this can be used to force the string to update itself.

You may wish to call this if the values inside of the Arguments list have changed or you wish to force all StringChanged subscribers to update. Note if setting the Arguments with a new list value then you do not need to call this as it will be called by the Arguments set method automatically.

Examples

This example shows how the string can be refreshed, such as when showing dynamic values like the current time.

/// <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);
}
}

Reset()

Declaration
protected override void Reset()
Overrides

Events

StringChanged

Provides a callback that will be invoked when the translated string has changed.

Declaration
public event LocalizedString.ChangeHandler StringChanged
Event Type
Type Description
LocalizedString.ChangeHandler
Remarks

The following events will trigger an update:

When the first LocalizedString.ChangeHandler is added, a loading operation (see CurrentLoadingOperation) automatically starts. When the loading operation is completed, the localized string value is sent to the subscriber. If you add additional subscribers after loading has completed, they are also sent the latest localized string value. This ensures that a subscriber will always have the correct localized value regardless of when it was added.

Examples

This example shows how the StringChanged event can be used to trigger updates to a string.

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);
}
}

Extension Methods