com.xmobitea.changx.mini-localization 1.5.2 → 1.5.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +23 -23
- package/AI_ADD_LOCALIZATION_KEY.md +78 -78
- package/AI_ADD_LOCALIZATION_KEY.md.meta +7 -7
- package/AI_API_REFERENCE.md +9 -9
- package/AI_BEHAVIOR.md +10 -10
- package/AI_BIND_UI_TEXT.md +97 -97
- package/AI_BIND_UI_TEXT.md.meta +7 -7
- package/AI_IMPORT_TRANSLATIONS.md +84 -84
- package/AI_IMPORT_TRANSLATIONS.md.meta +7 -7
- package/AI_SETUP.md +10 -10
- package/AI_SETUP_LOCALIZATION_MANAGER.md +6 -6
- package/AI_SETUP_LOCALIZATION_SETTINGS.md +22 -22
- package/AI_SWITCH_LANGUAGE.md +107 -107
- package/AI_SWITCH_LANGUAGE.md.meta +7 -7
- package/AI_USAGE.md +18 -18
- package/CHANGELOG.md +9 -4
- package/Editor/KeyUsageAnalyzerWindowsEditor.cs +884 -0
- package/Editor/KeyUsageAnalyzerWindowsEditor.cs.meta +11 -0
- package/Editor/LocalizationComponentEditor.cs +0 -28
- package/Editor/LocalizationComponentWindowsEditor.cs +1 -1
- package/Editor/LocalizationManagerEditor.cs +2 -2
- package/Editor/TMP_LocalizationComponentEditor.cs +0 -28
- package/README.md +24 -24
- package/Runtime/LocalizationManager.cs +3 -3
- package/package.json +1 -1
|
@@ -1,84 +1,84 @@
|
|
|
1
|
-
# AI Import Translations
|
|
2
|
-
|
|
3
|
-
Use this when translations come from CSV or Google Sheets, or when XML files must be regenerated through editor tooling.
|
|
4
|
-
|
|
5
|
-
## Runtime Rule
|
|
6
|
-
|
|
7
|
-
- runtime never reads CSV or Google Sheets;
|
|
8
|
-
- `Fetch Localization` is editor-only;
|
|
9
|
-
- fetch converts external data into XML and then regenerates `LocalizationConstantId.cs`.
|
|
10
|
-
|
|
11
|
-
## CSV Import
|
|
12
|
-
|
|
13
|
-
Checklist:
|
|
14
|
-
|
|
15
|
-
- import the CSV into Unity as a `TextAsset`;
|
|
16
|
-
- configure `localizationLanguageItems` in the same order as CSV language columns;
|
|
17
|
-
- assign a local XML `TextAsset` to every runtime language item;
|
|
18
|
-
- set `Fetch Type Local Localization` to `FromCsv` when generating local XML;
|
|
19
|
-
- assign `Csv Fetch Local Localization`;
|
|
20
|
-
- set `Fetch Type Online Localization` to `FromCsv` only when generating online XML too;
|
|
21
|
-
- assign `Csv Fetch Online Localization` when online fetch uses CSV;
|
|
22
|
-
- run `XmobiTea Tools/Localization/Fetch Localization`.
|
|
23
|
-
|
|
24
|
-
CSV shape:
|
|
25
|
-
|
|
26
|
-
```text
|
|
27
|
-
Key,English,Vietnamese
|
|
28
|
-
Home_Title,Home,Trang chu
|
|
29
|
-
Home_Subtitle,Welcome,Chao mung
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
Rules:
|
|
33
|
-
|
|
34
|
-
- delimiter is comma;
|
|
35
|
-
- first row is header and is skipped;
|
|
36
|
-
- first column is key;
|
|
37
|
-
- every row must have one cell per configured language;
|
|
38
|
-
- use empty cells for blank translations instead of shortening rows.
|
|
39
|
-
|
|
40
|
-
## Google Sheets Import
|
|
41
|
-
|
|
42
|
-
Checklist:
|
|
43
|
-
|
|
44
|
-
- put the spreadsheet id/key in `worksheetKey`;
|
|
45
|
-
- configure `localizationLanguageItems` in the same order as sheet language columns;
|
|
46
|
-
- assign a local XML `TextAsset` to every runtime language item;
|
|
47
|
-
- set `Fetch Type Local Localization` to `FromGoogleSheets` when generating local XML;
|
|
48
|
-
- set `Sheet Name Fetch Local Localization`; empty uses the default executable argument `local`;
|
|
49
|
-
- set `Fetch Type Online Localization` to `FromGoogleSheets` only when generating online XML too;
|
|
50
|
-
- set `Sheet Name Fetch Online Localization` when online fetch uses Google Sheets; empty uses the default executable argument `online`;
|
|
51
|
-
- keep explicit sheet names without spaces;
|
|
52
|
-
- run `XmobiTea Tools/Localization/Fetch Localization`.
|
|
53
|
-
|
|
54
|
-
## Outputs
|
|
55
|
-
|
|
56
|
-
- generated local XML is copied into each assigned local `xml` asset;
|
|
57
|
-
- generated online XML is written under `Online-LocalizationFile/<Language>.xml`;
|
|
58
|
-
- runtime online loading still requires hosting those XML files and assigning `onlineLocalizationUrl`.
|
|
59
|
-
- after any fetch run, existing `Local-LocalizationFile/<Language>.xml` files are copied into assigned local `xml` assets, even if only online output was requested. Remove stale local output files first when local XML must stay unchanged.
|
|
60
|
-
|
|
61
|
-
## When To Regenerate Constants Only
|
|
62
|
-
|
|
63
|
-
Run this instead of full fetch when XML is already up to date and only keys changed:
|
|
64
|
-
|
|
65
|
-
```text
|
|
66
|
-
XmobiTea Tools/Localization/Generate LocalizationConstantId.cs
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
## Common Failures
|
|
70
|
-
|
|
71
|
-
| Symptom | Likely cause | Fix |
|
|
72
|
-
| --- | --- | --- |
|
|
73
|
-
| fetch fails for Google Sheets | empty `worksheetKey` | set the spreadsheet id/key |
|
|
74
|
-
| XML generated for wrong language | language order does not match CSV or Sheet columns | reorder `localizationLanguageItems` or source columns |
|
|
75
|
-
| local XML changes during online-only fetch | stale `Local-LocalizationFile/<Language>.xml` exists | remove stale local output files before fetching |
|
|
76
|
-
| online XML never used at runtime | `onlineLocalizationUrl` is empty | host the generated XML and set the URL |
|
|
77
|
-
| constants missing keys after fetch | first configured local XML is incomplete | fix first local XML and regenerate constants |
|
|
78
|
-
|
|
79
|
-
## Hard No
|
|
80
|
-
|
|
81
|
-
- Do not claim CSV or Google Sheets are runtime sources.
|
|
82
|
-
- Do not skip assigning local XML assets when local XML output is expected.
|
|
83
|
-
- Do not shorten translation rows when one language is blank.
|
|
84
|
-
- Do not forget that fetch menu actions are editor-only entrypoints.
|
|
1
|
+
# AI Import Translations
|
|
2
|
+
|
|
3
|
+
Use this when translations come from CSV or Google Sheets, or when XML files must be regenerated through editor tooling.
|
|
4
|
+
|
|
5
|
+
## Runtime Rule
|
|
6
|
+
|
|
7
|
+
- runtime never reads CSV or Google Sheets;
|
|
8
|
+
- `Fetch Localization` is editor-only;
|
|
9
|
+
- fetch converts external data into XML and then regenerates `LocalizationConstantId.cs`.
|
|
10
|
+
|
|
11
|
+
## CSV Import
|
|
12
|
+
|
|
13
|
+
Checklist:
|
|
14
|
+
|
|
15
|
+
- import the CSV into Unity as a `TextAsset`;
|
|
16
|
+
- configure `localizationLanguageItems` in the same order as CSV language columns;
|
|
17
|
+
- assign a local XML `TextAsset` to every runtime language item;
|
|
18
|
+
- set `Fetch Type Local Localization` to `FromCsv` when generating local XML;
|
|
19
|
+
- assign `Csv Fetch Local Localization`;
|
|
20
|
+
- set `Fetch Type Online Localization` to `FromCsv` only when generating online XML too;
|
|
21
|
+
- assign `Csv Fetch Online Localization` when online fetch uses CSV;
|
|
22
|
+
- run `XmobiTea Tools/Localization/Fetch Localization`.
|
|
23
|
+
|
|
24
|
+
CSV shape:
|
|
25
|
+
|
|
26
|
+
```text
|
|
27
|
+
Key,English,Vietnamese
|
|
28
|
+
Home_Title,Home,Trang chu
|
|
29
|
+
Home_Subtitle,Welcome,Chao mung
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Rules:
|
|
33
|
+
|
|
34
|
+
- delimiter is comma;
|
|
35
|
+
- first row is header and is skipped;
|
|
36
|
+
- first column is key;
|
|
37
|
+
- every row must have one cell per configured language;
|
|
38
|
+
- use empty cells for blank translations instead of shortening rows.
|
|
39
|
+
|
|
40
|
+
## Google Sheets Import
|
|
41
|
+
|
|
42
|
+
Checklist:
|
|
43
|
+
|
|
44
|
+
- put the spreadsheet id/key in `worksheetKey`;
|
|
45
|
+
- configure `localizationLanguageItems` in the same order as sheet language columns;
|
|
46
|
+
- assign a local XML `TextAsset` to every runtime language item;
|
|
47
|
+
- set `Fetch Type Local Localization` to `FromGoogleSheets` when generating local XML;
|
|
48
|
+
- set `Sheet Name Fetch Local Localization`; empty uses the default executable argument `local`;
|
|
49
|
+
- set `Fetch Type Online Localization` to `FromGoogleSheets` only when generating online XML too;
|
|
50
|
+
- set `Sheet Name Fetch Online Localization` when online fetch uses Google Sheets; empty uses the default executable argument `online`;
|
|
51
|
+
- keep explicit sheet names without spaces;
|
|
52
|
+
- run `XmobiTea Tools/Localization/Fetch Localization`.
|
|
53
|
+
|
|
54
|
+
## Outputs
|
|
55
|
+
|
|
56
|
+
- generated local XML is copied into each assigned local `xml` asset;
|
|
57
|
+
- generated online XML is written under `Online-LocalizationFile/<Language>.xml`;
|
|
58
|
+
- runtime online loading still requires hosting those XML files and assigning `onlineLocalizationUrl`.
|
|
59
|
+
- after any fetch run, existing `Local-LocalizationFile/<Language>.xml` files are copied into assigned local `xml` assets, even if only online output was requested. Remove stale local output files first when local XML must stay unchanged.
|
|
60
|
+
|
|
61
|
+
## When To Regenerate Constants Only
|
|
62
|
+
|
|
63
|
+
Run this instead of full fetch when XML is already up to date and only keys changed:
|
|
64
|
+
|
|
65
|
+
```text
|
|
66
|
+
XmobiTea Tools/Localization/Generate LocalizationConstantId.cs
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Common Failures
|
|
70
|
+
|
|
71
|
+
| Symptom | Likely cause | Fix |
|
|
72
|
+
| --- | --- | --- |
|
|
73
|
+
| fetch fails for Google Sheets | empty `worksheetKey` | set the spreadsheet id/key |
|
|
74
|
+
| XML generated for wrong language | language order does not match CSV or Sheet columns | reorder `localizationLanguageItems` or source columns |
|
|
75
|
+
| local XML changes during online-only fetch | stale `Local-LocalizationFile/<Language>.xml` exists | remove stale local output files before fetching |
|
|
76
|
+
| online XML never used at runtime | `onlineLocalizationUrl` is empty | host the generated XML and set the URL |
|
|
77
|
+
| constants missing keys after fetch | first configured local XML is incomplete | fix first local XML and regenerate constants |
|
|
78
|
+
|
|
79
|
+
## Hard No
|
|
80
|
+
|
|
81
|
+
- Do not claim CSV or Google Sheets are runtime sources.
|
|
82
|
+
- Do not skip assigning local XML assets when local XML output is expected.
|
|
83
|
+
- Do not shorten translation rows when one language is blank.
|
|
84
|
+
- Do not forget that fetch menu actions are editor-only entrypoints.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
fileFormatVersion: 2
|
|
2
|
-
guid: b1ae3ea4769d478b93068a586c538744
|
|
3
|
-
TextScriptImporter:
|
|
4
|
-
externalObjects: {}
|
|
5
|
-
userData:
|
|
6
|
-
assetBundleName:
|
|
7
|
-
assetBundleVariant:
|
|
1
|
+
fileFormatVersion: 2
|
|
2
|
+
guid: b1ae3ea4769d478b93068a586c538744
|
|
3
|
+
TextScriptImporter:
|
|
4
|
+
externalObjects: {}
|
|
5
|
+
userData:
|
|
6
|
+
assetBundleName:
|
|
7
|
+
assetBundleVariant:
|
package/AI_SETUP.md
CHANGED
|
@@ -4,16 +4,16 @@ Use this file only as a setup router. Open the specific setup file below.
|
|
|
4
4
|
|
|
5
5
|
## Setup Routing
|
|
6
6
|
|
|
7
|
-
| Need | Use |
|
|
8
|
-
| --- | --- |
|
|
9
|
-
| Scene object, singleton timing, bootstrap call, persistent manager | `AI_SETUP_LOCALIZATION_MANAGER.md` |
|
|
10
|
-
| Settings asset, language items, XML shape, CSV/Google import, constants | `AI_SETUP_LOCALIZATION_SETTINGS.md` |
|
|
11
|
-
| Switch runtime language after setup | `AI_SWITCH_LANGUAGE.md` |
|
|
12
|
-
| Bind fixed UI text | `AI_BIND_UI_TEXT.md` |
|
|
13
|
-
| Add, rename, or remove a localization key | `AI_ADD_LOCALIZATION_KEY.md` |
|
|
14
|
-
| Import translations from CSV or Google Sheets | `AI_IMPORT_TRANSLATIONS.md` |
|
|
15
|
-
| Choose runtime API after setup | `AI_USAGE.md` |
|
|
16
|
-
| Lifecycle/source precedence edge cases | `AI_BEHAVIOR.md` |
|
|
7
|
+
| Need | Use |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| Scene object, singleton timing, bootstrap call, persistent manager | `AI_SETUP_LOCALIZATION_MANAGER.md` |
|
|
10
|
+
| Settings asset, language items, XML shape, CSV/Google import, constants | `AI_SETUP_LOCALIZATION_SETTINGS.md` |
|
|
11
|
+
| Switch runtime language after setup | `AI_SWITCH_LANGUAGE.md` |
|
|
12
|
+
| Bind fixed UI text | `AI_BIND_UI_TEXT.md` |
|
|
13
|
+
| Add, rename, or remove a localization key | `AI_ADD_LOCALIZATION_KEY.md` |
|
|
14
|
+
| Import translations from CSV or Google Sheets | `AI_IMPORT_TRANSLATIONS.md` |
|
|
15
|
+
| Choose runtime API after setup | `AI_USAGE.md` |
|
|
16
|
+
| Lifecycle/source precedence edge cases | `AI_BEHAVIOR.md` |
|
|
17
17
|
|
|
18
18
|
## Minimal Runtime Contract
|
|
19
19
|
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# AI Setup LocalizationManager
|
|
2
2
|
|
|
3
|
-
Use this when a task mentions scene setup, singleton timing, bootstrapping language selection, persistent localization, UI text binding timing, or `[Localization] LocalizationManager instance is null!`.
|
|
4
|
-
|
|
5
|
-
Open smaller task files when setup is already done:
|
|
6
|
-
|
|
7
|
-
- `AI_SWITCH_LANGUAGE.md` for switching runtime language;
|
|
8
|
-
- `AI_BIND_UI_TEXT.md` for binding fixed UI text.
|
|
3
|
+
Use this when a task mentions scene setup, singleton timing, bootstrapping language selection, persistent localization, UI text binding timing, or `[Localization] LocalizationManager instance is null!`.
|
|
4
|
+
|
|
5
|
+
Open smaller task files when setup is already done:
|
|
6
|
+
|
|
7
|
+
- `AI_SWITCH_LANGUAGE.md` for switching runtime language;
|
|
8
|
+
- `AI_BIND_UI_TEXT.md` for binding fixed UI text.
|
|
9
9
|
|
|
10
10
|
## Required Imports
|
|
11
11
|
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# AI Setup LocalizationSettings
|
|
2
2
|
|
|
3
|
-
Use this when a task mentions `LocalizationSettings`, language items, XML files, CSV import, Google Sheets import, generated constants, settings asset path, missing keys, or editor menu actions.
|
|
4
|
-
|
|
5
|
-
Open smaller task files when the settings asset already exists:
|
|
6
|
-
|
|
7
|
-
- `AI_ADD_LOCALIZATION_KEY.md` for adding, renaming, or removing keys;
|
|
8
|
-
- `AI_IMPORT_TRANSLATIONS.md` for CSV or Google Sheets import;
|
|
9
|
-
- `AI_SWITCH_LANGUAGE.md` for runtime switching after setup.
|
|
3
|
+
Use this when a task mentions `LocalizationSettings`, language items, XML files, CSV import, Google Sheets import, generated constants, settings asset path, missing keys, or editor menu actions.
|
|
4
|
+
|
|
5
|
+
Open smaller task files when the settings asset already exists:
|
|
6
|
+
|
|
7
|
+
- `AI_ADD_LOCALIZATION_KEY.md` for adding, renaming, or removing keys;
|
|
8
|
+
- `AI_IMPORT_TRANSLATIONS.md` for CSV or Google Sheets import;
|
|
9
|
+
- `AI_SWITCH_LANGUAGE.md` for runtime switching after setup.
|
|
10
10
|
|
|
11
11
|
## Settings Contract
|
|
12
12
|
|
|
@@ -149,11 +149,11 @@ Checklist:
|
|
|
149
149
|
- Put the Google spreadsheet id/key in `worksheetKey`.
|
|
150
150
|
- Configure `localizationLanguageItems` in the same order as sheet language columns.
|
|
151
151
|
- Assign a local XML `TextAsset` to every language item.
|
|
152
|
-
- Set `fetchTypeLocalLocalization` to `FromGoogleSheets` when generating local XML.
|
|
153
|
-
- Set `sheetNameFetchLocalLocalization` to the local sheet tab name. If left empty, the fetch executable receives `local`.
|
|
154
|
-
- Set `fetchTypeOnlineLocalization` to `FromGoogleSheets` only when generating online XML files too.
|
|
155
|
-
- Set `sheetNameFetchOnlineLocalization` to the online sheet tab name. If left empty, the fetch executable receives `online`.
|
|
156
|
-
- Keep explicit sheet tab names without spaces because they are passed to the executable without quoting.
|
|
152
|
+
- Set `fetchTypeLocalLocalization` to `FromGoogleSheets` when generating local XML.
|
|
153
|
+
- Set `sheetNameFetchLocalLocalization` to the local sheet tab name. If left empty, the fetch executable receives `local`.
|
|
154
|
+
- Set `fetchTypeOnlineLocalization` to `FromGoogleSheets` only when generating online XML files too.
|
|
155
|
+
- Set `sheetNameFetchOnlineLocalization` to the online sheet tab name. If left empty, the fetch executable receives `online`.
|
|
156
|
+
- Keep explicit sheet tab names without spaces because they are passed to the executable without quoting.
|
|
157
157
|
- Run `XmobiTea Tools/Localization/Fetch Localization`.
|
|
158
158
|
|
|
159
159
|
Sheet shape:
|
|
@@ -166,11 +166,11 @@ Home_Subtitle,Welcome,Chao mung
|
|
|
166
166
|
|
|
167
167
|
Notes:
|
|
168
168
|
|
|
169
|
-
- Google Sheets import uses bundled editor executables under `Editor/Tools/GetLocalizationTools`.
|
|
170
|
-
- Generated local XML files are copied into each assigned `XML` asset.
|
|
171
|
-
- Generated online XML files are written under `Online-LocalizationFile/<Language>.xml`.
|
|
172
|
-
- Runtime online loading still requires hosting those XML files and setting `Online Localization Url`.
|
|
173
|
-
- After every fetch run, any existing `Local-LocalizationFile/<Language>.xml` file is copied into the assigned local `XML` asset, even for online-only fetches. Delete stale local output files first if local XML should not change.
|
|
169
|
+
- Google Sheets import uses bundled editor executables under `Editor/Tools/GetLocalizationTools`.
|
|
170
|
+
- Generated local XML files are copied into each assigned `XML` asset.
|
|
171
|
+
- Generated online XML files are written under `Online-LocalizationFile/<Language>.xml`.
|
|
172
|
+
- Runtime online loading still requires hosting those XML files and setting `Online Localization Url`.
|
|
173
|
+
- After every fetch run, any existing `Local-LocalizationFile/<Language>.xml` file is copied into the assigned local `XML` asset, even for online-only fetches. Delete stale local output files first if local XML should not change.
|
|
174
174
|
|
|
175
175
|
## Editor Menu Entrypoints
|
|
176
176
|
|
|
@@ -179,7 +179,7 @@ Notes:
|
|
|
179
179
|
| `XmobiTea Tools/Localization/Open Settings` | create/select settings asset |
|
|
180
180
|
| `XmobiTea Tools/Localization/Show LocalizationComponentWindows` | bulk add/remove text binding components |
|
|
181
181
|
| `XmobiTea Tools/Localization/Generate LocalizationConstantId.cs` | generate key constants from first language XML |
|
|
182
|
-
| `XmobiTea Tools/Localization/Fetch Localization` | import XML from configured CSV or Google Sheets source, copy existing local output files into assigned XML assets, then regenerate constants |
|
|
182
|
+
| `XmobiTea Tools/Localization/Fetch Localization` | import XML from configured CSV or Google Sheets source, copy existing local output files into assigned XML assets, then regenerate constants |
|
|
183
183
|
|
|
184
184
|
These are editor-only entrypoints. Runtime code should not call editor APIs.
|
|
185
185
|
|
|
@@ -193,7 +193,7 @@ If an MCP Unity server can invoke Unity editor menu items, use these exact menu
|
|
|
193
193
|
| `ChooseLanguage(...)` returns `false` for a language | language not configured | add matching `LocalizationLanguageItem` |
|
|
194
194
|
| UI shows raw keys after language selection | key missing or XML missing | verify XML assignment and key |
|
|
195
195
|
| constants missing a key | first configured language XML lacks the key | update first XML and regenerate |
|
|
196
|
-
| CSV fetch throws | missing CSV asset or missing language columns | assign CSV and complete all columns |
|
|
197
|
-
| Google fetch logs missing `worksheetKey` | a Google fetch type is selected with empty key | set spreadsheet id/key |
|
|
198
|
-
| local XML changes during online-only fetch | stale `Local-LocalizationFile/<Language>.xml` exists | remove stale local output files before fetching |
|
|
199
|
-
| online XML generated but not used | URL field not set to hosted XML | host XML and set `Online Localization Url` |
|
|
196
|
+
| CSV fetch throws | missing CSV asset or missing language columns | assign CSV and complete all columns |
|
|
197
|
+
| Google fetch logs missing `worksheetKey` | a Google fetch type is selected with empty key | set spreadsheet id/key |
|
|
198
|
+
| local XML changes during online-only fetch | stale `Local-LocalizationFile/<Language>.xml` exists | remove stale local output files before fetching |
|
|
199
|
+
| online XML generated but not used | URL field not set to hosted XML | host XML and set `Online Localization Url` |
|
package/AI_SWITCH_LANGUAGE.md
CHANGED
|
@@ -1,107 +1,107 @@
|
|
|
1
|
-
# AI Switch Language
|
|
2
|
-
|
|
3
|
-
Use this when a task needs to choose a startup language, switch language from UI, read the current language, or refresh custom non-UI state after a language change.
|
|
4
|
-
|
|
5
|
-
## Required State
|
|
6
|
-
|
|
7
|
-
- one active initialized `LocalizationManager`;
|
|
8
|
-
- a `LocalizationSettings` asset loadable as `Resources.Load<LocalizationSettings>("XmobiTea LocalizationSettings")`;
|
|
9
|
-
- target `SystemLanguage` exists in `localizationLanguageItems`;
|
|
10
|
-
- fixed UI text already uses localization components when possible.
|
|
11
|
-
|
|
12
|
-
## Switch Language
|
|
13
|
-
|
|
14
|
-
```csharp
|
|
15
|
-
LocalizationManager.ChooseLanguage(SystemLanguage.English);
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
Rules:
|
|
19
|
-
|
|
20
|
-
- call from `Start()` or later unless script execution order guarantees manager init;
|
|
21
|
-
- return value `false` means the manager is missing or the language is not configured;
|
|
22
|
-
- local XML applies immediately;
|
|
23
|
-
- Addressables XML and online XML can trigger later refreshes for the same switch;
|
|
24
|
-
- `OnUpdateText` can fire more than once for one `ChooseLanguage(...)` call.
|
|
25
|
-
|
|
26
|
-
## Startup Bootstrap
|
|
27
|
-
|
|
28
|
-
```csharp
|
|
29
|
-
using UnityEngine;
|
|
30
|
-
using XmobiTea.MiniLocalization;
|
|
31
|
-
|
|
32
|
-
public sealed class LocalizationBootstrap : MonoBehaviour
|
|
33
|
-
{
|
|
34
|
-
[SerializeField] private SystemLanguage startupLanguage = SystemLanguage.English;
|
|
35
|
-
|
|
36
|
-
private void Start()
|
|
37
|
-
{
|
|
38
|
-
LocalizationManager.ChooseLanguage(startupLanguage);
|
|
39
|
-
}
|
|
40
|
-
}
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
## Switch From UI
|
|
44
|
-
|
|
45
|
-
```csharp
|
|
46
|
-
public void UseVietnamese()
|
|
47
|
-
{
|
|
48
|
-
LocalizationManager.ChooseLanguage(SystemLanguage.Vietnamese);
|
|
49
|
-
}
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
Use the return value when UI should show failure:
|
|
53
|
-
|
|
54
|
-
```csharp
|
|
55
|
-
bool changed = LocalizationManager.ChooseLanguage(SystemLanguage.Vietnamese);
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
## Read Current And Available Languages
|
|
59
|
-
|
|
60
|
-
```csharp
|
|
61
|
-
var current = LocalizationManager.GetCurrentLanguage();
|
|
62
|
-
var allLanguages = LocalizationManager.GetAllLanguageItem();
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
Rules:
|
|
66
|
-
|
|
67
|
-
- `GetCurrentLanguage()` returns `null` and logs when the manager is missing;
|
|
68
|
-
- `GetAllLanguageItem()` reloads from `LocalizationSettings`;
|
|
69
|
-
- use `LocalizationLanguageItem.flagSpr` only as display data, not as runtime identity.
|
|
70
|
-
|
|
71
|
-
## Refresh Custom Non-UI State
|
|
72
|
-
|
|
73
|
-
Use this only when localization components cannot bind the target directly.
|
|
74
|
-
|
|
75
|
-
```csharp
|
|
76
|
-
using UnityEngine;
|
|
77
|
-
using XmobiTea.MiniLocalization;
|
|
78
|
-
|
|
79
|
-
public sealed class LocalizedTitleCache : MonoBehaviour
|
|
80
|
-
{
|
|
81
|
-
public string Title { get; private set; }
|
|
82
|
-
|
|
83
|
-
private void OnEnable()
|
|
84
|
-
{
|
|
85
|
-
LocalizationManager.OnUpdateText -= Refresh;
|
|
86
|
-
LocalizationManager.OnUpdateText += Refresh;
|
|
87
|
-
Refresh();
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
private void OnDisable()
|
|
91
|
-
{
|
|
92
|
-
LocalizationManager.OnUpdateText -= Refresh;
|
|
93
|
-
}
|
|
94
|
-
|
|
95
|
-
private void Refresh()
|
|
96
|
-
{
|
|
97
|
-
Title = LocalizationManager.GetText("Home_Title");
|
|
98
|
-
}
|
|
99
|
-
}
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
## Hard No
|
|
103
|
-
|
|
104
|
-
- Do not call localization static APIs from another component `Awake()` without an execution-order guarantee.
|
|
105
|
-
- Do not assume one language switch means one refresh event.
|
|
106
|
-
- Do not overwrite `LocalizationManager.OnUpdateText` with `=` or `null`.
|
|
107
|
-
- Do not manually refresh fixed `Text` or `TMP_Text` when localization components can bind the key.
|
|
1
|
+
# AI Switch Language
|
|
2
|
+
|
|
3
|
+
Use this when a task needs to choose a startup language, switch language from UI, read the current language, or refresh custom non-UI state after a language change.
|
|
4
|
+
|
|
5
|
+
## Required State
|
|
6
|
+
|
|
7
|
+
- one active initialized `LocalizationManager`;
|
|
8
|
+
- a `LocalizationSettings` asset loadable as `Resources.Load<LocalizationSettings>("XmobiTea LocalizationSettings")`;
|
|
9
|
+
- target `SystemLanguage` exists in `localizationLanguageItems`;
|
|
10
|
+
- fixed UI text already uses localization components when possible.
|
|
11
|
+
|
|
12
|
+
## Switch Language
|
|
13
|
+
|
|
14
|
+
```csharp
|
|
15
|
+
LocalizationManager.ChooseLanguage(SystemLanguage.English);
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Rules:
|
|
19
|
+
|
|
20
|
+
- call from `Start()` or later unless script execution order guarantees manager init;
|
|
21
|
+
- return value `false` means the manager is missing or the language is not configured;
|
|
22
|
+
- local XML applies immediately;
|
|
23
|
+
- Addressables XML and online XML can trigger later refreshes for the same switch;
|
|
24
|
+
- `OnUpdateText` can fire more than once for one `ChooseLanguage(...)` call.
|
|
25
|
+
|
|
26
|
+
## Startup Bootstrap
|
|
27
|
+
|
|
28
|
+
```csharp
|
|
29
|
+
using UnityEngine;
|
|
30
|
+
using XmobiTea.MiniLocalization;
|
|
31
|
+
|
|
32
|
+
public sealed class LocalizationBootstrap : MonoBehaviour
|
|
33
|
+
{
|
|
34
|
+
[SerializeField] private SystemLanguage startupLanguage = SystemLanguage.English;
|
|
35
|
+
|
|
36
|
+
private void Start()
|
|
37
|
+
{
|
|
38
|
+
LocalizationManager.ChooseLanguage(startupLanguage);
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Switch From UI
|
|
44
|
+
|
|
45
|
+
```csharp
|
|
46
|
+
public void UseVietnamese()
|
|
47
|
+
{
|
|
48
|
+
LocalizationManager.ChooseLanguage(SystemLanguage.Vietnamese);
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Use the return value when UI should show failure:
|
|
53
|
+
|
|
54
|
+
```csharp
|
|
55
|
+
bool changed = LocalizationManager.ChooseLanguage(SystemLanguage.Vietnamese);
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Read Current And Available Languages
|
|
59
|
+
|
|
60
|
+
```csharp
|
|
61
|
+
var current = LocalizationManager.GetCurrentLanguage();
|
|
62
|
+
var allLanguages = LocalizationManager.GetAllLanguageItem();
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Rules:
|
|
66
|
+
|
|
67
|
+
- `GetCurrentLanguage()` returns `null` and logs when the manager is missing;
|
|
68
|
+
- `GetAllLanguageItem()` reloads from `LocalizationSettings`;
|
|
69
|
+
- use `LocalizationLanguageItem.flagSpr` only as display data, not as runtime identity.
|
|
70
|
+
|
|
71
|
+
## Refresh Custom Non-UI State
|
|
72
|
+
|
|
73
|
+
Use this only when localization components cannot bind the target directly.
|
|
74
|
+
|
|
75
|
+
```csharp
|
|
76
|
+
using UnityEngine;
|
|
77
|
+
using XmobiTea.MiniLocalization;
|
|
78
|
+
|
|
79
|
+
public sealed class LocalizedTitleCache : MonoBehaviour
|
|
80
|
+
{
|
|
81
|
+
public string Title { get; private set; }
|
|
82
|
+
|
|
83
|
+
private void OnEnable()
|
|
84
|
+
{
|
|
85
|
+
LocalizationManager.OnUpdateText -= Refresh;
|
|
86
|
+
LocalizationManager.OnUpdateText += Refresh;
|
|
87
|
+
Refresh();
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
private void OnDisable()
|
|
91
|
+
{
|
|
92
|
+
LocalizationManager.OnUpdateText -= Refresh;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
private void Refresh()
|
|
96
|
+
{
|
|
97
|
+
Title = LocalizationManager.GetText("Home_Title");
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Hard No
|
|
103
|
+
|
|
104
|
+
- Do not call localization static APIs from another component `Awake()` without an execution-order guarantee.
|
|
105
|
+
- Do not assume one language switch means one refresh event.
|
|
106
|
+
- Do not overwrite `LocalizationManager.OnUpdateText` with `=` or `null`.
|
|
107
|
+
- Do not manually refresh fixed `Text` or `TMP_Text` when localization components can bind the key.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
fileFormatVersion: 2
|
|
2
|
-
guid: e9649c16f0de44cb8a55778b64cbc0e0
|
|
3
|
-
TextScriptImporter:
|
|
4
|
-
externalObjects: {}
|
|
5
|
-
userData:
|
|
6
|
-
assetBundleName:
|
|
7
|
-
assetBundleVariant:
|
|
1
|
+
fileFormatVersion: 2
|
|
2
|
+
guid: e9649c16f0de44cb8a55778b64cbc0e0
|
|
3
|
+
TextScriptImporter:
|
|
4
|
+
externalObjects: {}
|
|
5
|
+
userData:
|
|
6
|
+
assetBundleName:
|
|
7
|
+
assetBundleVariant:
|
package/AI_USAGE.md
CHANGED
|
@@ -4,16 +4,16 @@ Use this file to choose the correct localization API or generate common runtime
|
|
|
4
4
|
|
|
5
5
|
## Need-Based Routing
|
|
6
6
|
|
|
7
|
-
| Need | Use |
|
|
8
|
-
| --- | --- |
|
|
9
|
-
| Choose API or generate common runtime code | this file |
|
|
10
|
-
| Switch runtime language, read current language, build language selector | `AI_SWITCH_LANGUAGE.md` |
|
|
11
|
-
| Bind fixed UI text or use the bulk localization window | `AI_BIND_UI_TEXT.md` |
|
|
12
|
-
| Add, rename, or remove a localization key | `AI_ADD_LOCALIZATION_KEY.md` |
|
|
13
|
-
| Import translations from CSV or Google Sheets | `AI_IMPORT_TRANSLATIONS.md` |
|
|
14
|
-
| Setup router | `AI_SETUP.md` |
|
|
15
|
-
| Scene manager setup and bootstrap | `AI_SETUP_LOCALIZATION_MANAGER.md` |
|
|
16
|
-
| Settings asset, XML, CSV/Google import, constants setup | `AI_SETUP_LOCALIZATION_SETTINGS.md` |
|
|
7
|
+
| Need | Use |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| Choose API or generate common runtime code | this file |
|
|
10
|
+
| Switch runtime language, read current language, build language selector | `AI_SWITCH_LANGUAGE.md` |
|
|
11
|
+
| Bind fixed UI text or use the bulk localization window | `AI_BIND_UI_TEXT.md` |
|
|
12
|
+
| Add, rename, or remove a localization key | `AI_ADD_LOCALIZATION_KEY.md` |
|
|
13
|
+
| Import translations from CSV or Google Sheets | `AI_IMPORT_TRANSLATIONS.md` |
|
|
14
|
+
| Setup router | `AI_SETUP.md` |
|
|
15
|
+
| Scene manager setup and bootstrap | `AI_SETUP_LOCALIZATION_MANAGER.md` |
|
|
16
|
+
| Settings asset, XML, CSV/Google import, constants setup | `AI_SETUP_LOCALIZATION_SETTINGS.md` |
|
|
17
17
|
| Exact signatures, fields, XML shape, editor menu names | `AI_API_REFERENCE.md` |
|
|
18
18
|
| Lifecycle, source precedence, async refreshes, fetch edge cases | `AI_BEHAVIOR.md` |
|
|
19
19
|
| Package guardrails | `AGENTS.md` |
|
|
@@ -69,14 +69,14 @@ using XmobiTea.MiniLocalization.Core;
|
|
|
69
69
|
|
|
70
70
|
## Task Defaults
|
|
71
71
|
|
|
72
|
-
| Task | Default action |
|
|
73
|
-
| --- | --- |
|
|
74
|
-
| Add localization to project | Follow `AI_SETUP_LOCALIZATION_SETTINGS.md`, then `AI_SETUP_LOCALIZATION_MANAGER.md`. |
|
|
75
|
-
| Add a localized key | Follow `AI_ADD_LOCALIZATION_KEY.md`. |
|
|
76
|
-
| Bind existing UI text | Follow `AI_BIND_UI_TEXT.md`. |
|
|
77
|
-
| Switch language from UI | Follow `AI_SWITCH_LANGUAGE.md`. |
|
|
78
|
-
| Dynamic text with runtime values | Subscribe to `OnUpdateText`, rebuild the composed text, unsubscribe on disable. |
|
|
79
|
-
| Import translations | Follow `AI_IMPORT_TRANSLATIONS.md`. |
|
|
72
|
+
| Task | Default action |
|
|
73
|
+
| --- | --- |
|
|
74
|
+
| Add localization to project | Follow `AI_SETUP_LOCALIZATION_SETTINGS.md`, then `AI_SETUP_LOCALIZATION_MANAGER.md`. |
|
|
75
|
+
| Add a localized key | Follow `AI_ADD_LOCALIZATION_KEY.md`. |
|
|
76
|
+
| Bind existing UI text | Follow `AI_BIND_UI_TEXT.md`. |
|
|
77
|
+
| Switch language from UI | Follow `AI_SWITCH_LANGUAGE.md`. |
|
|
78
|
+
| Dynamic text with runtime values | Subscribe to `OnUpdateText`, rebuild the composed text, unsubscribe on disable. |
|
|
79
|
+
| Import translations | Follow `AI_IMPORT_TRANSLATIONS.md`. |
|
|
80
80
|
|
|
81
81
|
## Setup Gate
|
|
82
82
|
|
package/CHANGELOG.md
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
All notable changes to this package will be documented in this file.
|
|
3
3
|
|
|
4
|
-
The format is based on https://www.npmjs.com/org/xmobitea.
|
|
5
|
-
|
|
4
|
+
The format is based on https://www.npmjs.com/org/xmobitea.
|
|
5
|
+
|
|
6
|
+
## [1.5.3] - 2026-06-10
|
|
7
|
+
### Changed
|
|
8
|
+
- Centralized the localization settings open/create menu in `LocalizationSettingsEditor` by removing duplicate component editor implementations.
|
|
9
|
+
- Prefixed command-line and online XML load logs with `[Localization]`.
|
|
10
|
+
|
|
6
11
|
## [1.5.2] - 2026-06-01
|
|
7
|
-
### Added
|
|
8
|
-
- Added `LocalizationManager` runtime access for localized text.
|
|
12
|
+
### Added
|
|
13
|
+
- Added `LocalizationManager` runtime access for localized text.
|
|
9
14
|
- Added `LocalizationSettings` as the resource-backed localization configuration asset.
|
|
10
15
|
- Added `LocalizationLanguageItem` data for language definitions.
|
|
11
16
|
- Added `LocalizationComponent` support for `UnityEngine.UI.Text`.
|