com.xmobitea.changx.mini-localization 1.5.0 → 1.5.2

package/AI_BEHAVIOR.md

@@ -0,0 +1,272 @@
+# AI Behavior Notes For XmobiTea Localization
+
+Read this only for lifecycle, source precedence, async refreshes, editor fetch behavior, and key-generation edge cases. Use `AI_SETUP_LOCALIZATION_MANAGER.md` or `AI_SETUP_LOCALIZATION_SETTINGS.md` for setup checklists.
+
+## Fast Facts
+
+| Question | Answer |
+| --- | --- |
+| Does the package create `LocalizationManager`? | No |
+| Does runtime create `LocalizationSettings`? | No |
+| When is settings loaded? | `LocalizationManager.OnInit()` and `GetAllLanguageItem()` |
+| What activates translations? | `LocalizationManager.ChooseLanguage(...)` |
+| Missing-key result? | original key |
+| Runtime reads CSV or Google Sheets? | No |
+| Can one language switch refresh more than once? | Yes, with Addressables or online XML |
+| Does Addressables merge with local XML? | Yes, it adds/overwrites keys |
+| What does online XML do when it completes? | clears the active dictionary, then rebuilds it from the downloaded XML |
+| If Addressables and online XML both exist, what wins last? | whichever async callback finishes later |
+| Are constants discovered at runtime? | No, editor-generated only |
+
+## Initialization
+
+`LocalizationManager` inherits from `XmobiTea.MiniSingleton.Singleton<LocalizationManager>`.
+
+Valid runtime order:
+
+1. a loaded scene contains an active `LocalizationManager`;
+2. `Awake()` assigns the singleton cache;
+3. `OnInit()` loads `Resources.Load<LocalizationSettings>("XmobiTea LocalizationSettings")`;
+4. `OnInit()` builds a `SystemLanguage -> LocalizationLanguageItem` dictionary;
+5. app code calls `ChooseLanguage(...)`.
+
+Calling static APIs from another component's `Awake()` can fail even if a manager object exists, because the singleton may not have initialized yet.
+
+Behavior before activation:
+
+- `ChooseLanguage(...)` before singleton init returns `false`;
+- `GetText(...)` before singleton init returns the input key;
+- UI components that enable before language selection display fallback keys until `OnUpdateText` fires.
+
+## ChooseLanguage Source Order
+
+`ChooseLanguage(systemLanguage)` does this:
+
+1. returns `false` if the manager is missing;
+2. returns `false` if `systemLanguage` is not configured;
+3. assigns `currentLanguage`;
+4. clears the active dictionary;
+5. loads local XML synchronously when `LocalizationLanguageItem.xml` exists;
+6. starts Addressables XML load when available and valid;
+7. starts online XML load when `onlineLocalizationUrl` is not empty;
+8. invokes `OnUpdateText` immediately;
+9. invokes `OnUpdateText` again when valid async Addressables or online results complete.
+
+Per-source callback effect:
+
+| Source | Timing | Dictionary effect |
+| --- | --- | --- |
+| local XML `TextAsset` | sync | seeds dictionary |
+| Addressables `xmlRef` | async | adds keys and overwrites duplicates |
+| online URL XML | async | clears dictionary, then rebuilds from downloaded XML |
+
+There is no coordination between the two async callbacks. If one language configures both `xmlRef` and `onlineLocalizationUrl`, the callback that finishes later mutates the shared dictionary last.
+
+Async stale-result guard:
+
+- Addressables and online callbacks apply only when `instance._currentLanguage == thisLanguage`.
+- If the user changed language before the async result completes, the stale result is ignored.
+
+Failure behavior:
+
+- Addressables failure logs an error and keeps current dictionary content.
+- Online failure logs an error and keeps current dictionary content.
+
+## OnUpdateText Semantics
+
+For local-only languages, one `ChooseLanguage(...)` call fires `OnUpdateText` once.
+
+With async sources, one call may fire two or three times:
+
+| Trigger | Event timing |
+| --- | --- |
+| local XML | immediate |
+| Addressables XML | async completion |
+| online XML | async completion |
+
+Custom listeners must be idempotent.
+
+When both async sources are configured, the later refresh order follows callback completion order, not source type priority.
+
+Safe subscription:
+
+```csharp
+private void OnEnable()
+{
+    LocalizationManager.OnUpdateText -= Refresh;
+    LocalizationManager.OnUpdateText += Refresh;
+    Refresh();
+}
+
+private void OnDisable()
+{
+    LocalizationManager.OnUpdateText -= Refresh;
+}
+```
+
+`OnUpdateText` is a public static `Action`, not a C# `event`. External code can overwrite it. Agents should only generate `+=` and `-=`.
+
+## Lookup Behavior
+
+`GetText(key)` returns:
+
+- `key` when the manager is missing;
+- `key` when `key` is null or empty;
+- `key` when the active dictionary does not contain it;
+- translated dictionary value when found.
+
+Fallback-to-key is normal display behavior. Do not treat missing translations as exceptions unless project code adds validation.
+
+## UI Component Behavior
+
+`LocalizationComponentBase`:
+
+- stores `[LocalizationKey] protected string _key`;
+- subscribes to `LocalizationManager.OnUpdateText` on enable;
+- unsubscribes on disable;
+- calls `OnUpdateText()` immediately after subscribing.
+
+Targets:
+
+| Component | Target | Auto-resolve |
+| --- | --- | --- |
+| `LocalizationComponent` | `UnityEngine.UI.Text` | `GetComponent<Text>()` |
+| `TMP_LocalizationComponent` | `TMP_Text` | `GetComponent<TMP_Text>()` |
+
+Use these components for fixed UI text. Generate manual listeners only for dynamic text, non-UI state, or custom rendering.
+
+## XML Behavior
+
+The parser is structural, not schema-based.
+
+Expected shape:
+
+```xml
+<?xml version='1.0' encoding='utf-8'?>
+<English>
+  <section name='Local'>
+    <key name='Home_Title'>Home</key>
+  </section>
+</English>
+```
+
+Parser assumptions:
+
+- root element is read from `xmlDoc.ChildNodes.Item(1)`, so include the XML declaration;
+- key nodes are nested under section nodes, under the root;
+- each key node has a `name` attribute;
+- text comes from `node.InnerText`;
+- duplicate keys log and later values overwrite earlier values.
+
+Runtime replacements after XML read:
+
+| Stored text | Runtime text |
+| --- | --- |
+| `\\n` | newline |
+| `&lt;` | `<` |
+| `&gt;` | `>` |
+| `&#38;` | `&` |
+| `&#39;` | `'` |
+| `&#34;` | `"` |
+
+Malformed XML, missing declarations, or missing `name` attributes can throw during load.
+
+## Editor Fetch Behavior
+
+`FetchType` is editor-only:
+
+```csharp
+FetchType.None
+FetchType.FromGoogleSheets
+FetchType.FromCsv
+```
+
+Current constraints:
+
+- `Fetch Localization` checks `worksheetKey` only when a Google Sheets fetch type is selected.
+- CSV-only import can leave `worksheetKey` empty.
+- The custom inspector hides `worksheetKey` unless a Google Sheets fetch type is selected.
+- Empty Google sheet-name fields are passed to the fetch executable as default tab names: `local` for local XML and `online` for online XML. The inspector still warns when they are empty.
+- Google sheet tab names are not quoted in the command-line arguments, so names with spaces are unsafe.
+- CSV assets are not null-checked before `.text`.
+- CSV row lengths are not validated before language-column indexing.
+- Local XML target assets are assumed to exist when a `Local-LocalizationFile/<Language>.xml` file is copied back.
+- After every `Fetch Localization` run, the editor copies any existing `Local-LocalizationFile/<Language>.xml` file over the matching language item's assigned local `xml` asset, even when the current local fetch type is `None` or only online output was requested. Clear stale local output files before online-only fetches if local XML must remain untouched.
+- Runtime never reads CSV files.
+
+### FromGoogleSheets
+
+When either fetch type is `FromGoogleSheets`, the editor:
+
+1. finds the package folder in `Library/PackageCache` or `Assets`;
+2. runs the bundled platform `GetLocalization` executable;
+3. passes credentials path, worksheet key, local/online booleans, sheet names, and configured languages; empty sheet names are sent as `local` or `online`;
+4. expects output files under `Local-LocalizationFile/<Language>.xml` and/or `Online-LocalizationFile/<Language>.xml`;
+5. copies existing local output files over each language item's configured local `XML` asset;
+6. refreshes assets;
+7. regenerates `LocalizationConstantId.cs`.
+
+Sheet tab names are passed as command-line arguments without quoting. Avoid spaces.
+
+### FromCsv
+
+When local fetch is `FromCsv`, the editor:
+
+1. parses `csvFetchLocalLocalization` with comma delimiter and header removal;
+2. maps column 1 to key and later columns to `localizationLanguageItems` order;
+3. writes `Local-LocalizationFile/<Language>.xml`;
+4. copies existing local output files over each language item's configured local `XML` asset.
+
+When online fetch is `FromCsv`, the editor:
+
+1. parses `csvFetchOnlineLocalization`;
+2. writes `Online-LocalizationFile/<Language>.xml`;
+3. does not assign those files to a runtime field.
+
+Online runtime loading still depends on `LocalizationLanguageItem.onlineLocalizationUrl`.
+
+## Generated Constants
+
+`Generate LocalizationConstantId.cs`:
+
+1. loads `LocalizationSettings`;
+2. reads the first configured language item;
+3. parses that item's local XML;
+4. writes `Assets/XmobiTea-constant/Scripts/LocalizationConstantId.cs`;
+5. creates `public static readonly string` members.
+
+Consequences:
+
+- keys missing from the first language XML are not generated;
+- runtime-only or online-only keys are not generated unless they also exist in first local XML;
+- generated constants do not update automatically when XML changes;
+- key picker warnings depend on generated constants loaded in assemblies.
+
+Field-name conversion:
+
+- invalid C# identifier characters become `_`;
+- diacritics are removed;
+- digit-starting names are prefixed with `_`;
+- C# keywords are prefixed with `_`;
+- duplicate generated field names log and later duplicates are skipped.
+
+## Correct Mental Model
+
+Treat this package as:
+
+- scene-authored;
+- explicit-language-selection based;
+- `Resources` configured;
+- XML-backed at runtime;
+- key-based with fallback-to-key display;
+- event-driven for UI refresh;
+- editor-assisted for CSV/Google Sheets import and constant generation.
+
+Do not treat it as:
+
+- an auto-locale bootstrapper;
+- a runtime CSV reader;
+- a Google Sheets runtime client;
+- an ICU/pluralization formatter;
+- a strict XML schema validator;
+- a compile-time-safe localization database.

