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

package/AGENTS.md

@@ -1,67 +1,107 @@
-# XmobiTea Localization Package Notes
+# XmobiTea Localization Agent Guide
 
-This file defines the usage contract of this package for AI coding agents and maintainers.
+Scope: everything inside `Assets/XmobiTea Localization`.
 
-## Scope
+## Need-Based Routing
 
-Applies to everything inside this package folder.
+Choose by current need. Open the smallest file that answers it.
 
-## Hard Rules
-
-- `LocalizationManager` is a scene-hosted singleton and must exist before static APIs are used.
-- `LocalizationSettings` must exist in `Resources` under the configured resource path.
-- runtime localization is key-based and dictionary-backed.
-- `ChooseLanguage(...)` is the operation that actually populates the active text dictionary.
-- `GetText(...)` falls back to the original key when translation is missing.
-- UI text updates happen through `LocalizationManager.OnUpdateText`.
-- online localization success clears and rebuilds the active dictionary from the downloaded XML.
-- generated key constants come from editor tooling, not from runtime discovery.
-- `FetchType` controls the editor fetch source: `None`, `FromGoogleSheets`, or `FromCsv`.
-- CSV fetch reads a `TextAsset` assigned in settings, parses it with `CsvParser`, and writes XML files to disk. It does not alter the runtime dictionary directly.
-
-## Required Mental Model
-
-Treat this package as:
-
-- a scene-managed localization system,
-- XML-driven translation storage at runtime,
-- CSV-driven or Google-Sheets-driven fetch workflow in the editor (CSV is converted to XML before being used at runtime),
-- key-based lookup plus UI refresh events,
-- editor-assisted setup and code generation.
-
-Do not treat this package as:
-
-- an auto-configuring localization framework,
-- a strongly typed localization database,
-- a schema-validated content pipeline,
-- a one-shot synchronous load system when addressable or online sources are enabled.
-
-## Correct Usage Pattern
+| Need | Use |
+| --- | --- |
+| Choose localization API or generate common runtime code | `AI_USAGE.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 |
 
-When generating or reviewing code, assume the valid pattern is:
-
-1. Ensure `LocalizationManager` exists in scene.
-2. Ensure `LocalizationSettings` exists in `Resources`.
-3. Configure one or more `LocalizationLanguageItem` entries.
-4. Call `ChooseLanguage(...)` during bootstrap.
-5. Bind UI through localization components or direct `GetText(...)` calls.
-
-## Incorrect Assumptions
-
-These assumptions are false:
-
-- translations are active immediately just because the manager exists.
-- generated constants always exist without editor generation.
-- online localization merges into local localization without replacing it.
-- `GetText(...)` returns null when a key is missing.
-
-## Operational Consequences
-
-If an agent writes code against this package:
+## Hard Rules
 
-- it should mention the need for scene setup and settings asset,
-- it should not assume constants are available unless generation is part of the workflow,
-- it should account for repeated `OnUpdateText` when async sources are enabled,
-- it should document any changed XML or load-order semantics in `README.md`,
-- when describing the fetch workflow, it should distinguish between `FromGoogleSheets` (runs an external executable) and `FromCsv` (reads a `TextAsset` inside the project and converts it to XML),
-- it should never imply that CSV is read at runtime — CSV is an editor-only input format.
+- `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`.
+- 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`
+- `AI_USAGE.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_API_REFERENCE.md

@@ -0,0 +1,281 @@
+# AI API Reference For XmobiTea Localization
+
+Read this only when exact signatures, return values, serialized fields, XML shape, or editor menu names matter. Use `AI_SETUP_LOCALIZATION_MANAGER.md` for manager setup and `AI_SETUP_LOCALIZATION_SETTINGS.md` for settings/import preflight.
+
+Required imports for runtime usage:
+
+```csharp
+using UnityEngine;
+using XmobiTea.MiniLocalization;
+```
+
+Additional import only when code declares `LocalizationLanguageItem` directly:
+
+```csharp
+using XmobiTea.MiniLocalization.Core;
+```
+
+## LocalizationManager API
+
+| Signature | Returns | Use for | Missing manager |
+| --- | --- | --- | --- |
+| `public static bool ChooseLanguage(SystemLanguage systemLanguage)` | `true` on accepted language, otherwise `false` | activate or switch language | logs error and returns `false` |
+| `public static string GetText(string key)` | translated text or original `key` | direct string lookup | returns `key` |
+| `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` | event field | refresh custom state after dictionary updates | no automatic guard |
+
+`ChooseLanguage(...)` returns `false` when the requested `SystemLanguage` is not configured.
+
+`GetAllLanguageItem()` reloads `LocalizationSettings` from `Resources`; it does not return a cached copy from the active language dictionary.
+
+`OnUpdateText` is a public static `Action` field, not a C# `event`. Subscribe with `+=` and unsubscribe with `-=`. Do not assign it with `=` or set it to `null`.
+
+## Component API
+
+| Type | Target | Use for | Key field |
+| --- | --- | --- | --- |
+| `LocalizationComponentBase : MonoBehaviour` | abstract | shared event subscription and key storage | `[LocalizationKey] protected string _key` |
+| `LocalizationComponent : LocalizationComponentBase` | `UnityEngine.UI.Text` | UGUI text binding | `key` property |
+| `TMP_LocalizationComponent : LocalizationComponentBase` | `TMP_Text` | TextMesh Pro binding | `key` property |
+
+`TMP_LocalizationComponent` is compiled only when `UNITY_USING_TMPRO` is defined by the package asmdef version define for `com.unity.textmeshpro`.
+
+`LocalizationComponentBase` exposes:
+
+```csharp
+public string key { get; set; }
+public virtual void OnUpdateText();
+```
+
+Lifecycle behavior:
+
+- `OnEnable()` removes then adds `OnUpdateText` to `LocalizationManager.OnUpdateText`.
+- `OnEnable()` immediately calls `OnUpdateText()`.
+- `OnDisable()` unsubscribes.
+
+`LocalizationComponent` auto-fills its target only in `OnValidate()` when the serialized target is empty and the component sits on the same object as `Text`. The same pattern applies to `TMP_LocalizationComponent`.
+
+## LocalizationSettings API
+
+```csharp
+public enum FetchType
+{
+    None = 0,
+    FromGoogleSheets = 1,
+    FromCsv = 2,
+}
+
+public class LocalizationSettings : ScriptableObject
+{
+    public const string ResourcesPath = "XmobiTea LocalizationSettings";
+    public string worksheetKey { get; }
+    public LocalizationLanguageItem[] localizationLanguageItems { get; }
+    public FetchType fetchTypeLocalLocalization { get; }
+    public string sheetnameFetchLocalLocalization { get; }
+    public TextAsset csvFetchLocalLocalization { get; }
+    public FetchType fetchTypeOnlineLocalization { get; }
+    public string sheetnameFetchOnlineLocalization { get; }
+    public TextAsset csvFetchOnlineLocalization { get; }
+}
+```
+
+Serialized fields in the asset:
+
+| Inspector field | Runtime property | Used by |
+| --- | --- | --- |
+| `_worksheetKey` | `worksheetKey` | editor Google Sheets fetch; required when either fetch type is `FromGoogleSheets` |
+| `_localizationLanguageItems` | `localizationLanguageItems` | runtime language registry |
+| `_fetchTypeLocalLocalization` | `fetchTypeLocalLocalization` | editor local import |
+| `_sheetNameFetchLocalLocalization` | `sheetnameFetchLocalLocalization` | editor Google Sheets local import |
+| `_csvFetchLocalLocalization` | `csvFetchLocalLocalization` | editor CSV local import |
+| `_fetchTypeOnlineLocalization` | `fetchTypeOnlineLocalization` | editor online-file import |
+| `_sheetNameFetchOnlineLocalization` | `sheetnameFetchOnlineLocalization` | editor Google Sheets online import |
+| `_csvFetchOnlineLocalization` | `csvFetchOnlineLocalization` | editor CSV online import |
+
+Default asset path created by `Open Settings`:
+
+```text
+Assets/Resources/XmobiTea LocalizationSettings.asset
+```
+
+Runtime load:
+
+```csharp
+Resources.Load<LocalizationSettings>(LocalizationSettings.ResourcesPath)
+```
+
+## LocalizationSettings Inspector Setup
+
+Use this checklist when generating setup instructions:
+
+| Inspector field | Required when | Value rule |
+| --- | --- | --- |
+| `Localization Language Length` | always | inspector-only size control that resizes `_localizationLanguageItems` |
+| `systemLanguage` | always per language | Unity `SystemLanguage` value |
+| `flagSpr` | optional | display icon only |
+| `xml` | normal runtime local XML | assign an existing XML `TextAsset` asset |
+| `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; avoid spaces |
+| `csvFetchLocalLocalization` | local `FromCsv` | CSV `TextAsset` imported into Unity |
+| `fetchTypeOnlineLocalization` | editor import | `None`, `FromGoogleSheets`, or `FromCsv` |
+| `sheetNameFetchOnlineLocalization` | online `FromGoogleSheets` | Google Sheet tab name; avoid spaces |
+| `csvFetchOnlineLocalization` | online `FromCsv` | CSV `TextAsset` imported into Unity |
+| `worksheetKey` | any `FromGoogleSheets` fetch | non-empty Google spreadsheet id/key |
+
+For local imports, the editor writes fetched content into each configured language item's assigned `XML` asset path. Create placeholder XML assets and assign them before fetching.
+
+Inspector visibility: `Worksheet Key` is shown only when at least one fetch type is `FromGoogleSheets`. CSV-only import does not require `worksheetKey`.
+
+## Import Data Shape
+
+Google Sheet and CSV import use the same column model:
+
+```text
+Key,English,Vietnamese
+Home_Title,Home,Trang chu
+Home_Subtitle,Welcome,Chao mung
+```
+
+Rules:
+
+- first row is header;
+- first column is key;
+- subsequent columns map to `localizationLanguageItems` order;
+- column names should match the intended languages for human clarity;
+- every data row must contain `Key` plus one cell per configured language;
+- empty values generate empty XML text nodes;
+- CSV delimiter is comma.
+
+`Fetch Localization` is editor-only. It converts external data into XML and regenerates constants; runtime reads XML, Addressables XML, or online XML URL only.
+
+## LocalizationLanguageItem API
+
+Namespace:
+
+```csharp
+XmobiTea.MiniLocalization.Core
+```
+
+Shape:
+
+```csharp
+public class LocalizationLanguageItem
+{
+    public SystemLanguage systemLanguage { get; }
+    public Sprite flagSpr { get; }
+    public TextAsset xml { get; set; }
+    public string onlineLocalizationUrl { get; set; }
+}
+```
+
+When Addressables is installed:
+
+```csharp
+public AssetReferenceT<TextAsset> xmlRef { get; set; }
+```
+
+One item can provide local XML, optional Addressables XML, and optional online XML URL for the same language.
+
+If both `xmlRef` and `onlineLocalizationUrl` are configured, both async loads run independently. The callback that finishes later mutates the active dictionary last.
+
+## Editor Menus
+
+| Menu | Effect |
+| --- | --- |
+| `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, then regenerates constants |
+
+Inspector buttons on `LocalizationManager` and `LocalizationSettings` mirror the window, generate, and fetch actions.
+
+## Generated Constants
+
+Runtime package file:
+
+```csharp
+namespace XmobiTea.MiniLocalization
+{
+    public partial class LocalizationConstantId { }
+}
+```
+
+Generated file path:
+
+```text
+Assets/XmobiTea-constant/Scripts/LocalizationConstantId.cs
+```
+
+Generated shape:
+
+```csharp
+namespace XmobiTea.MiniLocalization
+{
+    public partial class LocalizationConstantId
+    {
+        public static readonly string Home_Title = "Home_Title";
+    }
+}
+```
+
+Generator behavior:
+
+- reads only the first configured language item's local XML;
+- converts invalid C# field-name characters to `_`;
+- removes diacritics;
+- prefixes digit-starting names and C# keywords with `_`;
+- logs duplicate generated field names and skips later duplicates.
+
+Generated members are `public static readonly string`, not `const`.
+
+## XML Shape
+
+Runtime parser accepts any root and section tag names as long as the document has the expected node order, keys are two levels below the root, and each key node has a `name` attribute.
+
+Minimal valid XML:
+
+```xml
+<?xml version='1.0' encoding='utf-8'?>
+<English>
+  <section name='Local'>
+    <key name='Home_Title'>Home</key>
+  </section>
+</English>
+```
+
+Parser rules:
+
+- expects the root element at `xmlDoc.ChildNodes.Item(1)`, so generated or hand-authored XML should include the XML declaration;
+- reads `xmlDoc.ChildNodes.Item(1)` as root;
+- loops each section node under root;
+- loops each key node under each section;
+- reads key from `node.Attributes.GetNamedItem("name").Value`;
+- reads text from `node.InnerText`;
+- logs duplicate keys and overwrites with the later value.
+
+Text replacements after XML read:
+
+| Stored text | Runtime text |
+| --- | --- |
+| `\\n` | newline |
+| `&lt;` | `<` |
+| `&gt;` | `>` |
+| `&#38;` | `&` |
+| `&#39;` | `'` |
+| `&#34;` | `"` |
+
+## Error And Fallback Guards
+
+- Missing manager: `ChooseLanguage` returns `false`; `GetText` returns the input key; language getters return `null`.
+- Missing settings during manager init: logs `[Localization] Missing XmobiTea LocalizationSettings` and no language registry is built.
+- Missing language in settings: `ChooseLanguage(...)` logs an error and returns `false`.
+- 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.

package/AI_API_REFERENCE.md.meta

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