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

package/AGENTS.md

@@ -1,107 +1,117 @@
-# XmobiTea Localization Agent Guide
-
-Scope: everything inside `Assets/XmobiTea Localization`.
-
-## Need-Based Routing
-
-Choose by current need. Open the smallest file that answers it.
-
+# XmobiTea Localization Agent Guide
+
+Scope: everything inside `Assets/XmobiTea Localization`.
+
+## Need-Based Routing
+
+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` |
-| 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` |
-| Missing or conflicting doc detail | source code |
-
-## Hard Rules
-
-- `LocalizationManager` is a scene-hosted `Singleton<LocalizationManager>`.
-- The package does not auto-create a missing manager.
-- Static APIs require the singleton to initialize first.
-- The conventional host object name is `LocalizationManager`, but runtime depends on the initialized component.
-- Use `XmobiTea.MiniSingleton.DontDestroy` only when later scenes need the same host.
-- Runtime settings lookup key is `XmobiTea LocalizationSettings`; `Open Settings` creates the asset at `Assets/Resources/XmobiTea LocalizationSettings.asset`.
-- `LocalizationSettings.ResourcesPath` is exactly `XmobiTea LocalizationSettings`.
-- `ChooseLanguage(...)` populates the active dictionary.
-- `GetText(...)` falls back to the original key.
-- `LocalizationComponent` targets `UnityEngine.UI.Text`.
-- `TMP_LocalizationComponent` targets `TMP_Text` and exists only with TextMesh Pro support.
-- Fixed labels, titles, descriptions, tabs, and button captions should use localization components.
-- `LocalizationManager.OnUpdateText` is a public static `Action`; subscribe with `+=`/`-=` and never overwrite it.
-- Local XML loads synchronously first.
-- Addressables XML can add/overwrite keys after async load completes.
-- Successful online XML clears and replaces the active dictionary.
-- 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.
+| 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` |
+| Missing or conflicting doc detail | source code |
+
+## Hard Rules
+
+- `LocalizationManager` is a scene-hosted `Singleton<LocalizationManager>`.
+- The package does not auto-create a missing manager.
+- Static APIs require the singleton to initialize first.
+- The conventional host object name is `LocalizationManager`, but runtime depends on the initialized component.
+- Use `XmobiTea.MiniSingleton.DontDestroy` only when later scenes need the same host.
+- Runtime settings lookup key is `XmobiTea LocalizationSettings`; `Open Settings` creates the asset at `Assets/Resources/XmobiTea LocalizationSettings.asset`.
+- `LocalizationSettings.ResourcesPath` is exactly `XmobiTea LocalizationSettings`.
+- `ChooseLanguage(...)` populates the active dictionary.
+- `GetText(...)` falls back to the original key.
+- `LocalizationComponent` targets `UnityEngine.UI.Text`.
+- `TMP_LocalizationComponent` targets `TMP_Text` and exists only with TextMesh Pro support.
+- Fixed labels, titles, descriptions, tabs, and button captions should use localization components.
+- `LocalizationManager.OnUpdateText` is a public static `Action`; subscribe with `+=`/`-=` and never overwrite it.
+- Local XML loads synchronously first.
+- Addressables XML can add/overwrite keys after async load completes.
+- Successful online XML clears and replaces the active dictionary.
+- 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.
-- 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.
-
-## Do Not Assume
-
-- `LocalizationManager` or `LocalizationSettings` will be created at runtime.
-- Translations are active before `ChooseLanguage(...)`.
-- A missing key returns `null`.
-- One language switch means exactly one `OnUpdateText` call.
-- Online XML merges with local XML.
-- CSV or Google Sheets are runtime data sources.
-- Generated constants are type-safe or auto-updated.
-- Keys missing from the first local XML will generate constants.
-- Nonexistent APIs exist: `SetLanguage`, `CurrentLanguage`, `GetLocalizedText`, `ReloadLanguage`, `FormatText`, `HasKey`.
-
-## Code Generation Guidance
-
-- Use `using XmobiTea.MiniLocalization;`.
-- Add `using XmobiTea.MiniLocalization.Core;` only when declaring `LocalizationLanguageItem`.
-- Prefer generated `LocalizationConstantId` values when the generated file exists and is current.
-- Use raw key strings in fresh setups until constants are generated.
-- Put language selection in `Start()` or later unless execution order guarantees manager initialization.
-- Generate scene setup instructions instead of constructing a manager from code.
-- Use `LocalizationComponent` / `TMP_LocalizationComponent` for fixed UI text.
-- Generate custom text refresh code only for dynamic/composed text, non-UI state, or custom rendering.
-- Custom listeners must unsubscribe and must tolerate repeated refreshes.
-- Treat fallback-to-key display as normal runtime behavior.
-- Before using constants, verify the first configured language XML contains the complete key set.
-- Use `Samples~/Example` as the known-good CSV/XML shape.
-
-## Setup Contract
-
-When generated code depends on localization, require:
-
-1. A loaded scene contains one active `LocalizationManager`.
-2. Static APIs run after `LocalizationManager.Awake()`.
-3. A `LocalizationSettings` asset loadable as `Resources.Load<LocalizationSettings>("XmobiTea LocalizationSettings")` exists.
-4. `localizationLanguageItems` contains the requested language.
-5. Runtime language items have local XML unless deliberately online/addressable-only.
-6. Bootstrap calls `ChooseLanguage(...)`.
-7. Fixed UI text uses localization components.
-8. Constants are regenerated after key changes.
-9. Fetch workflows verify assigned CSV assets, local XML targets, Google `worksheetKey`, and complete language columns.
-
-## Maintenance Checklist
-
-If changing resource paths, manager lifecycle, XML parsing, source precedence, generated constants, editor fetch behavior, component binding, or event semantics, update these together:
-
-- `Runtime/LocalizationManager.cs`
-- `Runtime/LocalizationSettings.cs`
-- `Runtime/LocalizationLanguageItem.cs`
-- `Runtime/LocalizationComponent.cs`
-- `Runtime/TMP_LocalizationComponent.cs`
-- `Editor/LocalizationManagerEditor.cs`
-- `Editor/LocalizationSettingsEditor.cs`
-- `Editor/LocalizationKeyDrawer.cs`
+- 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.
+
+## Do Not Assume
+
+- `LocalizationManager` or `LocalizationSettings` will be created at runtime.
+- Translations are active before `ChooseLanguage(...)`.
+- A missing key returns `null`.
+- One language switch means exactly one `OnUpdateText` call.
+- Online XML merges with local XML.
+- CSV or Google Sheets are runtime data sources.
+- Generated constants are type-safe or auto-updated.
+- Keys missing from the first local XML will generate constants.
+- Nonexistent APIs exist: `SetLanguage`, `CurrentLanguage`, `GetLocalizedText`, `ReloadLanguage`, `FormatText`, `HasKey`.
+
+## Code Generation Guidance
+
+- Use `using XmobiTea.MiniLocalization;`.
+- Add `using XmobiTea.MiniLocalization.Core;` only when declaring `LocalizationLanguageItem`.
+- Prefer generated `LocalizationConstantId` values when the generated file exists and is current.
+- Use raw key strings in fresh setups until constants are generated.
+- Put language selection in `Start()` or later unless execution order guarantees manager initialization.
+- Generate scene setup instructions instead of constructing a manager from code.
+- Use `LocalizationComponent` / `TMP_LocalizationComponent` for fixed UI text.
+- Generate custom text refresh code only for dynamic/composed text, non-UI state, or custom rendering.
+- Custom listeners must unsubscribe and must tolerate repeated refreshes.
+- Treat fallback-to-key display as normal runtime behavior.
+- Before using constants, verify the first configured language XML contains the complete key set.
+- Use `Samples~/Example` as the known-good CSV/XML shape.
+
+## Setup Contract
+
+When generated code depends on localization, require:
+
+1. A loaded scene contains one active `LocalizationManager`.
+2. Static APIs run after `LocalizationManager.Awake()`.
+3. A `LocalizationSettings` asset loadable as `Resources.Load<LocalizationSettings>("XmobiTea LocalizationSettings")` exists.
+4. `localizationLanguageItems` contains the requested language.
+5. Runtime language items have local XML unless deliberately online/addressable-only.
+6. Bootstrap calls `ChooseLanguage(...)`.
+7. Fixed UI text uses localization components.
+8. Constants are regenerated after key changes.
+9. Fetch workflows verify assigned CSV assets, local XML targets, Google `worksheetKey`, and complete language columns.
+
+## Maintenance Checklist
+
+If changing resource paths, manager lifecycle, XML parsing, source precedence, generated constants, editor fetch behavior, component binding, or event semantics, update these together:
+
+- `Runtime/LocalizationManager.cs`
+- `Runtime/LocalizationSettings.cs`
+- `Runtime/LocalizationLanguageItem.cs`
+- `Runtime/LocalizationComponent.cs`
+- `Runtime/TMP_LocalizationComponent.cs`
+- `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_API_REFERENCE.md`
-- `AI_BEHAVIOR.md`
-- `README.md`
+- `AI_API_REFERENCE.md`
+- `AI_BEHAVIOR.md`
+- `README.md`

package/AI_ADD_LOCALIZATION_KEY.md

@@ -0,0 +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.

package/AI_ADD_LOCALIZATION_KEY.md.meta

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