package/AI_BEHAVIOR.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 6a543512727d4ef99fc57b45f518faec
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/AI_BIND_UI_TEXT.md

@@ -0,0 +1,97 @@
+# AI Bind UI Text
+
+Use this when a task needs to localize fixed UI copy such as labels, titles, descriptions, tabs, button captions, or popup text.
+
+## Default Rule
+
+Use localization components for fixed UI text.
+
+Do not generate a custom script that only does:
+
+```csharp
+text.text = LocalizationManager.GetText(key);
+```
+
+## Component Choice
+
+| Target | Use |
+| --- | --- |
+| `UnityEngine.UI.Text` | `LocalizationComponent` |
+| `TMP_Text` | `TMP_LocalizationComponent` |
+
+`TMP_LocalizationComponent` exists only when TextMesh Pro support defines `UNITY_USING_TMPRO`.
+
+## Bind One Object
+
+Checklist:
+
+- add the correct localization component to the same `GameObject` as the target text when possible;
+- set `key`;
+- keep the target reference on the component if the text is not on the same object;
+- call `LocalizationManager.ChooseLanguage(...)` during startup so the component receives translated text.
+
+Inspector helpers:
+
+- `Reload Text` forces one preview refresh;
+- the key dropdown uses generated `LocalizationConstantId` values;
+- missing-key warnings compare the assigned key against generated constants.
+
+## Bulk Bind Existing UI
+
+Open:
+
+```text
+XmobiTea Tools/Localization/Show LocalizationComponentWindows
+```
+
+Use the window to:
+
+- scan a parent object;
+- add `LocalizationComponent` or `TMP_LocalizationComponent`;
+- assign keys;
+- remove an incorrect localization component.
+
+## Dynamic Or Composed Text
+
+Use custom code only for:
+
+- text built from runtime values;
+- non-UI cached state;
+- custom rendering outside `Text` and `TMP_Text`.
+
+Pattern:
+
+```csharp
+private void OnEnable()
+{
+    LocalizationManager.OnUpdateText -= Refresh;
+    LocalizationManager.OnUpdateText += Refresh;
+    Refresh();
+}
+
+private void OnDisable()
+{
+    LocalizationManager.OnUpdateText -= Refresh;
+}
+```
+
+## Key Safety
+
+After adding, removing, or renaming keys, run:
+
+```text
+XmobiTea Tools/Localization/Generate LocalizationConstantId.cs
+```
+
+Use generated constants when available:
+
+```csharp
+localizationComponent.key = LocalizationConstantId.Home_Title;
+```
+
+## Hard No
+
+- Do not bind fixed UI copy through one-off scripts when a localization component is enough.
+- Do not assume the component will find a target on another object automatically.
+- Do not rely on key dropdown warnings before constants are generated.
+- Do not forget that components can refresh more than once after one language switch.

