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

package/AGENTS.md

@@ -6,16 +6,16 @@ Scope: everything inside `Assets/XmobiTea Localization`.
 
 Choose by current need. Open the smallest file that answers it.
 
-| Need | Use |
-| --- | --- |
-| Choose localization API or generate common runtime 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 object, singleton timing, bootstrap, persistent manager | `AI_SETUP_LOCALIZATION_MANAGER.md` |
-| Settings asset, language items, XML, CSV/Google import, constants | `AI_SETUP_LOCALIZATION_SETTINGS.md` |
+| Need | Use |
+| --- | --- |
+| Choose localization API or generate common runtime 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 object, singleton timing, bootstrap, persistent manager | `AI_SETUP_LOCALIZATION_MANAGER.md` |
+| Settings asset, language items, XML, CSV/Google import, constants | `AI_SETUP_LOCALIZATION_SETTINGS.md` |
 | Exact signatures, return values, serialized fields, XML shape, editor menus | `AI_API_REFERENCE.md` |
 | Lifecycle, source precedence, async refreshes, fetch edge cases | `AI_BEHAVIOR.md` |
 | Package summary for humans | `README.md` |
@@ -42,11 +42,11 @@ Choose by current need. Open the smallest file that answers it.
 - If one language configures both Addressables XML and online XML, both async loads run and the callback that finishes later mutates the dictionary last.
 - `OnUpdateText` can fire more than once for one `ChooseLanguage(...)` call.
 - Runtime never reads CSV or Google Sheets.
-- `fetchType` is editor-only: `None`, `FromGoogleSheets`, `FromCsv`.
-- `worksheetKey` is required only when either fetch type is `FromGoogleSheets`.
-- Empty Google sheet-name fields are sent to the fetch executable as `local` or `online`; explicit sheet names must avoid spaces.
-- CSV rows must include `Key` plus one cell per configured language.
-- After any fetch run, existing `Local-LocalizationFile/<Language>.xml` files are copied into assigned local XML assets, even during online-only fetches.
+- `fetchType` is editor-only: `None`, `FromGoogleSheets`, `FromCsv`.
+- `worksheetKey` is required only when either fetch type is `FromGoogleSheets`.
+- Empty Google sheet-name fields are sent to the fetch executable as `local` or `online`; explicit sheet names must avoid spaces.
+- CSV rows must include `Key` plus one cell per configured language.
+- After any fetch run, existing `Local-LocalizationFile/<Language>.xml` files are copied into assigned local XML assets, even during online-only fetches.
 - Generated constants come from editor tooling, not runtime discovery.
 - Generated `LocalizationConstantId` members are `public static readonly string`.
 - The generator reads keys from the first configured language item's local XML.
@@ -104,14 +104,14 @@ If changing resource paths, manager lifecycle, XML parsing, source precedence, g
 - `Editor/LocalizationManagerEditor.cs`
 - `Editor/LocalizationSettingsEditor.cs`
 - `Editor/LocalizationKeyDrawer.cs`
-- `AI_USAGE.md`
-- `AI_SWITCH_LANGUAGE.md`
-- `AI_BIND_UI_TEXT.md`
-- `AI_ADD_LOCALIZATION_KEY.md`
-- `AI_IMPORT_TRANSLATIONS.md`
-- `AI_SETUP.md`
-- `AI_SETUP_LOCALIZATION_MANAGER.md`
-- `AI_SETUP_LOCALIZATION_SETTINGS.md`
+- `AI_USAGE.md`
+- `AI_SWITCH_LANGUAGE.md`
+- `AI_BIND_UI_TEXT.md`
+- `AI_ADD_LOCALIZATION_KEY.md`
+- `AI_IMPORT_TRANSLATIONS.md`
+- `AI_SETUP.md`
+- `AI_SETUP_LOCALIZATION_MANAGER.md`
+- `AI_SETUP_LOCALIZATION_SETTINGS.md`
 - `AI_API_REFERENCE.md`
 - `AI_BEHAVIOR.md`
 - `README.md`

package/AI_ADD_LOCALIZATION_KEY.md

