A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(ui): add pseudolocalization and text layout diagnostics
YHH563928975633
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 43bf8f712..16d54a35a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,15 @@ published separately; it ships inside the editor.## [Unreleased]+### Added++- UI text inspection and pseudolocalization previews. The editor can inspect+ computed text boxes, show overflow before clipping or ellipsis, and select+ the authored entity. Runtime localization can opt into accent and length+ stress without changing catalogs or parameters. Complex scripts, rich text+ and custom fonts are marked for visual review. The multilingual sample+ documents the scope and remaining platform checks.+### Fixed- **A project that moves keeps answering its textures from its own cache.** The editor remembered where each compressed texture was kept as an absolute path, so a project copied elsewhere went on serving textures from the old folder, and from none once that was deleted. It is kept relative to the project now; a record written by 0.76.0 is still read.diff --git a/desktop b/desktopindex 19533ad0e..17bbe943a 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 19533ad0e069e7d9c95ad0396cb64d9220534f1a+Subproject commit 17bbe943a3bbfb0f264218d20a69b2eaafcf6020diff --git a/examples/ui-localization-debug/.gitignore b/examples/ui-localization-debug/.gitignorenew file mode 100644index 000000000..04f4fa717--- /dev/null+++ b/examples/ui-localization-debug/.gitignore@@ -0,0 +1,3 @@+.esengine/+dist/+node_modules/diff --git a/examples/ui-localization-debug/README.md b/examples/ui-localization-debug/README.mdnew file mode 100644index 000000000..13187bce6--- /dev/null+++ b/examples/ui-localization-debug/README.md@@ -0,0 +1,21 @@+# UI localization debug++Open this project and use Window → UI Text Inspector. Wait for layout and+capture again. Original / Accents + 35% / Accents + 100% inspect a snapshot+without editing or saving scene content. Select jumps to the authored entity.+Box and text sizes are local display pixels, before Clip / Ellipsis truncation.++Play the scene. Switch locale cycles English, Chinese, Japanese, Korean,+Arabic and Thai. Stress text toggles runtime pseudolocalization; Resize box+changes the localized label between 220 and 600 pixels. These runtime changes+do not rewrite the catalog. The first narrow label and wrapped paragraph+intentionally overflow.++The ordinary glyph renderer does not implement Arabic joining / bidi or Thai+shaping. These rows require visual verification and cannot receive an automatic+fit verdict. Custom font assets, rich text and unresolved boxes are also marked+for review. Bounds cover glyph advances and line height, not stroke, shadow or+ink overhang. Host fonts can differ; inspect the exported game on each target.++This is RM-009 stage one. Focus paths, hit regions, platform shaping,+real IME/device acceptance and layout cache performance remain separate work.diff --git a/examples/ui-localization-debug/VALIDATION.md b/examples/ui-localization-debug/VALIDATION.mdnew file mode 100644index 000000000..16f3630ea--- /dev/null+++ b/examples/ui-localization-debug/VALIDATION.md@@ -0,0 +1,48 @@+# RM-009 stage one verification — 2026-10-08++Scope: pseudolocalization and an editor text-box inspector. The roadmap card+remains In Progress; this is not complex-script or device acceptance.++## Checks++- SDK: 29 checks across `ui-localization-debug`, `locale-table` and+ `ui-measure-text` pass. Catalogs and interpolated values survive preview;+ unknown keys stay visible; wrapping and truncation risks are diagnosed.+- Editor: typecheck, Vite build, and 28 i18n/menu/command checks pass.+- All 64 examples/templates typecheck against the current SDK.+- Public API: all 16 entry snapshots match. SDK test type debt remains+ 187 existing diagnostics, with zero new diagnostics.+- Built-in browser, actual WebGL2 editor: 11/11 fixture checks pass, including+ Yoga-computed sizes, pre-Ellipsis overflow, wrapped height, Chinese/Japanese/+ Korean bounds, explicit Arabic/Thai limitations and unchanged authored data.+- Window → UI Text Inspector opens a closable dock panel; 100% preview and+ selecting the English entity work. The panel reads the editor realm and+ labels its snapshot; an edited snapshot requires refresh before selection.+- CLI Web export includes the scene and six locale tables without warnings.+ The exported game loads and locale switching changes the localized label.++## Limits and observations++Arabic joining/bidi, Thai shaping, rich-text metrics, custom-font metrics,+real IME, minigame/native devices, focus paths, hit regions and performance+acceptance are not covered. Host fallback fonts require visual review; this+inspector measures advances/line height, not ink, stroke or shadow extents.++Some immediate built-in-browser screenshots show only changed text while a+later stable-frame screenshot shows all labels. The cause is unresolved; do+not use these captures to claim flicker-free exported-game acceptance. A+temporary no-cache comparison was reverted; no renderer cache changes ship.++The existing theme gate still reports the same 18 findings in CameraPreview,+GizmoMenu, TilemapReview and Viewport. It reports none in the new panel/styles.+The CSS-variable gate passes. Full CI/device acceptance is not asserted.++## Reproduce without desktop test runners++Build the SDK, then run `node tools/ui-localization-browser.mjs` and visit+`http://127.0.0.1:5194/__localization` in a browser. Open the inspector through+the Window menu. The fixture uses the paired editor revision and launches no+Electron or native test window.++Export with `node pipeline/bin/estella.mjs export examples/ui-localization-debug+--out <output-directory>`; serve that directory with a normal HTTP server.diff --git a/examples/ui-localization-debug/assets/i18n/ar.eslocale b/examples/ui-localization-debug/assets/i18n/ar.eslocalenew file mode 100644index 000000000..613d550dc--- /dev/null+++ b/examples/ui-localization-debug/assets/i18n/ar.eslocale@@ -0,0 +1,7 @@+{+ "version": 1,+ "locale": "ar",+ "entries": {+ "continue": "تابع إلى الفصل التالي"+ }+}diff --git a/examples/ui-localization-debug/assets/i18n/ar.eslocale.meta b/examples/ui-localization-debug/assets/i18n/ar.eslocale.metanew file mode 100644index 000000000..1f5c87300--- /dev/null+++ b/examples/ui-localization-debug/assets/i18n/ar.eslocale.meta@@ -0,0 +1,6 @@+{+ "version": "2.0",+ "uuid": "8c9f5151-b049-45b0-a6dc-94a7d0d21664",+ "importer": {},+ "type": "locale"+}diff --git a/examples/ui-localization-debug/assets/i18n/en.eslocale b/examples/ui-localization-debug/assets/i18n/en.eslocalenew file mode 100644index 000000000..5cec041f9--- /dev/null+++ b/examples/ui-localization-debug/assets/i18n/en.eslocale@@ -0,0 +1,7 @@+{+ "version": 1,+ "locale": "en",+ "entries": {+ "continue": "Continue to the next chapter"+ }+}diff --git a/examples/ui-localization-debug/assets/i18n/en.eslocale.meta b/examples/ui-localization-debug/assets/i18n/en.eslocale.metanew file mode 100644index 000000000..58465c2bc--- /dev/null+++ b/examples/ui-localization-debug/assets/i18n/en.eslocale.meta@@ -0,0 +1,6 @@+{+ "version": "2.0",+ "uuid": "3afb5cbb-bdaa-4d97-abb3-72822d486f1c",+ "importer": {},+ "type": "locale"+}diff --git a/examples/ui-localization-debug/assets/i18n/ja.eslocale b/examples/ui-localization-debug/assets/i18n/ja.eslocalenew file mode 100644index 000000000..e83669e24--- /dev/null+++ b/examples/ui-localization-debug/assets/i18n/ja.eslocale@@ -0,0 +1,7 @@+{+ "version": 1,+ "locale": "ja",+ "entries": {+ "continue": "次のチャプターに進む"+ }+}diff --git a/examples/ui-localization-debug/assets/i18n/ja.eslocale.meta b/examples/ui-localization-debug/assets/i18n/ja.eslocale.metanew file mode 100644index 000000000..422679d3f--- /dev/null+++ b/examples/ui-localization-debug/assets/i18n/ja.eslocale.meta@@ -0,0 +1,6 @@+{+ "version": "2.0",+ "uuid": "65714b7f-89b1-479d-8cf0-7552944408dd",+ "importer": {},+ "type": "locale"+}diff --git a/examples/ui-localization-debug/assets/i18n/ko.eslocale b/examples/ui-localization-debug/assets/i18n/ko.eslocalenew file mode 100644index 000000000..fcb5daae2--- /dev/null+++ b/examples/ui-localization-debug/assets/i18n/ko.eslocale@@ -0,0 +1,7 @@+{+ "version": 1,+ "locale": "ko",+ "entries": {+ "continue": "다음 장으로 계속하기"+ }+}diff --git a/examples/ui-localization-debug/assets/i18n/ko.eslocale.meta b/examples/ui-localization-debug/assets/i18n/ko.eslocale.metanew file mode 100644index 000000000..52e0a5a0e--- /dev/null+++ b/examples/ui-localization-debug/assets/i18n/ko.eslocale.meta@@ -0,0 +1,6 @@+{+ "version": "2.0",+ "uuid": "5182e8e1-1199-4e4a-8e04-2f37b98a1828",+ "importer": {},+ "type": "locale"+}diff --git a/examples/ui-localization-debug/assets/i18n/th.eslocale b/examples/ui-localization-debug/assets/i18n/th.eslocalenew file mode 100644index 000000000..d2903ac32--- /dev/null+++ b/examples/ui-localization-debug/assets/i18n/th.eslocale@@ -0,0 +1,7 @@+{+ "version": 1,+ "locale": "th",+ "entries": {+ "continue": "ไปยังบทถัดไป"+ }+}diff --git a/examples/ui-localization-debug/assets/i18n/th.eslocale.meta b/examples/ui-localization-debug/assets/i18n/th.eslocale.metanew file mode 100644index 000000000..6072d9778--- /dev/null+++ b/examples/ui-localization-debug/assets/i18n/th.eslocale.meta@@ -0,0 +1,6 @@+{+ "version": "2.0",+ "uuid": "12eb1475-c9db-4f49-82c8-cbbd0f295213",+ "importer": {},+ "type": "locale"+}diff --git a/examples/ui-localization-debug/assets/i18n/zh-CN.eslocale b/examples/ui-localization-debug/assets/i18n/zh-CN.eslocalenew file mode 100644index 000000000..e70a43547--- /dev/null+++ b/examples/ui-localization-debug/assets/i18n/zh-CN.eslocale@@ -0,0 +1,7 @@+{+ "version": 1,+ "locale": "zh-CN",+ "entries": {+ "continue": "继续前往下一章节"+ }+}diff --git a/examples/ui-localization-debug/assets/i18n/zh-CN.eslocale.meta b/examples/ui-localization-debug/assets/i18n/zh-CN.eslocale.metanew file mode 100644index 000000000..9b934d204--- /dev/null+++ b/examples/ui-localization-debug/assets/i18n/zh-CN.eslocale.meta@@ -0,0 +1,6 @@+{+ "version": "2.0",+ "uuid": "9de9ab69-458e-4fe2-90f5-e8128b40b80f",+ "importer": {},+ "type": "locale"+}diff --git a/examples/ui-localization-debug/assets/scenes/main.esscene b/examples/ui-localization-debug/assets/scenes/main.esscenenew file mode 100644index 000000000..6d5e6e738--- /dev/null+++ b/examples/ui-localization-debug/assets/scenes/main.esscene@@ -0,0 +1,751 @@+{+ "version": 4,+ "name": "Localization Debug",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "z": 10,+ "y": 0+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 300,+ "isActive": true+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Canvas",+ "parent": null,+ "children": [+ 2,+ 3,+ 4,+ 5,+ 6,+ 7,+ 8,+ 9,+ 10,+ 11,+ 12,+ 13+ ],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "Canvas",+ "data": {+ "designResolution": {+ "x": 800,+ "y": 600+ },+ "scaleMode": 2+ }+ },+ {+ "data": {},+ "type": "UINode"+ }+ ]+ },+ {+ "id": 2,+ "name": "Title",+ "parent": 1,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 600,+ "unit": 0+ },+ "height": {+ "value": 36,+ "unit": 0+ },+ "insetLeft": {+ "value": 40,+ "unit": 0+ },+ "insetTop": {+ "value": 20,+ "unit": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "UI localization / overflow laboratory",+ "fontSize": 20,+ "fontFamily": "Arial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "wordWrap": false+ }+ }+ ]+ },+ {+ "id": 3,+ "name": "English",+ "parent": 1,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 220,+ "unit": 0+ },+ "height": {+ "value": 32,+ "unit": 0+ },+ "insetLeft": {+ "value": 40,+ "unit": 0+ },+ "insetTop": {+ "value": 100,+ "unit": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "Continue to the next chapter",+ "fontSize": 20,+ "fontFamily": "Arial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "i18nKey": "continue",+ "overflow": 2,+ "wordWrap": false+ }+ }+ ]+ },+ {+ "id": 4,+ "name": "Chinese",+ "parent": 1,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 600,+ "unit": 0+ },+ "height": {+ "value": 36,+ "unit": 0+ },+ "insetLeft": {+ "value": 40,+ "unit": 0+ },+ "insetTop": {+ "value": 150,+ "unit": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "继续前往下一章节",+ "fontSize": 20,+ "fontFamily": "Arial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "wordWrap": false+ }+ }+ ]+ },+ {+ "id": 5,+ "name": "Japanese",+ "parent": 1,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 600,+ "unit": 0+ },+ "height": {+ "value": 36,+ "unit": 0+ },+ "insetLeft": {+ "value": 40,+ "unit": 0+ },+ "insetTop": {+ "value": 190,+ "unit": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "次のチャプターに進む",+ "fontSize": 20,+ "fontFamily": "Arial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "wordWrap": false+ }+ }+ ]+ },+ {+ "id": 6,+ "name": "Korean",+ "parent": 1,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 600,+ "unit": 0+ },+ "height": {+ "value": 36,+ "unit": 0+ },+ "insetLeft": {+ "value": 40,+ "unit": 0+ },+ "insetTop": {+ "value": 230,+ "unit": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "다음 장으로 계속하기",+ "fontSize": 20,+ "fontFamily": "Arial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "wordWrap": false+ }+ }+ ]+ },+ {+ "id": 7,+ "name": "Arabic — shaping unverified",+ "parent": 1,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 600,+ "unit": 0+ },+ "height": {+ "value": 36,+ "unit": 0+ },+ "insetLeft": {+ "value": 40,+ "unit": 0+ },+ "insetTop": {+ "value": 270,+ "unit": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "العربية — Chapter 2",+ "fontSize": 20,+ "fontFamily": "Arial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "wordWrap": false+ }+ }+ ]+ },+ {+ "id": 8,+ "name": "Thai — shaping unverified",+ "parent": 1,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 600,+ "unit": 0+ },+ "height": {+ "value": 36,+ "unit": 0+ },+ "insetLeft": {+ "value": 40,+ "unit": 0+ },+ "insetTop": {+ "value": 310,+ "unit": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "ไปยังบทถัดไป Chapter 2",+ "fontSize": 20,+ "fontFamily": "Arial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "wordWrap": false+ }+ }+ ]+ },+ {+ "id": 9,+ "name": "Wrapped paragraph",+ "parent": 1,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 220,+ "unit": 0+ },+ "height": {+ "value": 24,+ "unit": 0+ },+ "insetLeft": {+ "value": 40,+ "unit": 0+ },+ "insetTop": {+ "value": 350,+ "unit": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "A long sentence should wrap and overflow this short text box.",+ "fontSize": 20,+ "fontFamily": "Arial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "wordWrap": true,+ "overflow": 1+ }+ }+ ]+ },+ {+ "id": 10,+ "name": "Preview status",+ "parent": 1,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 680,+ "unit": 0+ },+ "height": {+ "value": 36,+ "unit": 0+ },+ "insetLeft": {+ "value": 40,+ "unit": 0+ },+ "insetTop": {+ "value": 440,+ "unit": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "Preview: off · Locale: en",+ "fontSize": 20,+ "fontFamily": "Arial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "wordWrap": false+ }+ }+ ]+ },+ {+ "id": 11,+ "name": "LocaleButton",+ "parent": 1,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 190,+ "unit": 0+ },+ "height": {+ "value": 42,+ "unit": 0+ },+ "insetLeft": {+ "value": 40,+ "unit": 0+ },+ "insetTop": {+ "value": 500,+ "unit": 0+ }+ }+ },+ {+ "type": "UIVisual",+ "data": {+ "color": {+ "r": 0.12,+ "g": 0.28,+ "b": 0.44,+ "a": 1+ },+ "visualType": 1+ }+ },+ {+ "type": "Interactable",+ "data": {+ "raycastTarget": true,+ "blockRaycast": true,+ "enabled": true+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "Switch locale",+ "fontSize": 18,+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "wordWrap": false+ }+ },+ {+ "data": {+ "tabIndex": 0+ },+ "type": "Focusable"+ }+ ]+ },+ {+ "id": 12,+ "name": "PseudoButton",+ "parent": 1,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 190,+ "unit": 0+ },+ "height": {+ "value": 42,+ "unit": 0+ },+ "insetLeft": {+ "value": 250,+ "unit": 0+ },+ "insetTop": {+ "value": 500,+ "unit": 0+ }+ }+ },+ {+ "type": "UIVisual",+ "data": {+ "color": {+ "r": 0.12,+ "g": 0.28,+ "b": 0.44,+ "a": 1+ },+ "visualType": 1+ }+ },+ {+ "type": "Interactable",+ "data": {+ "raycastTarget": true,+ "blockRaycast": true,+ "enabled": true+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "Stress text",+ "fontSize": 18,+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "wordWrap": false+ }+ },+ {+ "data": {+ "tabIndex": 0+ },+ "type": "Focusable"+ }+ ]+ },+ {+ "id": 13,+ "name": "WidthButton",+ "parent": 1,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "width": {+ "value": 190,+ "unit": 0+ },+ "height": {+ "value": 42,+ "unit": 0+ },+ "insetLeft": {+ "value": 460,+ "unit": 0+ },+ "insetTop": {+ "value": 500,+ "unit": 0+ }+ }+ },+ {+ "type": "UIVisual",+ "data": {+ "color": {+ "r": 0.12,+ "g": 0.28,+ "b": 0.44,+ "a": 1+ },+ "visualType": 1+ }+ },+ {+ "type": "Interactable",+ "data": {+ "raycastTarget": true,+ "blockRaycast": true,+ "enabled": true+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "Resize box",+ "fontSize": 18,+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "wordWrap": false+ }+ },+ {+ "data": {+ "tabIndex": 0+ },+ "type": "Focusable"+ }+ ]+ }+ ]+}diff --git a/examples/ui-localization-debug/assets/scenes/main.esscene.meta b/examples/ui-localization-debug/assets/scenes/main.esscene.metanew file mode 100644index 000000000..9bbbb8330--- /dev/null+++ b/examples/ui-localization-debug/assets/scenes/main.esscene.meta@@ -0,0 +1,8 @@+{+ "uuid": "7a0f3334-5eff-4d2f-83b9-81a7af0e76fb",+ "type": "scene",+ "importer": {+ "autoMigrate": true+ },+ "version": "2.0"+}diff --git a/examples/ui-localization-debug/project.esproject b/examples/ui-localization-debug/project.esprojectnew file mode 100644index 000000000..87b4d2101--- /dev/null+++ b/examples/ui-localization-debug/project.esproject@@ -0,0 +1,16 @@+{+ "formatVersion": "1",+ "name": "UI Localization Debug",+ "description": "Multilingual text, pseudolocalization and overflow inspection.",+ "tag": "UI",+ "version": "0.1.0",+ "defaultScene": "assets/scenes/main.esscene",+ "designResolution": {+ "width": 800,+ "height": 600+ },+ "spineVersion": "none",+ "scripts": {+ "main": "src/main.ts"+ }+}diff --git a/examples/ui-localization-debug/src/main.ts b/examples/ui-localization-debug/src/main.tsnew file mode 100644index 000000000..0c6933d36--- /dev/null+++ b/examples/ui-localization-debug/src/main.ts@@ -0,0 +1,24 @@+import {+ addPlugin, addSystemToSchedule, defineSystem, Schedule, Res, GetWorld,+ LocalizationPlugin, Localization, UIEvents, UIEventType, Text, UINode, px,+ type LocalizationAPI, type UIEventQueue, type World,+} from 'esengine';++const locales = ['en', 'zh-CN', 'ja', 'ko', 'ar', 'th'];+addPlugin(new LocalizationPlugin({ locale: 'en', fallback: 'en' }));+let locale = 0, pseudo = false, wide = false;+addSystemToSchedule(Schedule.Update, defineSystem([Res(Localization), Res(UIEvents), GetWorld()],+ (loc: LocalizationAPI, events: UIEventQueue, world: World) => {+ for (const event of events.query(UIEventType.Click)) {+ if (event.target === world.findEntityByName('LocaleButton')) { locale = (locale + 1) % locales.length; loc.setLocale(locales[locale]); }+ else if (event.target === world.findEntityByName('PseudoButton')) { pseudo = !pseudo; loc.setPseudoLocalization(pseudo ? { expansion: 1 } : null); }+ else if (event.target === world.findEntityByName('WidthButton')) {+ wide = !wide;+ const label = world.findEntityByName('English');+ if (label !== null) world.insert(label, UINode, { ...world.get(label, UINode), width: px(wide ? 600 : 220) });+ } else continue;+ const status = world.findEntityByName('Preview status');+ if (status !== null) world.insert(status, Text, { ...world.get(status, Text),+ content: `Preview: ${pseudo ? '100%' : 'off'} · Locale: ${loc.locale} · Box: ${wide ? 600 : 220}px` });+ }+ }, { name: 'LocalizationDebugControls' }));diff --git a/examples/ui-localization-debug/tsconfig.json b/examples/ui-localization-debug/tsconfig.jsonnew file mode 100644index 000000000..105dd19fa--- /dev/null+++ b/examples/ui-localization-debug/tsconfig.json@@ -0,0 +1,21 @@+{+ "compilerOptions": {+ "target": "ES2020",+ "module": "ESNext",+ "moduleResolution": "bundler",+ "strict": true,+ "esModuleInterop": true,+ "skipLibCheck": true,+ "forceConsistentCasingInFileNames": true,+ "declaration": false,+ "outDir": "./dist",+ "rootDir": ".",+ "paths": {+ "esengine": ["./.esengine/sdk/index.d.ts"],+ "estella-plugin-*": ["./.esengine/packages/*"],+ "esengine/wasm": ["./.esengine/sdk/wasm.d.ts"]+ }+ },+ "include": ["src/**/*"],+ "exclude": ["node_modules"]+}diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 051980717..d971ffb46 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 91 beta · 1537 experimental · 3 deprecated+Symbols: 115 public · 91 beta · 1542 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -4773,6 +4773,7 @@ locale: stringsetFallbackLocale: (locale: string) => voidsetLocale: (locale: string) => voidsetPluralSelector: (locale: string, selector: PluralSelector) => void+setPseudoLocalization: (options: PseudoLocalizationOptions | null) => voidt: (key: string, params?: TParams) => stringstatic new (locale?: string, fallback?: string): LocalizationAPIstatic prototype: LocalizationAPI@@ -6487,6 +6488,12 @@ name: stringtype: "property"```+## PseudoLocalizationOptions — interface @experimental+```+accents: boolean | undefined+expansion: number | undefined+```+## PtrLayout — interface @experimental```fields: readonly PtrFieldDesc[]@@ -8510,6 +8517,30 @@ static new (): TextInputPluginstatic prototype: TextInputPlugin```+## TextInspection — interface @experimental+```+horizontalOverflow: boolean+metrics: TextMetrics | null+unsupported: "rich-text" | "custom-font" | "complex-script" | "invalid-box" | null+verticalOverflow: boolean+```++## TextInspectionOptions — interface @experimental+```+bold: boolean | undefined+customFont: boolean | undefined+fontFamily: string | undefined+fontSize: number+height: number+italic: boolean | undefined+letterSpacing: number | undefined+lineHeight: number | undefined+maxWidth: number | undefined+richText: boolean | undefined+width: number+wordWrap: boolean | undefined+```+## TextMetrics — interface @experimental```height: number@@ -11347,6 +11378,11 @@ InputPluginInputRouter```+## inspectTextLayout — function @experimental+```+(text: string, opts: TextInspectionOptions): TextInspection+```+## inspectableTypes — function @experimental```(world: World, entity: number): string[]@@ -12007,6 +12043,11 @@ PrefabsPlugin(v: ClipVertex): [number, number]```+## pseudoLocalize — function @experimental+```+(template: string, options?: PseudoLocalizationOptions): string+```+## px — const @public```(n: number) => Dimensiondiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex a31644a19..a34a7e988 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 96 beta · 1556 experimental · 3 deprecated+Symbols: 115 public · 96 beta · 1561 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -4781,6 +4781,7 @@ locale: stringsetFallbackLocale: (locale: string) => voidsetLocale: (locale: string) => voidsetPluralSelector: (locale: string, selector: PluralSelector) => void+setPseudoLocalization: (options: PseudoLocalizationOptions | null) => voidt: (key: string, params?: TParams) => stringstatic new (locale?: string, fallback?: string): LocalizationAPIstatic prototype: LocalizationAPI@@ -6678,6 +6679,12 @@ name: stringtype: "property"```+## PseudoLocalizationOptions — interface @experimental+```+accents: boolean | undefined+expansion: number | undefined+```+## PtrLayout — interface @experimental```fields: readonly PtrFieldDesc[]@@ -8711,6 +8718,30 @@ static new (): TextInputPluginstatic prototype: TextInputPlugin```+## TextInspection — interface @experimental+```+horizontalOverflow: boolean+metrics: TextMetrics | null+unsupported: "rich-text" | "custom-font" | "complex-script" | "invalid-box" | null+verticalOverflow: boolean+```++## TextInspectionOptions — interface @experimental+```+bold: boolean | undefined+customFont: boolean | undefined+fontFamily: string | undefined+fontSize: number+height: number+italic: boolean | undefined+letterSpacing: number | undefined+lineHeight: number | undefined+maxWidth: number | undefined+richText: boolean | undefined+width: number+wordWrap: boolean | undefined+```+## TextMetrics — interface @experimental```height: number@@ -11593,6 +11624,11 @@ InputPluginInputRouter```+## inspectTextLayout — function @experimental+```+(text: string, opts: TextInspectionOptions): TextInspection+```+## inspectableTypes — function @experimental```(world: World, entity: number): string[]@@ -12258,6 +12294,11 @@ PrefabsPlugin(v: ClipVertex): [number, number]```+## pseudoLocalize — function @experimental+```+(template: string, options?: PseudoLocalizationOptions): string+```+## px — const @public```(n: number) => Dimensiondiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 27192d841..d1f84540b 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 93 beta · 1536 experimental · 3 deprecated+Symbols: 115 public · 93 beta · 1541 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -4768,6 +4768,7 @@ locale: stringsetFallbackLocale: (locale: string) => voidsetLocale: (locale: string) => voidsetPluralSelector: (locale: string, selector: PluralSelector) => void+setPseudoLocalization: (options: PseudoLocalizationOptions | null) => voidt: (key: string, params?: TParams) => stringstatic new (locale?: string, fallback?: string): LocalizationAPIstatic prototype: LocalizationAPI@@ -6482,6 +6483,12 @@ name: stringtype: "property"```+## PseudoLocalizationOptions — interface @experimental+```+accents: boolean | undefined+expansion: number | undefined+```+## PtrLayout — interface @experimental```fields: readonly PtrFieldDesc[]@@ -8505,6 +8512,30 @@ static new (): TextInputPluginstatic prototype: TextInputPlugin```+## TextInspection — interface @experimental+```+horizontalOverflow: boolean+metrics: TextMetrics | null+unsupported: "rich-text" | "custom-font" | "complex-script" | "invalid-box" | null+verticalOverflow: boolean+```++## TextInspectionOptions — interface @experimental+```+bold: boolean | undefined+customFont: boolean | undefined+fontFamily: string | undefined+fontSize: number+height: number+italic: boolean | undefined+letterSpacing: number | undefined+lineHeight: number | undefined+maxWidth: number | undefined+richText: boolean | undefined+width: number+wordWrap: boolean | undefined+```+## TextMetrics — interface @experimental```height: number@@ -11342,6 +11373,11 @@ InputPluginInputRouter```+## inspectTextLayout — function @experimental+```+(text: string, opts: TextInspectionOptions): TextInspection+```+## inspectableTypes — function @experimental```(world: World, entity: number): string[]@@ -12012,6 +12048,11 @@ PrefabsPlugin(v: ClipVertex): [number, number]```+## pseudoLocalize — function @experimental+```+(template: string, options?: PseudoLocalizationOptions): string+```+## px — const @public```(n: number) => Dimensiondiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 8034d4b1e..921e669ca 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 91 beta · 1558 experimental · 3 deprecated+Symbols: 115 public · 91 beta · 1563 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -4768,6 +4768,7 @@ locale: stringsetFallbackLocale: (locale: string) => voidsetLocale: (locale: string) => voidsetPluralSelector: (locale: string, selector: PluralSelector) => void+setPseudoLocalization: (options: PseudoLocalizationOptions | null) => voidt: (key: string, params?: TParams) => stringstatic new (locale?: string, fallback?: string): LocalizationAPIstatic prototype: LocalizationAPI@@ -6755,6 +6756,12 @@ name: stringtype: "property"```+## PseudoLocalizationOptions — interface @experimental+```+accents: boolean | undefined+expansion: number | undefined+```+## PtrLayout — interface @experimental```fields: readonly PtrFieldDesc[]@@ -8778,6 +8785,30 @@ static new (): TextInputPluginstatic prototype: TextInputPlugin```+## TextInspection — interface @experimental+```+horizontalOverflow: boolean+metrics: TextMetrics | null+unsupported: "rich-text" | "custom-font" | "complex-script" | "invalid-box" | null+verticalOverflow: boolean+```++## TextInspectionOptions — interface @experimental+```+bold: boolean | undefined+customFont: boolean | undefined+fontFamily: string | undefined+fontSize: number+height: number+italic: boolean | undefined+letterSpacing: number | undefined+lineHeight: number | undefined+maxWidth: number | undefined+richText: boolean | undefined+width: number+wordWrap: boolean | undefined+```+## TextMetrics — interface @experimental```height: number@@ -11631,6 +11662,11 @@ InputPluginInputRouter```+## inspectTextLayout — function @experimental+```+(text: string, opts: TextInspectionOptions): TextInspection+```+## inspectableTypes — function @experimental```(world: World, entity: number): string[]@@ -12296,6 +12332,11 @@ PrefabsPlugin(v: ClipVertex): [number, number]```+## pseudoLocalize — function @experimental+```+(template: string, options?: PseudoLocalizationOptions): string+```+## px — const @public```(n: number) => Dimensiondiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex d551d41e0..385a68205 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 91 beta · 1549 experimental · 3 deprecated+Symbols: 115 public · 91 beta · 1554 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -4775,6 +4775,7 @@ locale: stringsetFallbackLocale: (locale: string) => voidsetLocale: (locale: string) => voidsetPluralSelector: (locale: string, selector: PluralSelector) => void+setPseudoLocalization: (options: PseudoLocalizationOptions | null) => voidt: (key: string, params?: TParams) => stringstatic new (locale?: string, fallback?: string): LocalizationAPIstatic prototype: LocalizationAPI@@ -6489,6 +6490,12 @@ name: stringtype: "property"```+## PseudoLocalizationOptions — interface @experimental+```+accents: boolean | undefined+expansion: number | undefined+```+## PtrLayout — interface @experimental```fields: readonly PtrFieldDesc[]@@ -8512,6 +8519,30 @@ static new (): TextInputPluginstatic prototype: TextInputPlugin```+## TextInspection — interface @experimental+```+horizontalOverflow: boolean+metrics: TextMetrics | null+unsupported: "rich-text" | "custom-font" | "complex-script" | "invalid-box" | null+verticalOverflow: boolean+```++## TextInspectionOptions — interface @experimental+```+bold: boolean | undefined+customFont: boolean | undefined+fontFamily: string | undefined+fontSize: number+height: number+italic: boolean | undefined+letterSpacing: number | undefined+lineHeight: number | undefined+maxWidth: number | undefined+richText: boolean | undefined+width: number+wordWrap: boolean | undefined+```+## TextMetrics — interface @experimental```height: number@@ -11383,6 +11414,11 @@ InputPluginInputRouter```+## inspectTextLayout — function @experimental+```+(text: string, opts: TextInspectionOptions): TextInspection+```+## inspectableTypes — function @experimental```(world: World, entity: number): string[]@@ -12043,6 +12079,11 @@ PrefabsPlugin(v: ClipVertex): [number, number]```+## pseudoLocalize — function @experimental+```+(template: string, options?: PseudoLocalizationOptions): string+```+## px — const @public```(n: number) => Dimensiondiff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.tsindex 7243404f8..951b1d9ca 100644--- a/sdk/src/core-sys.ts+++ b/sdk/src/core-sys.ts@@ -39,6 +39,8 @@ export {export {Localization,LocalizationAPI,+ pseudoLocalize,+ type PseudoLocalizationOptions,LocalizationPlugin,localizationPlugin,interpolate,diff --git a/sdk/src/core-ui.ts b/sdk/src/core-ui.tsindex 8e2219a3a..76dd68195 100644--- a/sdk/src/core-ui.ts+++ b/sdk/src/core-ui.ts@@ -28,6 +28,9 @@ export {UILayoutGeneration,UIMask,measureText,+ inspectTextLayout,+ type TextInspection,+ type TextInspectionOptions,type MeasureTextOptions,type TextMetrics,parseRichText,diff --git a/sdk/src/i18n/Localization.ts b/sdk/src/i18n/Localization.tsindex 0a1df1570..5bd9692db 100644--- a/sdk/src/i18n/Localization.ts+++ b/sdk/src/i18n/Localization.ts@@ -10,6 +10,7 @@*/import { defineResource } from '../ecs/resource';+import { pseudoLocalize, type PseudoLocalizationOptions } from './pseudo-localization';export type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';@@ -59,6 +60,7 @@ export class LocalizationAPI {private readonly selectors = new Map<string, PluralSelector>();private locale_: string;private fallback_: string;+ private pseudo_: PseudoLocalizationOptions | null = null;constructor(locale = 'en', fallback = 'en') {this.locale_ = locale;@@ -78,6 +80,11 @@ export class LocalizationAPI {setFallbackLocale(locale: string): void { this.fallback_ = locale; }get fallbackLocale(): string { return this.fallback_; }+ /** Opt-in length stress preview. Pass null to restore ordinary translation. */+ setPseudoLocalization(options: PseudoLocalizationOptions | null): void {+ this.pseudo_ = options ? { ...options } : null;+ }+/** Override the plural rule for a locale (e.g. languages with few/many). */setPluralSelector(locale: string, selector: PluralSelector): void {this.selectors.set(locale, selector);@@ -101,10 +108,14 @@ export class LocalizationAPI {t(key: string, params?: TParams): string {const entry = this.lookup_(key);if (entry === undefined) return key;- if (typeof entry === 'string') return interpolate(entry, params);+ if (typeof entry === 'string') return this.translate_(entry, params);const count = typeof params?.count === 'number' ? params.count : 0;const selector = this.selectors.get(this.locale_) ?? defaultPluralSelector;- return interpolate(selectPluralForm(entry, count, selector), params);+ return this.translate_(selectPluralForm(entry, count, selector), params);+ }++ private translate_(template: string, params?: TParams): string {+ return interpolate(this.pseudo_ ? pseudoLocalize(template, this.pseudo_) : template, params);}private lookup_(key: string): LocaleEntry | undefined {diff --git a/sdk/src/i18n/index.ts b/sdk/src/i18n/index.tsindex 2f4e4921f..37e2299f6 100644--- a/sdk/src/i18n/index.ts+++ b/sdk/src/i18n/index.ts@@ -27,3 +27,5 @@ export {localizationPlugin,type LocalizationOptions,} from './LocalizationPlugin';++export { pseudoLocalize, type PseudoLocalizationOptions } from './pseudo-localization';diff --git a/sdk/src/i18n/pseudo-localization.ts b/sdk/src/i18n/pseudo-localization.tsnew file mode 100644index 000000000..4b1400d80--- /dev/null+++ b/sdk/src/i18n/pseudo-localization.ts@@ -0,0 +1,27 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team++/** Preview settings; never modify a catalog or interpolated parameter. @experimental */+export interface PseudoLocalizationOptions {+ /** Extra visible characters as a fraction of source length. Default 0.35. */+ expansion?: number;+ accents?: boolean;+}++const plain = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';+const accented = 'áƀçďéƒğĥíĵķľṁñóṕɋŕšţúṽŵẋýžÁƁÇĎÉƑĞĤÍĴĶĽṀÑÓṔɊŔŠŢÚṼŴẊÝŽ';++/** Length stress preview preserving placeholders, rich-text tags and newlines. @experimental */+export function pseudoLocalize(template: string, options: PseudoLocalizationOptions = {}): string {+ const expansion = Math.min(3, Math.max(0, Number.isFinite(options.expansion ?? 0.35) ? options.expansion ?? 0.35 : 0.35));+ return template.split('\n').map((line) => {+ if (!line) return line;+ let length = 0;+ const result = line.split(/(\{\w+\}|<[^>]*>|\[[^\]]*\])/g).map((part, index) => {+ if (index % 2) return part;+ length += [...part].length;+ return options.accents === false ? part : part.replace(/[a-z]/gi, (ch) => accented[plain.indexOf(ch)]);+ }).join('');+ return `⟦${result}${'~'.repeat(Math.ceil(length * expansion))}⟧`;+ }).join('\n');+}diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex c635cfba1..e8ca6fb42 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -328,6 +328,7 @@ export { BUILTIN_UI_PREFABS, BUILTIN_UI_WIDGET_NAMES } from './widgets/prefabs/gexport { TextPlugin, textPlugin, resolveTextRenderMode, glyphContentScale } from './text/plugin';export { InlineImagePlugin, inlineImagePlugin } from './text/inline-image-plugin';export { measureText, type MeasureTextOptions, type TextMetrics } from './text/measure-text';+export { inspectTextLayout, type TextInspection, type TextInspectionOptions } from './text/inspect-text';// UI Math Utilitiesexport {diff --git a/sdk/src/ui/text/inspect-text.ts b/sdk/src/ui/text/inspect-text.tsnew file mode 100644index 000000000..e6548d614--- /dev/null+++ b/sdk/src/ui/text/inspect-text.ts@@ -0,0 +1,53 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { measureText, type MeasureTextOptions, type TextMetrics } from './measure-text';+import { wrapByMeasure } from './layout';++/** A computed UINode text box, in local display pixels. @experimental */+export interface TextInspectionOptions extends MeasureTextOptions {+ width: number;+ height: number;+ wordWrap?: boolean;+ richText?: boolean;+ customFont?: boolean;+}++/** Overflow before the renderer applies Clip / Ellipsis. @experimental */+export interface TextInspection {+ metrics: TextMetrics | null;+ horizontalOverflow: boolean;+ verticalOverflow: boolean;+ /** These cases require visual verification rather than an automatic pass. */+ unsupported: 'rich-text' | 'custom-font' | 'complex-script' | 'invalid-box' | null;+}++/**+ * Inspect ordinary glyph-atlas text using individual glyph advances, as the+ * renderer does. Results depend on the host font; custom bitmap fonts and+ * shaped scripts deliberately return no automatic verdict. @experimental+ */+export function inspectTextLayout(text: string, opts: TextInspectionOptions): TextInspection {+ const unsupported = !Number.isFinite(opts.width) || !Number.isFinite(opts.height)+ || opts.width <= 0 || opts.height <= 0 || !Number.isFinite(opts.fontSize) || opts.fontSize <= 0+ || (opts.lineHeight !== undefined && (!Number.isFinite(opts.lineHeight) || opts.lineHeight <= 0))+ ? 'invalid-box' : opts.richText ? 'rich-text' : opts.customFont ? 'custom-font'+ : /[\u0300-\u036f\u0590-\u08ff\u0900-\u0fff\u200c-\u200f\u202a-\u202e\u2066-\u2069]/u.test(text) ? 'complex-script' : null;+ if (unsupported) return { metrics: null, horizontalOverflow: false, verticalOverflow: false, unsupported };+ const advances = new Map<string, number>();+ const widthOf = (line: string): number => [...line].reduce((sum, ch) => {+ let advance = advances.get(ch);+ if (advance === undefined) {+ advance = measureText(ch, { ...opts, maxWidth: undefined }).width;+ advances.set(ch, advance);+ }+ return sum + advance;+ }, 0);+ const lines = text.split('\n').flatMap((line) => opts.wordWrap ? wrapByMeasure(line, widthOf, opts.width) : [line]);+ const metrics = {+ width: lines.reduce((width, line) => Math.max(width, widthOf(line)), 0),+ height: lines.length * (opts.lineHeight ?? opts.fontSize * 1.2),+ lineCount: lines.length,+ };+ return { metrics, horizontalOverflow: metrics.width > opts.width + 0.01,+ verticalOverflow: metrics.height > opts.height + 0.01, unsupported: null };+}diff --git a/sdk/tests/ui-localization-debug.test.ts b/sdk/tests/ui-localization-debug.test.tsnew file mode 100644index 000000000..275e24215--- /dev/null+++ b/sdk/tests/ui-localization-debug.test.ts@@ -0,0 +1,47 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it } from 'vitest';+import { LocalizationAPI } from '../src/i18n/Localization';+import { pseudoLocalize } from '../src/i18n/pseudo-localization';+import { inspectTextLayout } from '../src/ui/text/inspect-text';++describe('localization preview', () => {+ it('preserves markup, parameters and line boundaries', () => {+ expect(pseudoLocalize('<b>Hello {name}</b>\n\n[image=star]', { expansion: 0 }))+ .toBe('⟦<b>Ĥéľľó {name}</b>⟧\n\n⟦[image=star]⟧');+ });+ it('selects plurals before preview and leaves bound values intact', () => {+ const loc = new LocalizationAPI();+ loc.addCatalog('en', { count: { one: '{count} item for {name}', other: '{count} items for {name}' } });+ loc.setPseudoLocalization({ expansion: 0 });+ expect(loc.t('count', { count: 2, name: 'Alice' })).toBe('⟦2 íţéṁš ƒóŕ Alice⟧');+ expect(loc.t('missing')).toBe('missing');+ loc.setPseudoLocalization(null);+ expect(loc.t('count', { count: 1, name: 'Alice' })).toBe('1 item for Alice');+ });+ it('bounds malformed or extreme expansion settings', () => {+ expect(pseudoLocalize('Hi', { accents: false, expansion: Infinity })).toBe('⟦Hi~⟧');+ expect(pseudoLocalize('Hi', { accents: false, expansion: -1 })).toBe('⟦Hi⟧');+ });+});++describe('text inspection', () => {+ const box = { width: 30, height: 12, fontSize: 10, lineHeight: 12 };+ it('reports overflow before clipping instead of treating truncation as fitting', () => {+ expect(inspectTextLayout('123456', box).horizontalOverflow).toBe(true);+ expect(inspectTextLayout('123456', { ...box, wordWrap: true }).verticalOverflow).toBe(true);+ expect(inspectTextLayout('12', box).metrics?.lineCount).toBe(1);+ });+ it('counts explicit empty lines and uses configured line height', () => {+ expect(inspectTextLayout('A\n\nB', box).metrics?.height).toBe(36);+ });+ it('does not claim shaped, rich or custom-font text fits', () => {+ expect(inspectTextLayout('العربية', box).unsupported).toBe('complex-script');+ expect(inspectTextLayout('ไทย', box).unsupported).toBe('complex-script');+ expect(inspectTextLayout('e\u0301', box).unsupported).toBe('complex-script');+ expect(inspectTextLayout('<b>Hi</b>', { ...box, richText: true }).unsupported).toBe('rich-text');+ expect(inspectTextLayout('Hi', { ...box, customFont: true }).unsupported).toBe('custom-font');+ expect(inspectTextLayout('Hi', { ...box, width: 0 }).unsupported).toBe('invalid-box');+ expect(inspectTextLayout('Hi', { ...box, lineHeight: -1 }).unsupported).toBe('invalid-box');+ });+});diff --git a/tools/ui-localization-browser.mjs b/tools/ui-localization-browser.mjsnew file mode 100644index 000000000..4470258c5--- /dev/null+++ b/tools/ui-localization-browser.mjs@@ -0,0 +1,28 @@+// SPDX-License-Identifier: Apache-2.0+// Ordinary browser fixture. No Electron, native windows or automated desktop launch.+import fs from 'node:fs';+import { fileURLToPath, pathToFileURL } from 'node:url';+import path from 'node:path';+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const { createServer } = await import(pathToFileURL(path.join(root, 'desktop/node_modules/vite/dist/node/index.js')).href);+const { default: react } = await import(pathToFileURL(path.join(root, 'desktop/node_modules/@vitejs/plugin-react/dist/index.js')).href);+const server = await createServer({ configFile: false, root: path.join(root, 'desktop'),+ resolve: { alias: [+ { find: '@', replacement: path.join(root, 'desktop/src') },+ { find: /^esengine$/, replacement: path.join(root, 'sdk/dist/index.js') },+ ] },+ server: { host: '127.0.0.1', port: 5194, strictPort: true, fs: { allow: [root] } },+ plugins: [react(), { name: 'ui-localization-fixture', configureServer(server) {+ server.middlewares.use((req, res, next) => {+ if (req.url === '/__localization-scene.json') {+ res.setHeader('Content-Type', 'application/json');+ res.end(fs.readFileSync(path.join(root, 'examples/ui-localization-debug/assets/scenes/main.esscene')));+ } else if (req.url === '/__localization') {+ const entry = `/@fs/${path.join(root, 'tools/ui-localization-browser.tsx').replaceAll('\\', '/')}`;+ const html = `<html><head><title>UI localization Web verification</title></head><body><div id="root"></div><script type="module" src="${entry}"></script></body></html>`;+ server.transformIndexHtml(req.url, html).then((result) => { res.setHeader('Content-Type', 'text/html'); res.end(result); });+ } else next();+ });+ } }] });+await server.listen();+console.log('UI localization fixture: http://127.0.0.1:5194/__localization');diff --git a/tools/ui-localization-browser.tsx b/tools/ui-localization-browser.tsxnew file mode 100644index 000000000..1d13bf8e0--- /dev/null+++ b/tools/ui-localization-browser.tsx@@ -0,0 +1,45 @@+// SPDX-License-Identifier: Apache-2.0+import '../desktop/src/main';+import { captureUITextRows } from '../desktop/src/panels/UITextDebugPanel';+import { EngineHost } from '../desktop/src/engine/EngineHost';+import { SceneModel } from '../desktop/src/engine/SceneModel';+import { useEditorStore } from '../desktop/src/store/editorStore';+import { inspectTextLayout, pseudoLocalize } from 'esengine';++const status = document.createElement('pre');+status.style.cssText = 'position:fixed;left:20px;bottom:20px;z-index:1001;max-width:600px;background:#19191d;color:white;padding:12px';+document.body.append(status);+EngineHost.setSceneBootstrap(async () => { await EngineHost.loadScene('/__localization-scene.json'); });+useEditorStore.getState().enterEditor();+const deadline = Date.now() + 45000;+while (EngineHost.getSnapshot().status !== 'ready' && Date.now() < deadline) await new Promise(r => setTimeout(r, 100));+if (EngineHost.getSnapshot().status !== 'ready') throw new Error(JSON.stringify(EngineHost.getSnapshot()));+EngineHost.syncEditorViewToScene();+for (let i = 0; i < 12; i++) await new Promise(requestAnimationFrame);+const before = JSON.stringify(SceneModel.serialize());+const rows = captureUITextRows();+let passed = 0, failed = 0;+const check = (ok: boolean, label: string) => { ok ? passed++ : failed++; status.textContent += `${ok ? 'PASS' : 'FAIL'} ${label}\n`; };+check(rows.length === 12, `Actual Text + UINode rows: ${rows.length}`);+check(rows.every(row => row.width > 0 && row.height > 0), 'Computed Yoga boxes resolved');+const english = rows.find(row => row.name === 'English')!;+const options = { width: english.width, height: english.height, fontSize: english.text.fontSize, fontFamily: english.text.fontFamily };+check(inspectTextLayout(english.text.content, options).horizontalOverflow, 'Narrow English detects overflow before Ellipsis');+check(inspectTextLayout(pseudoLocalize(english.text.content, { expansion: 1 }), options).horizontalOverflow, '100% preview detects overflow');+for (const name of ['Chinese', 'Japanese', 'Korean']) {+ const row = rows.find(row => row.name === name)!;+ const result = inspectTextLayout(row.text.content, { ...options, width: row.width, height: row.height });+ check(result.unsupported === null && !result.horizontalOverflow, `${name} ordinary bounds fit`);+}+for (const name of ['Arabic — shaping unverified', 'Thai — shaping unverified']) {+ const row = rows.find(row => row.name === name)!;+ check(inspectTextLayout(row.text.content, options).unsupported === 'complex-script', `${name}: no false automatic pass`);+}+const wrapped = rows.find(row => row.name === 'Wrapped paragraph')!;+check(inspectTextLayout(wrapped.text.content, { ...options, width: wrapped.width, height: wrapped.height, wordWrap: true }).verticalOverflow, 'Wrapped paragraph detects vertical truncation');+check(JSON.stringify(SceneModel.serialize()) === before, 'Inspection / pseudolocalization leave authored scene unchanged');+status.textContent += `RESULT ${passed} passed, ${failed} failed · ${EngineHost.activeBackend}`;+const dismiss = document.createElement('button');+dismiss.textContent = 'Dismiss verification report';+dismiss.onclick = () => { status.style.display = 'none'; };+status.append(document.createElement('br'), dismiss);