XmobiTea Localization

Scene-based Unity localization package. Runtime loads XML into an active key-value dictionary, then refreshes UGUI/TMP text through localization components.

Need-Based Routing

Open the smallest file that answers the task.

| Need | Use | | --- | --- | | Choose API or generate common code | AI_USAGE.md | | Switch runtime language, read current language, build language selector | AI_SWITCH_LANGUAGE.md | | Bind fixed UI text or use the bulk localization window | AI_BIND_UI_TEXT.md | | Add, rename, or remove a localization key | AI_ADD_LOCALIZATION_KEY.md | | Import translations from CSV or Google Sheets | AI_IMPORT_TRANSLATIONS.md | | Setup router | AI_SETUP.md | | Scene manager setup and bootstrap | AI_SETUP_LOCALIZATION_MANAGER.md | | Settings, XML, CSV/Google import, constants | AI_SETUP_LOCALIZATION_SETTINGS.md | | Exact signatures, fields, XML shape, editor menus | AI_API_REFERENCE.md | | Lifecycle, source precedence, async refreshes, edge cases | AI_BEHAVIOR.md | | Package guardrails for AI agents | AGENTS.md | | Source behavior changes | runtime/editor source |

Provides

Runtime:

• LocalizationManager
• LocalizationSettings
• LocalizationLanguageItem
• LocalizationComponent
• TMP_LocalizationComponent
• LocalizationConstantId

Editor:

• settings asset creation/opening;
• CSV or Google Sheets import into XML;
• LocalizationConstantId.cs generation;
• localization key dropdown and missing-key warning;
• bulk window for adding/removing localization components.

Runtime Setup

1. Add one active boot-scene LocalizationManager.
2. Run XmobiTea Tools/Localization/Open Settings.
3. Configure localizationLanguageItems.
4. Assign XML TextAsset files.
5. Call LocalizationManager.ChooseLanguage(...) from Start() or later.

Minimal bootstrap:

using UnityEngine;
using XmobiTea.MiniLocalization;

public sealed class LocalizationBootstrap : MonoBehaviour
{
    private void Start()
    {
        LocalizationManager.ChooseLanguage(SystemLanguage.English);
    }
}

Default settings asset path created by Open Settings:

Assets/Resources/XmobiTea LocalizationSettings.asset

Runtime lookup uses Resources.Load<LocalizationSettings>("XmobiTea LocalizationSettings").

Manager setup: AI_SETUP_LOCALIZATION_MANAGER.md. Settings/import setup: AI_SETUP_LOCALIZATION_SETTINGS.md.

Common task guides:

• switch runtime language: AI_SWITCH_LANGUAGE.md;
• bind fixed UI text: AI_BIND_UI_TEXT.md;
• add or rename keys: AI_ADD_LOCALIZATION_KEY.md;
• import CSV or Google Sheets: AI_IMPORT_TRANSLATIONS.md.

Runtime Usage

Direct lookup:

string title = LocalizationManager.GetText("Home_Title");

Generated key lookup:

string title = LocalizationManager.GetText(LocalizationConstantId.Home_Title);

UI binding:

• use LocalizationComponent for UnityEngine.UI.Text;
• use TMP_LocalizationComponent for TMP_Text when TextMesh Pro support is enabled;
• keep the localization component on the same GameObject as the target text so the inspector can auto-fill the reference, or assign the reference manually;
• set key in the Inspector or the bulk localization window;
• regenerate constants after key changes.

For fixed UI copy, prefer localization components over custom scripts that assign .text.

Import Workflow

CSV or Google Sheets are editor import sources only. Runtime reads XML, Addressables XML, or online XML URL.

If one language configures both Addressables XML and online XML, both async loads run; the callback that finishes later mutates the active dictionary last.

Common import shape:

Key,English,Vietnamese
Home_Title,Home,Trang chu
Home_Subtitle,Welcome,Chao mung

Menu:

XmobiTea Tools/Localization/Fetch Localization

CSV-only import does not need Worksheet Key. Google Sheets import does.

After Fetch Localization, any existing Local-LocalizationFile/<Language>.xml output is copied into the assigned local XML assets. Clear stale local output files before online-only fetches if local XML should not change.

XML Shape

<?xml version='1.0' encoding='utf-8'?>
<English>
  <section name='Local'>
    <key name='Home_Title'>Home</key>
  </section>
</English>

Include the XML declaration; the runtime parser reads the root at ChildNodes.Item(1).

Editor Menus

| Menu | Effect | | --- | --- | | XmobiTea Tools/Localization/Open Settings | create/select settings asset | | XmobiTea Tools/Localization/Show LocalizationComponentWindows | bulk add/remove text binding components | | XmobiTea Tools/Localization/Generate LocalizationConstantId.cs | generate constants from first language XML | | XmobiTea Tools/Localization/Fetch Localization | import XML from CSV/Google source, copy existing local output files into assigned XML assets, then regenerate constants |

Sample

Samples~/Example

Contains a minimal two-language CSV/XML setup: LocalizationSample.csv, English.xml, Vietnamese.xml.

Namespace

using XmobiTea.MiniLocalization;

Use this only when declaring LocalizationLanguageItem:

using XmobiTea.MiniLocalization.Core;

Package Metadata

• Package name: com.xmobitea.changx.mini-localization
• Unity version: 2022.3+
• License: Apache-2.0
• Runtime assembly: com.xmobitea.changx.mini-localization.runtime
• Editor assembly: com.xmobitea.changx.mini-localization.editor