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

package/AI_API_REFERENCE.md

@@ -1,281 +1,282 @@
-# 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.
+# 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` | static `Action` 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; 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 |
+| `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.
+
+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, 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.
+
+## 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.
+- 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_API_REFERENCE.md.meta

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