@@ -1,78 +1,78 @@
-# AI Add Localization Key
-
-Use this when a task adds, renames, or removes a localization key, or when `LocalizationConstantId` is missing or stale.
-
-## Source Of Truth
-
-Choose one source of truth and update that source first:
-
-- CSV or Google Sheets when the project imports translations through `Fetch Localization`;
-- local XML files when the project edits runtime XML directly.
-
-The first configured language item's local XML must contain the full key set because constant generation reads that file only.
-
-## Add A Key
-
-Checklist:
-
-- add the key to the source of truth;
-- if editing XML directly, add the key to every runtime language XML;
-- keep XML in the runtime parser shape;
-- regenerate constants;
-- update `LocalizationComponent`, `TMP_LocalizationComponent`, and scripts to use the new key.
-
-Minimal XML entry:
-
-```xml
-<key name='Home_Title'>Home</key>
-```
-
-## Rename A Key
-
-Checklist:
-
-- rename the key in the source of truth;
-- update every affected XML or translation row;
-- regenerate constants;
-- update all component keys and script references;
-- remove old key usages so UI does not fall back to the old raw key string.
-
-## Remove A Key
-
-Checklist:
-
-- delete the key from the source of truth;
-- regenerate constants;
-- remove or replace every component and code reference to that key.
-
-## Regenerate Constants
-
-Run:
-
-```text
-XmobiTea Tools/Localization/Generate LocalizationConstantId.cs
-```
-
-Generated file:
-
-```text
-Assets/XmobiTea-constant/Scripts/LocalizationConstantId.cs
-```
-
-Use raw strings temporarily when constants are intentionally not regenerated yet.
-
-## Verify
-
-Checklist:
-
-- run `ChooseLanguage(...)`;
-- confirm `LocalizationManager.GetText(key)` returns translated text instead of the raw key;
-- confirm fixed UI text refreshes;
-- confirm the generated constant exists when code uses `LocalizationConstantId.*`.
-
-## Hard No
-
-- Do not add a key only to a non-first language XML and expect a constant to generate.
-- Do not rename keys in code only.
-- Do not leave stale component keys after a rename or delete.
-- Do not assume runtime discovers new constants automatically.
+# AI Add Localization Key
+
+Use this when a task adds, renames, or removes a localization key, or when `LocalizationConstantId` is missing or stale.
+
+## Source Of Truth
+
+Choose one source of truth and update that source first:
+
+- CSV or Google Sheets when the project imports translations through `Fetch Localization`;
+- local XML files when the project edits runtime XML directly.
+
+The first configured language item's local XML must contain the full key set because constant generation reads that file only.
+
+## Add A Key
+
+Checklist:
+
+- add the key to the source of truth;
+- if editing XML directly, add the key to every runtime language XML;
+- keep XML in the runtime parser shape;
+- regenerate constants;
+- update `LocalizationComponent`, `TMP_LocalizationComponent`, and scripts to use the new key.
+
+Minimal XML entry:
+
+```xml
+<key name='Home_Title'>Home</key>
+```
+
+## Rename A Key
+
+Checklist:
+
+- rename the key in the source of truth;
+- update every affected XML or translation row;
+- regenerate constants;
+- update all component keys and script references;
+- remove old key usages so UI does not fall back to the old raw key string.
+
+## Remove A Key
+
+Checklist:
+
+- delete the key from the source of truth;
+- regenerate constants;
+- remove or replace every component and code reference to that key.
+
+## Regenerate Constants
+
+Run:
+
+```text
+XmobiTea Tools/Localization/Generate LocalizationConstantId.cs
+```
+
+Generated file:
+
+```text
+Assets/XmobiTea-constant/Scripts/LocalizationConstantId.cs
+```
+
+Use raw strings temporarily when constants are intentionally not regenerated yet.
+
+## Verify
+
+Checklist:
+
+- run `ChooseLanguage(...)`;
+- confirm `LocalizationManager.GetText(key)` returns translated text instead of the raw key;
+- confirm fixed UI text refreshes;
+- confirm the generated constant exists when code uses `LocalizationConstantId.*`.
+
+## Hard No
+
+- Do not add a key only to a non-first language XML and expect a constant to generate.
+- Do not rename keys in code only.
+- Do not leave stale component keys after a rename or delete.
+- Do not assume runtime discovers new constants automatically.

package/AI_ADD_LOCALIZATION_KEY.md.meta

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

package/AI_API_REFERENCE.md

@@ -24,7 +24,7 @@ using XmobiTea.MiniLocalization.Core;
 | `public static LocalizationLanguageItem GetCurrentLanguage()` | active item or `null` | inspect selected language | logs error and returns `null` |
 | `public static LocalizationLanguageItem[] GetAllLanguageItem()` | configured items or `null` | show language choices | logs error and returns `null` |
 | `public static string GetTextWithoutBOM(TextAsset textAsset)` | text content | helper for XML `TextAsset` parsing | no manager needed; `textAsset` must be non-null |
-| `public static Action OnUpdateText` | static `Action` field | refresh custom state after dictionary updates | no automatic guard |
+| `public static Action OnUpdateText` | static `Action` field | refresh custom state after dictionary updates | no automatic guard |
 
 `ChooseLanguage(...)` returns `false` when the requested `SystemLanguage` is not configured.
 