package/AI_BIND_UI_TEXT.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 1d94a22a4df04055a673d6ddc188052e
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/AI_IMPORT_TRANSLATIONS.md

@@ -0,0 +1,84 @@
+# AI Import Translations
+
+Use this when translations come from CSV or Google Sheets, or when XML files must be regenerated through editor tooling.
+
+## Runtime Rule
+
+- runtime never reads CSV or Google Sheets;
+- `Fetch Localization` is editor-only;
+- fetch converts external data into XML and then regenerates `LocalizationConstantId.cs`.
+
+## CSV Import
+
+Checklist:
+
+- import the CSV into Unity as a `TextAsset`;
+- configure `localizationLanguageItems` in the same order as CSV language columns;
+- assign a local XML `TextAsset` to every runtime language item;
+- set `Fetch Type Local Localization` to `FromCsv` when generating local XML;
+- assign `Csv Fetch Local Localization`;
+- set `Fetch Type Online Localization` to `FromCsv` only when generating online XML too;
+- assign `Csv Fetch Online Localization` when online fetch uses CSV;
+- run `XmobiTea Tools/Localization/Fetch Localization`.
+
+CSV shape:
+
+```text
+Key,English,Vietnamese
+Home_Title,Home,Trang chu
+Home_Subtitle,Welcome,Chao mung
+```
+
+Rules:
+
+- delimiter is comma;
+- first row is header and is skipped;
+- first column is key;
+- every row must have one cell per configured language;
+- use empty cells for blank translations instead of shortening rows.
+
+## Google Sheets Import
+
+Checklist:
+
+- put the spreadsheet id/key in `worksheetKey`;
+- configure `localizationLanguageItems` in the same order as sheet language columns;
+- assign a local XML `TextAsset` to every runtime language item;
+- set `Fetch Type Local Localization` to `FromGoogleSheets` when generating local XML;
+- set `Sheet Name Fetch Local Localization`; empty uses the default executable argument `local`;
+- set `Fetch Type Online Localization` to `FromGoogleSheets` only when generating online XML too;
+- set `Sheet Name Fetch Online Localization` when online fetch uses Google Sheets; empty uses the default executable argument `online`;
+- keep explicit sheet names without spaces;
+- run `XmobiTea Tools/Localization/Fetch Localization`.
+
+## Outputs
+
+- generated local XML is copied into each assigned local `xml` asset;
+- generated online XML is written under `Online-LocalizationFile/<Language>.xml`;
+- runtime online loading still requires hosting those XML files and assigning `onlineLocalizationUrl`.
+- after any fetch run, existing `Local-LocalizationFile/<Language>.xml` files are copied into assigned local `xml` assets, even if only online output was requested. Remove stale local output files first when local XML must stay unchanged.
+
+## When To Regenerate Constants Only
+
+Run this instead of full fetch when XML is already up to date and only keys changed:
+
+```text
+XmobiTea Tools/Localization/Generate LocalizationConstantId.cs
+```
+
+## Common Failures
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| fetch fails for Google Sheets | empty `worksheetKey` | set the spreadsheet id/key |
+| XML generated for wrong language | language order does not match CSV or Sheet columns | reorder `localizationLanguageItems` or source columns |
+| local XML changes during online-only fetch | stale `Local-LocalizationFile/<Language>.xml` exists | remove stale local output files before fetching |
+| online XML never used at runtime | `onlineLocalizationUrl` is empty | host the generated XML and set the URL |
+| constants missing keys after fetch | first configured local XML is incomplete | fix first local XML and regenerate constants |
+
+## Hard No
+
+- Do not claim CSV or Google Sheets are runtime sources.
+- Do not skip assigning local XML assets when local XML output is expected.
+- Do not shorten translation rows when one language is blank.
+- Do not forget that fetch menu actions are editor-only entrypoints.

