Localized Object
Component for binding data to UI elements
Overview
A component that acts as the bridge between your localization data and your scene. It attaches to a GameObject and automatically updates a target component (TMP_Text, UniText, AudioSource, or Image) based on the selected language and settings.
Workflow
When the game starts or the language changes, the component follows these steps:
Lookup: It finds the translation using the selected Table and Key.
Fallback: If content is missing or empty, it checks whether Fallback To Default is enabled. Unless the object is locked to a language, it then tries the default language.
Processing: It processes any Dynamic Strings (variables like {username}) registered to the object.
Application: It applies the final result to the target component (TMP_Text, UniText, AudioSource, or Image).
Dynamic Strings
You can inject variables into your localized text using the {variable} syntax.
For example, if your translation key is: "Hello, {player_name}!".
Bind player_name to a field or readable property on a component:
using UnityEngine;
using Evo.Localization;
public class LocalizedGreeting : MonoBehaviour
{
public LocalizedObject welcomeText;
public string playerName = "PlayerOne";
void Start()
{
welcomeText.AddDynamicString("player_name", nameof(playerName), this);
welcomeText.UpdateContent();
}
}Values are read when content is refreshed. Call UpdateContent() after changing a value if you need to display it immediately. A null reference does not supply a literal replacement value.
Public API
Properties
| Property | Type | Description |
|---|---|---|
table | LocalizationTable | The table asset containing the key. |
tableKey | string | The specific key ID to localize. |
objectType | ObjectType | Defines which component to drive: TMPText, UniText (when installed), Audio, Image, or Custom. |
useFallback | bool | If true, uses the default language when content is missing or empty. Disabled by language locking. |
updateMode | UpdateMode | Selects the initial refresh: OnEnable (default) or Start. Both also follow language/data changes once registered. OnDemand requires explicit UpdateContent() calls. |
lockToLanguage | bool | If true, this object will ignore the global language and use lockedLanguage instead. |
lockedLanguage | LocalizationLanguage | The specific language to use if lockToLanguage is enabled. |
Methods
| Method | Description |
|---|---|
UpdateContent() | Forces the object to refresh its content immediately based on the current key and language. |
AddDynamicString(string keyword, string targetVar, Object reference) | Binds a placeholder to an instance field or readable property on reference. All three arguments are required; targetVar is the member name, not a literal value. |
GetString(string key) | Retrieves a localized string from the currently assigned table using the provided key. |
GetAudio(string key) | Retrieves a localized audio clip from the currently assigned table using the provided key. |
GetSprite(string key) | Retrieves a localized sprite from the currently assigned table using the provided key. |
Events
The component provides Unity Events that trigger whenever the content is updated. This allows you to drive custom logic or components not natively supported.
| Event | Parameter | Description |
|---|---|---|
onStringChanged | string | Invoked when the text content is updated. |
onAudioChanged | AudioClip | Invoked when the audio clip is updated. |
onSpriteChanged | Sprite | Invoked when the sprite image is updated. |
Example
using UnityEngine;
using UnityEngine.UI;
using Evo.Localization;
public class LocalizedObjectExample : MonoBehaviour
{
public LocalizedObject targetObject;
public Image externalImage;
public string playerName = "PlayerOne";
void Start()
{
// Dynamic Strings
// Binds the "{username}" placeholder in the text to "PlayerOne"
targetObject.AddDynamicString("username", nameof(playerName), this);
// Optional - Refresh to show the new string with the variable applied
targetObject.UpdateContent();
// You can add listeners to provided events that will get triggered with language changes
targetObject.onStringChanged.AddListener(EventTest);
}
void EventTest(string output)
{
Debug.Log($"Localization returned a new output: {output}");
}
void UpdateText()
{
// Change the key at runtime
targetObject.tableKey = "new_key_id";
// Force the object to refresh immediately
targetObject.UpdateContent();
}
void GetDirectData()
{
// Retrieve data directly from the object's assigned table
// This is useful for getting related assets that aren't handling the main text
string text = targetObject.GetString("other_key");
AudioClip clip = targetObject.GetAudio("sfx_key");
Sprite icon = targetObject.GetSprite("icon_key");
// Alternatively, specify the table ID for a static lookup
string altText = LocalizedObject.GetString("Table ID", "other_key");
AudioClip altClip = LocalizedObject.GetAudio("Table ID", "sfx_key");
Sprite altIcon = LocalizedObject.GetSprite("Table ID", "icon_key");
}
}