@@ -119,14 +119,14 @@ Use this checklist when generating setup instructions:
 | `xmlRef` | optional Addressables runtime XML | shown only when Addressables is installed |
 | `onlineLocalizationUrl` | optional online runtime XML | URL must return parser-compatible XML |
 | `fetchTypeLocalLocalization` | editor import | `None`, `FromGoogleSheets`, or `FromCsv` |
-| `sheetNameFetchLocalLocalization` | local `FromGoogleSheets` | Google Sheet tab name; empty is sent to the fetch executable as `local`; avoid spaces |
+| `sheetNameFetchLocalLocalization` | local `FromGoogleSheets` | Google Sheet tab name; empty is sent to the fetch executable as `local`; avoid spaces |
 | `csvFetchLocalLocalization` | local `FromCsv` | CSV `TextAsset` imported into Unity |
 | `fetchTypeOnlineLocalization` | editor import | `None`, `FromGoogleSheets`, or `FromCsv` |
-| `sheetNameFetchOnlineLocalization` | online `FromGoogleSheets` | Google Sheet tab name; empty is sent to the fetch executable as `online`; avoid spaces |
+| `sheetNameFetchOnlineLocalization` | online `FromGoogleSheets` | Google Sheet tab name; empty is sent to the fetch executable as `online`; avoid spaces |
 | `csvFetchOnlineLocalization` | online `FromCsv` | CSV `TextAsset` imported into Unity |
 | `worksheetKey` | any `FromGoogleSheets` fetch | non-empty Google spreadsheet id/key |
 
-After any `Fetch Localization` run, the editor copies each existing `Local-LocalizationFile/<Language>.xml` file into the matching configured language item's assigned `XML` asset path. Create placeholder XML assets and assign them before fetching. Remove stale `Local-LocalizationFile` outputs before online-only fetches if the assigned local XML assets must not be overwritten.
+After any `Fetch Localization` run, the editor copies each existing `Local-LocalizationFile/<Language>.xml` file into the matching configured language item's assigned `XML` asset path. Create placeholder XML assets and assign them before fetching. Remove stale `Local-LocalizationFile` outputs before online-only fetches if the assigned local XML assets must not be overwritten.
 
 Inspector visibility: `Worksheet Key` is shown only when at least one fetch type is `FromGoogleSheets`. CSV-only import does not require `worksheetKey`.
 
@@ -189,7 +189,7 @@ If both `xmlRef` and `onlineLocalizationUrl` are configured, both async loads ru
 | `XmobiTea Tools/Localization/Open Settings` | creates or selects `Assets/Resources/XmobiTea LocalizationSettings.asset` |
 | `XmobiTea Tools/Localization/Show LocalizationComponentWindows` | opens bulk UI text binding window |
 | `XmobiTea Tools/Localization/Generate LocalizationConstantId.cs` | generates constants from the first language item's local XML |
-| `XmobiTea Tools/Localization/Fetch Localization` | imports local/online XML files from configured editor sources, copies any existing local output files into assigned XML assets, then regenerates constants |
+| `XmobiTea Tools/Localization/Fetch Localization` | imports local/online XML files from configured editor sources, copies any existing local output files into assigned XML assets, then regenerates constants |
 
 Inspector buttons on `LocalizationManager` and `LocalizationSettings` mirror the window, generate, and fetch actions.
 
@@ -276,7 +276,7 @@ Text replacements after XML read:
 - Missing key: `GetText(key)` returns `key`.
 - Empty key: `GetText(key)` returns `key`.
 - Duplicate XML key: logs an error and overwrites with the later value.
-- Missing local XML: local sync load is skipped; optional Addressables or online sources may still update later if configured.
-- Missing first language XML during constant generation: generator can throw while reading or parsing.
-- Missing CSV asset or missing CSV language columns during fetch: editor code can throw before generating XML.
-- Stale `Local-LocalizationFile/<Language>.xml` files can be copied into assigned local XML assets by any later fetch run, including online-only fetches.
+- Missing local XML: local sync load is skipped; optional Addressables or online sources may still update later if configured.
+- Missing first language XML during constant generation: generator can throw while reading or parsing.
+- Missing CSV asset or missing CSV language columns during fetch: editor code can throw before generating XML.
+- Stale `Local-LocalizationFile/<Language>.xml` files can be copied into assigned local XML assets by any later fetch run, including online-only fetches.

package/AI_BEHAVIOR.md

@@ -185,14 +185,14 @@ 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.
+- 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
 
@@ -200,13 +200,13 @@ 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`;
+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.
+Sheet tab names are passed as command-line arguments without quoting. Avoid spaces.
 
 ### FromCsv
 

package/AI_BIND_UI_TEXT.md

@@ -1,97 +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.
+# 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

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