Class LocalizedDatabase<TTable, TEntry>

Provides common functionality for both string and asset table fetching.

Inheritance

Object

LocalizedDatabase<TTable, TEntry>

LocalizedAssetDatabase

LocalizedStringDatabase

Namespace: UnityEngine.Localization.Settings

Syntax

[Serializable]
public abstract class LocalizedDatabase<TTable, TEntry> : IPreloadRequired, IReset, IDisposable where TTable : DetailedLocalizationTable<TEntry> where TEntry : TableEntry

Type Parameters

Name	Description
TTable
TEntry

Constructors

LocalizedDatabase()

Creates a new instance of the database.

Declaration

public LocalizedDatabase()

Properties

DefaultTable

The default table to use when no table collection name is provided.

Declaration

public virtual TableReference DefaultTable { get; set; }

Property Value

Type	Description
TableReference

PreloadOperation

Preload operation. Loads all tables and their contents(when applicable) marked with the preload label for the selected locale.

Declaration

public AsyncOperationHandle PreloadOperation { get; }

Property Value

Type	Description
AsyncOperationHandle

Implements

IPreloadRequired.PreloadOperation

TablePostprocessor

Gets a notification when a table completes loading. This can be used to apply changes to a table at runtime, such as updating or creating new entries.

Declaration

public ITablePostprocessor TablePostprocessor { get; set; }

Property Value

Type	Description
ITablePostprocessor

Examples

This example demonstrates how to use the ITablePostprocessor to apply changes to a table after it has loaded but before it has been used. This can be beneficial when you wish to modify or add entries to a table, such as when supporting third-party content, for example modding.

[Serializable]
public class CustomTablePatcher : ITablePostprocessor
{
public void PostprocessTable(LocalizationTable table)
{
    Debug.Log($"Postprocess {table}");

    if (table is StringTable stringTable)
    {
        // Add a new value
        stringTable.AddEntry("some new entry", "localized value");

        // Update an old value
        var entry = stringTable.GetEntry("some existing value");
        if (entry != null)
        {
            entry.Value = "updated localized value";
        }
    }
    else if (table is AssetTable assetTable)
    {
        // Add a new value
        var entry = assetTable.AddEntry("my texture asset", null);
        entry.SetAssetOverride(Texture2D.whiteTexture);

        // Override an existing value
        var overrideEntry = assetTable.GetEntry("existing entry");
        if (overrideEntry != null)
        {
            var texture = new Texture2D(10, 10);
            overrideEntry.SetAssetOverride(texture);
        }
    }
}
}

public static class AssignCustomTablePatcherExample
{
[MenuItem("Localization Samples/Assign Custom table postprocessor")]
public static void AssignTablePostprocessor()
{
    // Create an instance of the table provider.
    var provider = new CustomTablePatcher();

    // A table postprocessor can be assigned to each database or the same can be shared between both.
    var settings = LocalizationEditorSettings.ActiveLocalizationSettings;
    settings.GetStringDatabase().TablePostprocessor = provider;
    settings.GetAssetDatabase().TablePostprocessor = provider;

    // Set dirty so the changes are saved.
    EditorUtility.SetDirty(settings);
}
}

TableProvider

Called when attempting to load a table, can be used to override the default table loading through Addressables in order to provide a custom table.

Declaration

public ITableProvider TableProvider { get; set; }

Property Value

Type	Description
ITableProvider

Examples

This example demonstrates how to use the ITableProvider to provide a custom String Table without using the Addressables system. This approach is particularly useful when you want to allow users to add third-party content, such as modding. The localization data could be loaded from an external file and then converted into a table at runtime.

[Serializable]
public class CustomTableProvider : ITableProvider
{
public string customTableCollectionName = "My Custom Table";

public AsyncOperationHandle<TTable> ProvideTableAsync<TTable>(string tableCollectionName, Locale locale) where TTable : LocalizationTable
{
    Debug.Log($"Requested {locale.LocaleName} {typeof(TTable).Name} with the name `{tableCollectionName}`.");

    // Provide a custom string table only with the name "My Custom Table".
    if (typeof(TTable) == typeof(StringTable) && tableCollectionName == customTableCollectionName)
    {
        // Create the table and its shared table data.
        var table = ScriptableObject.CreateInstance<StringTable>();
        table.SharedData = ScriptableObject.CreateInstance<SharedTableData>();
        table.SharedData.TableCollectionName = customTableCollectionName;
        table.LocaleIdentifier = locale.Identifier;

        // Add some values
        table.AddEntry("My Entry 1", "My localized value 1");
        table.AddEntry("My Entry 2", "My localized value 2");

        return Addressables.ResourceManager.CreateCompletedOperation(table as TTable, null);
    }

    // Fallback to default table loading.
    return default;
}
}

