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

package/AGENTS.md

@@ -0,0 +1,67 @@
+# XmobiTea Localization Package Notes
+
+This file defines the usage contract of this package for AI coding agents and maintainers.
+
+## Scope
+
+Applies to everything inside this package folder.
+
+## 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
+
+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:
+
+- 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.

package/AGENTS.md.meta

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

package/AI_USAGE.md

@@ -0,0 +1,96 @@
+# AI Usage Rules For XmobiTea Localization
+
+Use this file when you want to generate code without reading the runtime implementation.
+
+## One-Screen Summary
+
+- Scene `LocalizationManager` required: `Yes`
+- `Resources` settings asset required: `Yes`
+- Main activation call: `LocalizationManager.ChooseLanguage(...)`
+- Text lookup fallback: original key
+- UI auto-refresh event: `LocalizationManager.OnUpdateText`
+- XML local source: `Yes`
+- 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
+
+### Rule 1
+
+Always assume localization is inactive until `ChooseLanguage(...)` is called.
+
+### Rule 2
+
+Always assume `LocalizationManager` must already exist in scene.
+
+### Rule 3
+
+Always assume `LocalizationSettings` must exist in `Resources`.
+
+### Rule 4
+
+Use `LocalizationComponent` for `UnityEngine.UI.Text`.
+
+### Rule 5
+
+Use `TMP_LocalizationComponent` only when TextMesh Pro support is present.
+
+### Rule 6
+
+Treat `GetText(key)` fallback-to-key as normal behavior, not as an exception case.
+
+### Rule 7
+
+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
+using UnityEngine;
+using XmobiTea.MiniLocalization;
+
+public sealed class ExampleLocalizationBootstrap : MonoBehaviour
+{
+	private void Start()
+	{
+		LocalizationManager.ChooseLanguage(SystemLanguage.English);
+	}
+}
+```
+
+```csharp
+using XmobiTea.MiniLocalization;
+
+var title = LocalizationManager.GetText("Home_Title");
+```
+
+## Forbidden AI Assumptions
+
+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,
+- CSV files are read at runtime,
+- fetch type is a boolean — it is a `FetchType` enum.
+
+## Recommended AI Output Style
+
+When generating new code with this package:
+
+- mention manager and settings setup,
+- call out `ChooseLanguage(...)`,
+- prefer generated constants when they are part of the project workflow,
+- keep key-based fallback semantics explicit.

package/AI_USAGE.md.meta

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

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/Editor/CsvParser.cs

@@ -0,0 +1,158 @@
+namespace XmobiTea.MiniLocalization.Editor
+{
+    using System.Collections.Generic;
+    using System.Linq;
+    using System.Text.RegularExpressions;
+    using System.Text;
+    using System;
+
+    public static class CsvParser
+    {
+        public static List<List<string>> ParseFromString(
+            string data,
+            bool hasHeader,
+            bool removeHeader = true)
+        {
+            ConvertToCrlf(ref data);
+
+            var sheet = new List<List<string>>();
+            var row = new List<string>();
+            var cell = new StringBuilder();
+            var insideQuoteCell = false;
+            var start = 0;
+
+            var delimiterSpan = ','.ToString().AsSpan();
+            var crlfSpan = "\r\n".AsSpan();
+            var oneDoubleQuotSpan = "\"".AsSpan();
+            var twoDoubleQuotSpan = "\"\"".AsSpan();
+
+            while (start < data.Length)
+            {
+                var length = start <= data.Length - 2 ? 2 : 1;
+                var span = data.AsSpan(start, length);
+
+                if (span.StartsWith(delimiterSpan))
+                {
+                    if (insideQuoteCell)
+                    {
+                        cell.Append(',');
+                    }
+                    else
+                    {
+                        AddCell(row, cell);
+                    }
+
+                    start += 1;
+                }
+                else if (span.StartsWith(crlfSpan))
+                {
+                    if (insideQuoteCell)
+                    {
+                        cell.Append("\r\n");
+                    }
+                    else
+                    {
+                        AddCell(row, cell);
+
+                        if (IsRowNonEmpty(row))
+                        {
+                            AddRow(sheet, ref row);
+                        }
+                        else
+                        {
+                            row.Clear(); // Reset row if it's just empty
+                        }
+                    }
+
+                    start += 2;
+                }
+                else if (span.StartsWith(twoDoubleQuotSpan))
+                {
+                    cell.Append("\"");
+                    start += 2;
+                }
+                else if (span.StartsWith(oneDoubleQuotSpan))
+                {
+                    insideQuoteCell = !insideQuoteCell;
+                    start += 1;
+                }
+                else
+                {
+                    cell.Append(span[0]);
+                    start += 1;
+                }
+            }
+
+            // Add the last cell
+            if (IsRowNonEmpty(row) || cell.Length > 0)
+            {
+                AddCell(row, cell);
+                AddRow(sheet, ref row);
+            }
+
+            if (hasHeader && removeHeader && sheet.Count > 0)
+            {
+                sheet.RemoveAt(0);
+            }
+
+            if (hasHeader && !removeHeader && sheet.Count == 1)
+            {
+                sheet.Clear();
+            }
+
+            return sheet;
+        }
+
+        private static bool IsRowNonEmpty(List<string> row) =>
+            row.Count > 0 &&
+            row.Any(cell => !string.IsNullOrWhiteSpace(cell));
+
+        private static void AddCell(List<string> row, StringBuilder cell)
+        {
+            row.Add(cell.ToString());
+            cell.Clear();
+        }
+
+        private static void AddRow(List<List<string>> sheet, ref List<string> row)
+        {
+            sheet.Add(new List<string>(row));
+            row.Clear();
+        }
+
+        private static void ConvertToCrlf(ref string data)
+        {
+            data = Regex.Replace(data, @"\r\n|\r|\n", "\r\n");
+        }
+
+        private static object ConvertValue(string value, Type targetType)
+        {
+            if (string.IsNullOrWhiteSpace(value))
+            {
+                if (targetType == typeof(string))
+                    return string.Empty;
+
+                return targetType.IsValueType ? Activator.CreateInstance(targetType) : null;
+            }
+
+            if (targetType == typeof(string))
+                return value;
+
+            if (targetType == typeof(int) || targetType == typeof(int?))
+                return int.TryParse(value, out int intResult) ? intResult : null;
+
+            if (targetType == typeof(decimal) || targetType == typeof(decimal?))
+                return decimal.TryParse(value, out decimal decimalResult) ? decimalResult : null;
+
+            if (targetType == typeof(DateTime) || targetType == typeof(DateTime?))
+                return DateTime.TryParse(value, out DateTime dateResult) ? dateResult : null;
+
+            if (targetType == typeof(bool) || targetType == typeof(bool?))
+                return bool.TryParse(value, out bool boolResult) ? boolResult : null;
+
+            if (targetType == typeof(double) || targetType == typeof(double?))
+                return double.TryParse(value, out double doubleResult) ? doubleResult : null;
+
+            throw new NotSupportedException($"Type {targetType} is not supported for conversion.");
+        }
+    }
+}

package/Editor/CsvParser.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: c44754ba565bc0249ad8400dfd782fbd
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Editor/LocalizationComponentEditor.cs

@@ -1,66 +1,66 @@
-namespace XmobiTea.MiniLocalization.Editor
-{
-    using System.IO;
-    using UnityEditor;
-
-    using UnityEngine;
-
-    [CustomEditor(typeof(LocalizationComponent))]
-    public class LocalizationComponentEditor : Editor
-    {
-        SerializedProperty keyProp;
-        SerializedProperty mainTxtProp;
-
-        private void OnEnable()
-        {
-            keyProp = serializedObject.FindProperty("_key");
-            mainTxtProp = serializedObject.FindProperty("_mainTxt");
-        }
-
-        public override void OnInspectorGUI()
-        {
-            serializedObject.Update();
-
-            EditorGUILayout.PropertyField(mainTxtProp);
-
-            EditorGUILayout.PropertyField(keyProp);
-
-            if (serializedObject.hasModifiedProperties) serializedObject.ApplyModifiedProperties();
-
-            EditorGUILayout.Space(20);
-
-            if (GUILayout.Button("Reload Text"))
-            {
-                var localizationComponentBase = (LocalizationComponentBase)target;
-                localizationComponentBase.OnUpdateText();
-            }
-        }
-
-        [MenuItem("XmobiTea Tools/Localization/Open Settings")]
-        private static void OpenSettings()
-        {
-            var localizationSettings = GetSettings();
-
-            Selection.SetActiveObjectWithContext(localizationSettings, localizationSettings);
-        }
-
-        public static LocalizationSettings GetSettings()
-        {
-            var localizationSettings = Resources.Load<LocalizationSettings>(LocalizationSettings.ResourcesPath);
-            if (localizationSettings == null)
-            {
-                localizationSettings = ScriptableObject.CreateInstance<LocalizationSettings>();
-
-                var dirPath = Application.dataPath + "/Resources";
-                if (!Directory.Exists(dirPath)) Directory.CreateDirectory(dirPath);
-
-                var path = "Assets/Resources/" + LocalizationSettings.ResourcesPath + ".asset";
-                AssetDatabase.CreateAsset(localizationSettings, path);
-
-                Debug.Log("[Localization] Localization Settings create success at path " + path);
-            }
-
-            return localizationSettings;
-        }
-    }
-}
+namespace XmobiTea.MiniLocalization.Editor
+{
+    using System.IO;
+    using UnityEditor;
+
+    using UnityEngine;
+
+    [CustomEditor(typeof(LocalizationComponent))]
+    public class LocalizationComponentEditor : Editor
+    {
+        SerializedProperty keyProp;
+        SerializedProperty mainTxtProp;
+
+        private void OnEnable()
+        {
+            keyProp = serializedObject.FindProperty("_key");
+            mainTxtProp = serializedObject.FindProperty("_mainTxt");
+        }
+
+        public override void OnInspectorGUI()
+        {
+            serializedObject.Update();
+
+            EditorGUILayout.PropertyField(mainTxtProp);
+
+            EditorGUILayout.PropertyField(keyProp);
+
+            if (serializedObject.hasModifiedProperties) serializedObject.ApplyModifiedProperties();
+
+            EditorGUILayout.Space(20);
+
+            if (GUILayout.Button("Reload Text"))
+            {
+                var localizationComponentBase = (LocalizationComponentBase)target;
+                localizationComponentBase.OnUpdateText();
+            }
+        }
+
+        [MenuItem("XmobiTea Tools/Localization/Open Settings")]
+        private static void OpenSettings()
+        {
+            var localizationSettings = GetSettings();
+
+            Selection.SetActiveObjectWithContext(localizationSettings, localizationSettings);
+        }
+
+        public static LocalizationSettings GetSettings()
+        {
+            var localizationSettings = Resources.Load<LocalizationSettings>(LocalizationSettings.ResourcesPath);
+            if (localizationSettings == null)
+            {
+                localizationSettings = ScriptableObject.CreateInstance<LocalizationSettings>();
+
+                var dirPath = Application.dataPath + "/Resources";
+                if (!Directory.Exists(dirPath)) Directory.CreateDirectory(dirPath);
+
+                var path = "Assets/Resources/" + LocalizationSettings.ResourcesPath + ".asset";
+                AssetDatabase.CreateAsset(localizationSettings, path);
+
+                Debug.Log("[Localization] Localization Settings create success at path " + path);
+            }
+
+            return localizationSettings;
+        }
+    }
+}