Archived on 2026-10-24. This is a historical implementation note, not current setup instructions or an active task list. Original claims, code examples, file paths, and completion statements have not all been revalidated. Use the current documentation and issue register for maintenance decisions.

LocalizedTextHandler Usage Guide¶

Overview¶

The LocalizedTextHandler is a component that allows you to handle localization for UI panels and menus without creating a separate controller script. Simply attach it to any GameObject that contains TMP_Text elements, and it will automatically update all assigned texts when the language changes.

Features¶

✅ No controller needed for simple UI panels
✅ Supports multiple text elements on a single GameObject
✅ Automatically updates when language changes
✅ Easy configuration in Unity Inspector
✅ Debug mode for troubleshooting
✅ Runtime methods for dynamic text management
✅ Clean event-based architecture

How to Use¶

1. Add Component to GameObject¶

Method A: Via Inspector 1. Select your UI panel or GameObject 2. Click "Add Component" in the Inspector 3. Search for "Localized Text Handler"

Method B: Via Context Menu 1. Select your UI panel or GameObject in the Hierarchy 2. Right-click → GameObject → UI → Localized Text Handler

2. Configure Text Pairs¶

In the Inspector, you'll see a list called "Text Pairs":

Element	Target Text	Localized String
Size 0	[TMP_Text]	[LocalizedString]

For each text element you want to localize:

Click the + button to add a new pair
Drag the TMP_Text component from your UI into the "Target Text" field
Assign a LocalizedString reference (either from a ScriptableObject or create a new one)

3. Example Setup¶

Confirmation Panel Example:

ConfirmationPanel (GameObject)
├── LocalizedTextHandler
│   ├── Text Pairs:
│   │   ├── Element 0
│   │   │   ├── Target Text: TitleText
│   │   │   └── Localized String: Confirmation_Title
│   │   ├── Element 1
│   │   │   ├── Target Text: MessageText
│   │   │   └── Localized String: Confirmation_Message
│   │   └── Element 2
│   │       ├── Target Text: ConfirmButton
│   │       └── Localized String: Confirmation_Yes
├── TitleText (TMP_Text)
├── MessageText (TMP_Text)
└── ConfirmButton (Button with TMP_Text)

Inspector Options¶

Update On Enable (Default: true)¶

When checked, texts are updated immediately when the GameObject is enabled
Useful if you want to manually control when texts are updated

Debug Mode (Default: false)¶

Enables logging for localization events
Helpful for troubleshooting which texts are being updated
Logs changes to the Console when locale changes

Runtime Methods¶

RefreshTexts()¶

Manually trigger an update of all assigned texts.

// Example usage
GetComponent<LocalizedTextHandler>().RefreshTexts();

Useful for: - Dynamic content changes - Updating texts after modifying localized strings at runtime - Testing localization in editor

AddTextPair(TextMeshPro.TMP_Text target, LocalizedString localized)¶

Add a new text pair at runtime.

// Example: Add a text pair dynamically
var newTitleText = GetComponentInChildren<TMP_Text>();
var newLocalizedString = new LocalizedString 
{ 
    TableReference = "UI", 
    TableEntryReference = "New_Title" 
};

GetComponent<LocalizedTextHandler>().AddTextPair(newTitleText, newLocalizedString);

RemoveTextPair(TextMeshPro.TMP_Text target)¶

Remove a text pair by its TMP_Text reference.

// Example: Remove a text pair
var textToRemove = GetComponentInChildren<TMP_Text>();
GetComponent<LocalizedTextHandler>().RemoveTextPair(textToRemove);

Use Cases¶

1. Confirmation Dialogs¶

// No controller needed - just attach LocalizedTextHandler
ConfirmationPanel
├── LocalizedTextHandler
│   └── Text Pairs: [Title, Message, Yes, No]

// About Page
AboutPanel
├── LocalizedTextHandler
│   └── Text Pairs: [Header, Version, Credits, Links]

3. Tutorial Text Panels¶

// Tutorial Step
TutorialPanel
├── LocalizedTextHandler
│   └── Text Pairs: [StepTitle, Instruction, Tip]

4. Loading Screen Messages¶

// Loading Screen
LoadingScreen
├── LocalizedTextHandler
│   └── Text Pairs: [LoadingMessage, ProgressText]

Best Practices¶

DO¶

✅ Use for simple UI panels with static text
✅ Use debug mode during development
✅ Organize text pairs logically in the Inspector
✅ Name your text elements descriptively (e.g., "TitleText", "MessageText")
✅ Use meaningful LocalizedString reference names

DON'T¶

❌ Use for complex UI with dynamic logic (use a controller instead)
❌ Leave debug mode enabled in production builds
❌ Create LocalizedTextHandler for single text elements (use Unity's built-in Localize String Event component instead)

Comparison: LocalizedTextHandler vs. Controller¶

Feature	LocalizedTextHandler	Controller Script
Complexity	Low	High
Code Required	None (just component)	Custom script needed
Best For	Static UI, simple panels	Complex UI with logic
Reusability	High (just configure)	Medium (may need customization)
Maintenance	Easy	Requires code updates

Troubleshooting¶

Text not updating on language change¶

Check that Update On Enable is checked
Verify the GameObject is active in the hierarchy
Ensure LocalizationManager.OnLocaleChanged is firing (check other localized elements)
Enable Debug Mode to see if the event is being received

Missing localized text¶

Verify the LocalizedString reference is properly configured
Check that the Table Reference and Table Entry Reference are correct
Ensure the localization table exists and has the entry
Use Debug Mode to see what text is being retrieved

Null Reference errors¶

Make sure all TMP_Text references are assigned
Verify all LocalizedString references are set
Check that the GameObject hierarchy is correct

Advanced Usage¶

Combining with Other Components¶

You can use LocalizedTextHandler alongside other UI components:

// Example: Confirmation dialog with button handlers
ConfirmationPanel
├── LocalizedTextHandler (handles text)
├── ConfirmationDialogUI (handles button clicks)
└── Layout elements

Localization with Conditional Logic¶

If you need conditional logic based on language, you can still use a controller:

public class MenuController : MonoBehaviour
{
    private LocalizedTextHandler textHandler;

    private void Awake()
    {
        textHandler = GetComponent<LocalizedTextHandler>();
        LocalizationManager.OnLocaleChanged += HandleLanguageChange;
    }

    private void HandleLanguageChange(int localeId)
    {
        // Custom logic based on language
        if (localeId == 0) // English
        {
            // Do something specific for English
        }
        // TextHandler will automatically update texts
    }
}

Performance Considerations¶

LocalizedTextHandler only subscribes when enabled
Automatically unsubscribes when disabled to prevent memory leaks
Minimal overhead - only processes assigned text pairs
No performance impact on GameObjects without the component

Support¶

For issues or questions: 1. Enable Debug Mode to see detailed logging 2. Check the Console for error messages 3. Verify LocalizationManager is properly initialized 4. Ensure Unity Localization package is installed and configured

LocalizationManager - Manages language changes
LocalizedString - Unity's localization reference
TextMeshPro.TMP_Text - Text component for displaying localized text