package/AI_IMPORT_TRANSLATIONS.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: b1ae3ea4769d478b93068a586c538744
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/AI_SETUP.md

@@ -0,0 +1,30 @@
+# AI Setup For XmobiTea Localization
+
+Use this file only as a setup router. Open the specific setup file below.
+
+## Setup Routing
+
+| Need | Use |
+| --- | --- |
+| Scene object, singleton timing, bootstrap call, persistent manager | `AI_SETUP_LOCALIZATION_MANAGER.md` |
+| Settings asset, language items, XML shape, CSV/Google import, constants | `AI_SETUP_LOCALIZATION_SETTINGS.md` |
+| Switch runtime language after setup | `AI_SWITCH_LANGUAGE.md` |
+| Bind fixed UI text | `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` |
+| Choose runtime API after setup | `AI_USAGE.md` |
+| Lifecycle/source precedence edge cases | `AI_BEHAVIOR.md` |
+
+## Minimal Runtime Contract
+
+- A loaded scene has one active initialized `LocalizationManager`.
+- A `LocalizationSettings` asset loadable as `Resources.Load<LocalizationSettings>("XmobiTea LocalizationSettings")` exists.
+- `localizationLanguageItems` contains the requested `SystemLanguage`.
+- Runtime language items have XML unless deliberately online/addressable-only.
+- App bootstrap calls `LocalizationManager.ChooseLanguage(...)` from `Start()` or later.
+
+## Setup Order
+
+1. Configure `LocalizationSettings`: `AI_SETUP_LOCALIZATION_SETTINGS.md`.
+2. Add and bootstrap `LocalizationManager`: `AI_SETUP_LOCALIZATION_MANAGER.md`.
+3. Bind UI text or call runtime APIs: `AI_USAGE.md`.

