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

package/AGENTS.md

@@ -16,13 +16,16 @@ Applies to everything inside this package folder.
 - 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,
+- 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.
 
@@ -59,4 +62,6 @@ If an agent writes code against this package:
 - 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`.
+- 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.

package/AI_USAGE.md

@@ -13,6 +13,8 @@ Use this file when you want to generate code without reading the runtime impleme
 - Addressables optional source: `Yes`
 - Online optional source: `Yes`
 - Generated key constants automatic at runtime: `No`
+- Editor fetch source options: `None`, `FromGoogleSheets`, `FromCsv`
+- CSV is editor-only: parsed to XML by editor tooling, never read at runtime
 
 ## Exact Rules
 
@@ -44,6 +46,14 @@ Treat `GetText(key)` fallback-to-key as normal behavior, not as an exception cas
 
 If online localization is enabled and succeeds, assume it replaces the active dictionary content.
 
+### Rule 8
+
+`FetchType` is an enum with three values: `None`, `FromGoogleSheets`, `FromCsv`. It is set separately for local and online fetch.
+
+### Rule 9
+
+When `FetchType.FromCsv` is active, the editor reads a `TextAsset` CSV assigned in `LocalizationSettings`, converts it to XML, and writes the result to disk. The runtime never reads CSV directly.
+
 ## Safe Code Template
 
 ```csharp
@@ -72,7 +82,9 @@ Do not generate code that assumes:
 - auto-bootstrap of language selection,
 - runtime-generated key constants,
 - null return on missing translation,
-- one single synchronous update when online or addressable sources are involved.
+- one single synchronous update when online or addressable sources are involved,
+- CSV files are read at runtime,
+- fetch type is a boolean — it is a `FetchType` enum.
 
 ## Recommended AI Output Style
 

package/CHANGELOG.md

@@ -3,6 +3,13 @@ All notable changes to this package will be documented in this file.
 
 The format is based on (https://www.npmjs.com/org/xmobitea)
 
+## [Unreleased]
+### Added
+- `FetchType` enum (`None`, `FromGoogleSheets`, `FromCsv`) replacing the previous boolean `usingFetch*` fields in `LocalizationSettings`.
+- `CsvParser` editor utility for parsing RFC-4180 CSV files, including quoted fields and embedded newlines.
+- `csvFetchLocalLocalization` and `csvFetchOnlineLocalization` `TextAsset` fields in `LocalizationSettings` for CSV-based fetch.
+- CSV fetch path in `LocalizationManagerEditor`: reads an assigned CSV asset, converts each language column to XML, and writes output to `Local-LocalizationFile/` or `Online-LocalizationFile/`.
+
 ## [1.0.0] - 2021-04-08
 ### Added
 - This is the first release of Chang X plugins, as a Package

package/README.md

@@ -123,13 +123,16 @@ Loads `LocalizationSettings` again from `Resources` and returns the configured l
 Localization XML is parsed using:
 
 - `XmlDocument`
-- `xmlDoc.ChildNodes.Item(1)`
-- nested section nodes
+- `xmlDoc.ChildNodes.Item(1)` — selects the root element regardless of its tag name
+- nested section nodes — the parser iterates all children of the root, then all children of each section
 - child nodes with attribute `name`
 
-Effective expected shape is:
+The parser does not validate tag names. Both hand-authored XML and editor-generated XML are accepted as long as the nesting is correct.
+
+Hand-authored XML example:
 
 ```xml
+<?xml version='1.0' encoding='utf-8'?>
 <root>
 	<section>
 		<item name="SomeKey">Translated text</item>
@@ -137,6 +140,17 @@ Effective expected shape is:
 </root>
 ```
 
+Editor-generated XML (produced by CSV fetch or key generator) uses the language name as the root tag and `<key>` as the child tag:
+
+```xml
+<?xml version='1.0' encoding='utf-8'?>
+<English>
+	<section name="Local">
+		<key name="SomeKey">Translated text</key>
+	</section>
+</English>
+```
+
 Important behavior:
 
 - key is read from `node.Attributes.GetNamedItem("name").Value`
@@ -163,10 +177,12 @@ It contains:
 
 - `worksheetKey`
 - `localizationLanguageItems`
-- `usingFetchLocalLocalization`
-- `sheetNameFetchLocalLocalization`
-- `usingFetchOnlineLocalization`
-- `sheetNameFetchOnlineLocalization`
+- `fetchTypeLocalLocalization` — `FetchType` enum: `None`, `FromGoogleSheets`, `FromCsv`
+- `sheetNameFetchLocalLocalization` — sheet name used when `FromGoogleSheets`
+- `csvFetchLocalLocalization` — `TextAsset` CSV used when `FromCsv`
+- `fetchTypeOnlineLocalization` — `FetchType` enum: `None`, `FromGoogleSheets`, `FromCsv`
+- `sheetNameFetchOnlineLocalization` — sheet name used when `FromGoogleSheets`
+- `csvFetchOnlineLocalization` — `TextAsset` CSV used when `FromCsv`
 
 These fields are mainly used by editor tooling.
 
@@ -247,25 +263,96 @@ Important behavior:
 
 ## Fetch localization
 
-Editor fetch flow:
+`FetchType` controls where the editor reads source data. Each of local and online can independently set `None`, `FromGoogleSheets`, or `FromCsv`.
+
+### FromGoogleSheets
 
 1. reads settings,
 2. locates a packaged external executable in `Editor/Tools/GetLocalizationTools`,
 3. passes worksheet key, sheet names, and languages as command-line arguments,
-4. expects XML files under `Local-LocalizationFile/<Language>.xml`,
+4. expects XML files written under `Local-LocalizationFile/<Language>.xml` and/or `Online-LocalizationFile/<Language>.xml`,
 5. copies those files into the asset paths referenced by configured `LocalizationLanguageItem.XML`,
 6. refreshes assets,
 7. regenerates `LocalizationConstantId.cs`.
 
-This fetch path is editor tooling behavior, not runtime behavior.
+### FromCsv
+
+1. reads the `TextAsset` CSV assigned to `csvFetchLocalLocalization` or `csvFetchOnlineLocalization` in settings,
+2. parses it with `CsvParser` — first row is a header and is skipped, first column is the key, subsequent columns are language values in the same order as `localizationLanguageItems`,
+3. converts each language column to XML and writes files under `Local-LocalizationFile/<Language>.xml` or `Online-LocalizationFile/<Language>.xml`,
+4. copies those XML files into the asset paths referenced by configured `LocalizationLanguageItem.XML`,
+5. refreshes assets,
+6. regenerates `LocalizationConstantId.cs`.
+
+CSV is always an editor-only input. The runtime never reads CSV files.
+
+Expected CSV layout (columns after key must match the order of `localizationLanguageItems`):
+
+```
+key,English,Vietnamese
+Home_Title,Home,Trang Chủ
+Home_Subtitle,Welcome,Chào Mừng
+```
 
 ## Key picker / scene window
 
-Editor tools provide:
+### Key picker drawer
+
+Every field tagged with `[LocalizationKey]` (used on `_key` in all localization components) renders a custom property drawer in the Inspector:
+
+- **Text field** — the key value can be typed directly.
+- **`▼` dropdown button** — opens an `AdvancedDropdown` listing all string constants from `LocalizationConstantId`. Selecting an entry writes the key to the field.
+- **Red warning label** — appears directly below the field when the current key value is not found in any `LocalizationConstantId` partial class. This indicates the editor generator has not been run or the key was renamed.
+- The available key list is populated by reflecting over all loaded assemblies and is refreshed at most once every 60 seconds.
+
+### LocalizationComponent window
+
+Accessible from:
+
+```text
+XmobiTea Tools/Localization/Show LocalizationComponentWindows
+```
+
+or from the `LocalizationManager` inspector button or the `LocalizationSettings` inspector button.
+
+The window scans UI text objects under a selected parent GameObject and provides controls to add or remove `LocalizationComponent` instances in bulk.
+
+## LocalizationSettings inspector
+
+The `LocalizationSettings` asset has a custom inspector that shows fields conditionally based on the selected `FetchType`.
+
+### Language list
+
+- **Localization Language Length** — integer field that controls the array size of `localizationLanguageItems`. Increase or decrease to add or remove language entries.
+- Each language entry expands to show: `System Language`, `Flag Spr`, local `XML` asset, and (when Addressables is installed) `XMLRef`.
+
+### Local fetch section
+
+- **Fetch Type Local Localization** — enum: `None`, `FromGoogleSheets`, `FromCsv`.
+  - When `FromGoogleSheets`: shows **Sheet Name Fetch Local Localization** field with a hint that the value must not be empty and must not contain spaces.
+  - When `FromCsv`: shows **Csv Fetch Local Localization** (`TextAsset`) field with a hint that the file must not be null and must use `,` as delimiter.
 
-- property drawer dropdown for keys
-- validation message when a key is missing from generated constants
-- a window to scan UI text objects under a selected parent and add/remove localization components
+### Online fetch section
+
+- **Fetch Type Online Localization** — same enum as above with the same conditional fields.
+
+### Shared hints
+
+- When either fetch type is `FromCsv`: the inspector displays a live hint showing the expected CSV column order based on the currently configured languages, for example:
+  ```
+  The column in csv must start at Key, English, Vietnamese
+  ```
+- When either fetch type is `FromGoogleSheets`: shows **Worksheet Key** and a hint about the expected column layout in the Google Sheet.
+
+### Action buttons
+
+Three buttons are available at the bottom of the `LocalizationSettings` inspector (and also from the `LocalizationManager` inspector):
+
+| Button | Action |
+|---|---|
+| `Show LocalizationComponentWindows` | Opens the bulk component assignment window |
+| `Generate LocalizationConstantId.cs` | Parses the first language XML and writes the constants file |
+| `Fetch Localization` | Runs the configured fetch (Google Sheets or CSV) then regenerates constants |
 
 ## Required Setup
 
@@ -280,18 +367,22 @@ Editor tools provide:
 
 ## UI setup
 
-For `UnityEngine.UI.Text`:
+### LocalizationComponent (UnityEngine.UI.Text)
+
+1. Add `LocalizationComponent` to the same GameObject as the `Text` component.
+2. Inspector fields:
+   - **Main Txt** — reference to the `UnityEngine.UI.Text` target. If left empty, it is auto-resolved via `GetComponent<Text>()` at both edit time (`OnValidate`) and at runtime.
+   - **Key** — the localization key. Uses the key picker drawer: type directly or use the `▼` dropdown. A red warning appears if the key is missing from generated constants.
+3. Click **Reload Text** in the inspector to force a text refresh in the editor without entering Play mode.
 
-1. add `LocalizationComponent`
-2. assign or auto-resolve `Text`
-3. set the localization key
+### TMP_LocalizationComponent (TextMesh Pro)
 
-For TMP:
+1. Install the TextMesh Pro package.
+2. Add `TMP_LocalizationComponent` to the same GameObject as the `TMP_Text` component.
+3. Inspector fields match `LocalizationComponent`: **TMP Text** reference and **Key** with the same key picker drawer and warning behavior.
+4. Click **Reload Text** to force a refresh in the editor.
 
-1. install TextMesh Pro
-2. add `TMP_LocalizationComponent`
-3. assign or auto-resolve `TMP_Text`
-4. set the localization key
+Both components subscribe to `LocalizationManager.OnUpdateText` in `OnEnable` and unsubscribe in `OnDisable`. They also call `OnUpdateText()` immediately after subscribing so the correct text appears when the object becomes active.
 
 ## Basic Usage
 
@@ -328,12 +419,66 @@ var text = LocalizationManager.GetText(LocalizationConstantId.Home_Title);
 
 ## React to async updates
 
+`LocalizationManager.OnUpdateText` is a static `Action` that fires each time the active translation dictionary has been rebuilt or updated.
+
+### When it fires
+
+One call to `ChooseLanguage(...)` can cause `OnUpdateText` to fire **more than once**:
+
+| Trigger | Fires? |
+|---|---|
+| Local XML loaded synchronously | Yes — always, at the end of `ChooseLanguage(...)` |
+| Addressables XML loaded (async) | Yes — when the async operation completes, if the language has not changed again |
+| Online XML loaded (async) | Yes — when the HTTP request completes, if the language has not changed again |
+
+For a project that uses only local XML, `OnUpdateText` fires exactly once per `ChooseLanguage(...)` call. For projects that enable addressable or online sources, expect it to fire two or three times.
+
+### When to use it directly vs via LocalizationComponent
+
+Use `LocalizationComponent` / `TMP_LocalizationComponent` for UI text objects — they subscribe and unsubscribe automatically and handle the refresh internally.
+
+Subscribe to `OnUpdateText` directly when you need to refresh non-UI state, for example a data model, a mesh, or custom rendering that depends on localized strings.
+
+### Subscription and unsubscription
+
+Always unsubscribe when the subscriber is destroyed or disabled to avoid calling a method on a dead object:
+
+```csharp
+using UnityEngine;
+using XmobiTea.MiniLocalization;
+
+public sealed class ExampleLocalizationListener : MonoBehaviour
+{
+    void OnEnable()
+    {
+        LocalizationManager.OnUpdateText -= Refresh;
+        LocalizationManager.OnUpdateText += Refresh;
+        Refresh();
+    }
+
+    void OnDisable()
+    {
+        LocalizationManager.OnUpdateText -= Refresh;
+    }
+
+    void Refresh()
+    {
+        var title = LocalizationManager.GetText(LocalizationConstantId.Home_Title);
+        // apply title to non-UI state
+    }
+}
+```
+
+The `-=` before `+=` in `OnEnable` prevents duplicate subscriptions if the object is enabled more than once.
+
+### Minimal example
+
 ```csharp
 using XmobiTea.MiniLocalization;
 
 LocalizationManager.OnUpdateText += () =>
 {
-	UnityEngine.Debug.Log("Localization updated");
+    UnityEngine.Debug.Log("Localization updated");
 };
 ```
 
@@ -454,5 +599,5 @@ com.xmobitea.changx.mini-localization.editor
 ## Package Metadata
 
 - Package name: `com.xmobitea.changx.mini-localization`
-- Unity version: `2020.3+`
+- Unity version: `2022.3+`
 - License: `Apache-2.0`

package/package.json

@@ -1,13 +1,13 @@
 {
     "name": "com.xmobitea.changx.mini-localization",
-    "version": "1.4.10",
+    "version": "1.5.0",
     "displayName": "XmobiTea Localization",
     "description": "XmobiTea Unity Toolkit packages",
-    "unity": "2020.3",
+    "unity": "2022.3",
     "dependencies": {
-        "com.xmobitea.changx.app": "1.4.0",
-        "com.xmobitea.changx.mini-autogenerate": "1.4.0",
-        "com.xmobitea.changx.mini-singleton": "1.4.0"
+        "com.xmobitea.changx.app": "1.5.0",
+        "com.xmobitea.changx.mini-autogenerate": "1.5.0",
+        "com.xmobitea.changx.mini-singleton": "1.5.0"
     },
     "keywords": [
         "chang x",