public static class AssignCustomTableProviderExample
{
[MenuItem("Localization Samples/Assign Custom table provider")]
public static void AssignTableProvider()
{
    // Create an instance of the table provider.
    var provider = new CustomTableProvider();

    // A provider can be assigned to each database or the same provider can be shared between both.
    var settings = LocalizationEditorSettings.ActiveLocalizationSettings;
    settings.GetStringDatabase().TableProvider = provider;
    settings.GetAssetDatabase().TableProvider = provider;

    // Set dirty so the changes are saved.
    EditorUtility.SetDirty(settings);
}
}

UseFallback

Should the fallback Locale be used when a translation could not be found?.

Declaration

public bool UseFallback { get; set; }

Property Value

Type	Description
Boolean

Methods

GetAllTables(Locale)

Returns all the tables available. This method is asynchronous and may not have an immediate result. Check IsDone to see if the tables are available. if it is false then you can use the Completed event to get a callback when it is finished, yield on the operation or call WaitForCompletion to force the operation to complete.```

Declaration

public virtual AsyncOperationHandle<IList<TTable>> GetAllTables(Locale locale = null)

Parameters

Type	Name	Description
Locale	locale	The Locale to load the table from, use null to default to cref="LocalizationSettings.SelectedLocale"/>.

Returns

Type	Description
AsyncOperationHandle<IList<TTable>>

GetDefaultTableAsync()

Returns the Default table. This method is asynchronous and may not have an immediate result. Check IsDone to see if the data is available, if it is false then you can use the Completed event to get a callback when it is finished, yield on the operation or call WaitForCompletion to force the operation to complete.

Declaration

public AsyncOperationHandle<TTable> GetDefaultTableAsync()

Returns

Type	Description
AsyncOperationHandle<TTable>

GetTable(TableReference, Locale)

Returns the named table. Uses WaitForCompletion to force the loading to complete synchronously. Please note that WaitForCompletion is not supported on WebGL.

Declaration

public virtual TTable GetTable(TableReference tableReference, Locale locale = null)

Parameters

Type	Name	Description
TableReference	tableReference	The table identifier. Can be either the name of the table or the table collection name Guid.
Locale	locale	The Locale to load the table from, use null to default to cref="LocalizationSettings.SelectedLocale"/>.

Returns

Type	Description
TTable

GetTableAsync(TableReference, Locale)

Returns the named table. This method is asynchronous and may not have an immediate result. Check IsDone to see if the data is available, if it is false then you can use the Completed event to get a callback when it is finished, yield on the operation or call WaitForCompletion to force the operation to complete.

Declaration

public virtual AsyncOperationHandle<TTable> GetTableAsync(TableReference tableReference, Locale locale = null)

Parameters

Type	Name	Description
TableReference	tableReference	The table identifier. Can be either the name of the table or the table collection name Guid.
Locale	locale	The Locale to load the table from, use null to default to SelectedLocale.

Returns

Type	Description
AsyncOperationHandle<TTable>

Remarks

Internally the following is performed when a table is requested:

GetTableEntry(TableReference, TableEntryReference, Locale, FallbackBehavior)

Returns the entry from the requested table. A table entry will contain the localized item and metadata. Uses WaitForCompletion to force the loading to complete synchronously. Please note that WaitForCompletion is not supported on WebGL.

Declaration

public virtual LocalizedDatabase<TTable, TEntry>.TableEntryResult GetTableEntry(TableReference tableReference, TableEntryReference tableEntryReference, Locale locale = null, FallbackBehavior fallbackBehavior = FallbackBehavior.UseProjectSettings)

Parameters

Type	Name	Description
TableReference	tableReference	The table identifier. Can be either the name of the table or the table collection name Guid.
TableEntryReference	tableEntryReference	A reference to the entry in the table.
Locale	locale	The Locale to load the table from. Null will use SelectedLocale.
FallbackBehavior	fallbackBehavior	A Enum which determines if a Fallback should be used when no value could be found for the Locale.

Returns

Type	Description
LocalizedDatabase.TableEntryResult<>	The table entry result which contains the table

GetTableEntryAsync(TableReference, TableEntryReference, Locale, FallbackBehavior)

Returns the entry from the requested table. A table entry will contain the localized item and metadata. This method is asynchronous and may not have an immediate result. Check IsDone to see if the data is available, if it is false then you can use the Completed event to get a callback when it is finished, yield on the operation or call WaitForCompletion to force the operation to complete. Once the Completed event has been called, during the next update, the internal operation will be returned to a pool so that it can be reused. If you do plan to keep hold of the handle after completion then you should call Acquire to prevent the operation being reused and Release(AsyncOperationHandle) to finally return the operation back to the pool.

Declaration

public virtual AsyncOperationHandle<LocalizedDatabase<TTable, TEntry>.TableEntryResult> GetTableEntryAsync(TableReference tableReference, TableEntryReference tableEntryReference, Locale locale = null, FallbackBehavior fallbackBehavior = FallbackBehavior.UseProjectSettings)

Parameters

Type	Name	Description
TableReference	tableReference	The table identifier. Can be either the name of the table or the table collection name Guid.
TableEntryReference	tableEntryReference	A reference to the entry in the table.
Locale	locale	The Locale to load the table from. Null will use SelectedLocale.
FallbackBehavior	fallbackBehavior	A Enum which determines if a Fallback should be used when no value could be found for the Locale.

Returns

Type	Description
AsyncOperationHandle<LocalizedDatabase.TableEntryResult<>>

Remarks

Internally the following is performed when an Entry is requested. First the table will be requested using GetTableAsync(TableReference, Locale). Once the table is loaded the entry will be extracted like so:

IsTableLoaded(TableReference, Locale)

Checks if the table is currently loaded or not.

Declaration

public virtual bool IsTableLoaded(TableReference tableReference, Locale locale = null)

Parameters

Type	Name	Description
TableReference	tableReference	The table identifier. Can be either the name of the table or the table collection name Guid.
Locale	locale	The Locale to load the table from, use null to default to cref="LocalizationSettings.SelectedLocale"/>.

Returns

Type	Description
Boolean

OnLocaleChanged(Locale)

Called before the LocaleChanged event is sent out in order to give the database a chance to prepare.

Declaration

public virtual void OnLocaleChanged(Locale locale)

Parameters

Type	Name	Description
Locale	locale

PreloadTables(IList<TableReference>, Locale)

Preloads the matching tables for the selected Locale. If the tables are AssetTable then their assets will also be loaded. Check IsDone to see if the data is available, if it is false then you can use the Completed event to get a callback when it is finished, yield on the operation or call WaitForCompletion to force the operation to complete.

Declaration

public AsyncOperationHandle PreloadTables(IList<TableReference> tableReferences, Locale locale = null)

Parameters

Type	Name	Description
IList<TableReference>	tableReferences	An IList of tableReferences to check for the string.
Locale	locale	The Locale to use instead of the default SelectedLocale

Returns

Type	Description
AsyncOperationHandle

Examples

This shows how to manually preload tables instead of marking them as Preload in the editor.

public class PreloadingSample : MonoBehaviour
{
IEnumerator Start()
{
    // Tables that are not marked as Preload can be manually preloaded.
    var preloadOperation = LocalizationSettings.StringDatabase.PreloadTables(new TableReference[] { "UI Text", "Game Text" });
    yield return preloadOperation;

    // Get some text from the table, this will be immediately available now the table has been preloaded
    var uiText = LocalizationSettings.StringDatabase.GetTableEntryAsync("UI Text", "Start_Game").Result;
    Debug.Log(uiText);
}
}

PreloadTables(TableReference, Locale)

Preloads the selected table. If the table is an AssetTable its assets will also be loaded. Check IsDone to see if the data is available, if it is false then you can use the Completed event to get a callback when it is finished, yield on the operation or call WaitForCompletion to force the operation to complete.

Declaration

public AsyncOperationHandle PreloadTables(TableReference tableReference, Locale locale = null)

Parameters

Type	Name	Description
TableReference	tableReference	A reference to the table. A table reference can be either the name of the table or the table collection name Guid.
Locale	locale	The Locale to use instead of the default SelectedLocale

Returns

Type	Description
AsyncOperationHandle

ReleaseAllTables(Locale)

Releases all tables that are currently loaded in the database. This will also release any references to the SharedTableData providing there are no other references to it, such as different Locale versions of the table that have been loaded.

Declaration

public void ReleaseAllTables(Locale locale = null)

Parameters

Type	Name	Description
Locale	locale	The Locale to release tables for, when null all locales will be released.

ReleaseTable(TableReference, Locale)

Releases all references to the table that matches the tableReference and locale. This will also release any references to the SharedTableData providing there are no other references to it, such as different Locale versions of the table that have been loaded. A table is released by calling Release(AsyncOperationHandle) on it which decrements the ref-count. When a given Asset's ref-count is zero, that Asset is ready to be unloaded. For more information, read the Addressables section on when memory is cleared.

Declaration

public void ReleaseTable(TableReference tableReference, Locale locale = null)

Parameters

Type	Name	Description
TableReference	tableReference	A reference to the table. A table reference can be either the name of the table or the table collection name Guid.
Locale	locale	The Locale version of the table that should be unloaded. When null the SelectedLocale will be used.

Examples

This shows how to release a table but prevent it from being unloaded.

public class ReleaseSample : MonoBehaviour
{
AsyncOperationHandle<StringTable> m_Table;

IEnumerator Start()
{
    TableReference tableReference = "My Game Text";
    m_Table = LocalizationSettings.StringDatabase.GetTableAsync(tableReference);

    yield return m_Table;

    // To prevent a table from being released we can acquire a reference to it.
    // Now we will always keep this table, even if the Selected Locale is changed.
    Addressables.ResourceManager.Acquire(m_Table);

    // We can tell the Localization system to release references to the table.
    LocalizationSettings.StringDatabase.ReleaseTable(tableReference);
}

private void OnDisable()
{
    // To release the table we call Release.
    Addressables.Release(m_Table);
}
}

ResetState()

Resets the state of the provider by removing all the cached tables and clearing the preload operation.

Declaration

public void ResetState()

Implements

IReset.ResetState()