package/AI_SETUP.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 84785a85c25f40dcbe19b0762490a5ac
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/AI_SETUP_LOCALIZATION_MANAGER.md

@@ -0,0 +1,96 @@
+# AI Setup LocalizationManager
+
+Use this when a task mentions scene setup, singleton timing, bootstrapping language selection, persistent localization, UI text binding timing, or `[Localization] LocalizationManager instance is null!`.
+
+Open smaller task files when setup is already done:
+
+- `AI_SWITCH_LANGUAGE.md` for switching runtime language;
+- `AI_BIND_UI_TEXT.md` for binding fixed UI text.
+
+## Required Imports
+
+```csharp
+using UnityEngine;
+using XmobiTea.MiniLocalization;
+```
+
+## Scene Contract
+
+- A loaded scene has one active `LocalizationManager` component.
+- `LocalizationManager.Awake()` has initialized before static APIs are called.
+- `LocalizationSettings` already exists and contains the requested language.
+- App bootstrap calls `LocalizationManager.ChooseLanguage(...)` from `Start()` or later.
+- Do not auto-create the manager in runtime code.
+
+## Scene Setup
+
+Checklist:
+
+- Create a boot-scene `GameObject` named `LocalizationManager`.
+- Add the `LocalizationManager` component.
+- Keep the object active and enabled before localization APIs are used.
+- Add `XmobiTea.MiniSingleton.DontDestroy` only when the manager must survive scene loads.
+- Do not add extra `LocalizationManager` objects in later scenes when using one persistent boot manager.
+- Call `ChooseLanguage(...)` from `Start()` or later.
+
+Minimal bootstrap:
+
+```csharp
+using UnityEngine;
+using XmobiTea.MiniLocalization;
+
+public sealed class LocalizationBootstrap : MonoBehaviour
+{
+    [SerializeField] private SystemLanguage startupLanguage = SystemLanguage.English;
+
+    private void Start()
+    {
+        LocalizationManager.ChooseLanguage(startupLanguage);
+    }
+}
+```
+
+## Call Timing
+
+Avoid calling localization static APIs from another component's `Awake()` unless script execution order guarantees `LocalizationManager.Awake()` has already run.
+
+Prefer:
+
+```csharp
+private void Start()
+{
+    LocalizationManager.ChooseLanguage(SystemLanguage.English);
+}
+```
+
+UI components that enable before `ChooseLanguage(...)` can show keys first and refresh after `OnUpdateText` fires.
+
+## Component Binding Setup
+
+For fixed scene UI:
+
+- Use `XmobiTea Tools/Localization/Show LocalizationComponentWindows` to bulk scan a parent object.
+- Add `LocalizationComponent` for `UnityEngine.UI.Text`.
+- Add `TMP_LocalizationComponent` for `TMP_Text` when TextMesh Pro support is enabled.
+- Set `key`.
+- Use components for fixed labels, titles, descriptions, tabs, and button captions.
+- Use custom code only for dynamic/composed text or non-UI state.
+
+Inspector tools:
+
+| Tool | Effect |
+| --- | --- |
+| `Reload Text` | force one component refresh |
+| key dropdown | selects generated keys found in loaded `LocalizationConstantId` types |
+| missing-key warning | compares component key against generated constants |
+
+Run `Generate LocalizationConstantId.cs` before relying on dropdown warnings. Constants setup lives in `AI_SETUP_LOCALIZATION_SETTINGS.md`.
+
+## Manager Setup Errors
+
+| Symptom or log | Likely cause | Fix |
+| --- | --- | --- |
+| `[Localization] LocalizationManager instance is null!` | no initialized scene manager | add active manager or call later |
+| `ChooseLanguage(...)` returns `false` | manager missing or language not configured | verify manager and settings language item |
+| UI shows raw keys before startup finishes | components enabled before `ChooseLanguage(...)` | call `ChooseLanguage(...)` in bootstrap and allow refresh |
+| duplicate manager disappears | singleton destroyed later duplicate | keep only one persistent manager |

package/AI_SETUP_LOCALIZATION_MANAGER.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 47add6df507f4db98391d4ed1de82b5c
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: