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

LocalizedReference.TableReference

LocalizedReference.TableEntryReference

LocalizedReference.FallbackState

LocalizedReference.IsEmpty

LocalizedReference.SetReference(TableReference, TableEntryReference)

LocalizedReference.ToString()

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

LocalizedReference.ForceUpdate()

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

LocalizedReference.Reset()

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:

• The first time the action is added to the event.
• The SelectedLocale changing.
• The Arguments changing.
• If the string is currently using a IGlobalVariable which supports IGlobalVariableValueChanged and it's value has changed.
• When RefreshString() is called.
• The TableReference or TableEntryReference changing.

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

TupleExtensions.IsValueTuple(Object)

TupleExtensions.GetValueTupleItemObjects(Object)

TupleExtensions.GetValueTupleItemObjectsFlattened(Object)