Skip to content

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.

feat(ui): add pseudolocalization and text layout diagnostics

YHH563928975633
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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/desktop
index 19533ad0e..17bbe943a 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 19533ad0e069e7d9c95ad0396cb64d9220534f1a
+Subproject commit 17bbe943a3bbfb0f264218d20a69b2eaafcf6020
diff --git a/examples/ui-localization-debug/.gitignore b/examples/ui-localization-debug/.gitignore
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.eslocale
new file mode 100644
index 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.meta
new file mode 100644
index 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.eslocale
new file mode 100644
index 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.meta
new file mode 100644
index 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.eslocale
new file mode 100644
index 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.meta
new file mode 100644
index 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.eslocale
new file mode 100644
index 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.meta
new file mode 100644
index 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.eslocale
new file mode 100644
index 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.meta
new file mode 100644
index 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.eslocale
new file mode 100644
index 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.meta
new file mode 100644
index 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.esscene
new file mode 100644
index 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.meta
new file mode 100644
index 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.esproject
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.md
index 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: string
setFallbackLocale: (locale: string) => void
setLocale: (locale: string) => void
setPluralSelector: (locale: string, selector: PluralSelector) => void
+setPseudoLocalization: (options: PseudoLocalizationOptions | null) => void
t: (key: string, params?: TParams) => string
static new (locale?: string, fallback?: string): LocalizationAPI
static prototype: LocalizationAPI
@@ -6487,6 +6488,12 @@ name: string
type: "property"
```
+## PseudoLocalizationOptions — interface @experimental
+```
+accents: boolean | undefined
+expansion: number | undefined
+```
+
## PtrLayout — interface @experimental
```
fields: readonly PtrFieldDesc[]
@@ -8510,6 +8517,30 @@ static new (): TextInputPlugin
static 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 @@ InputPlugin
InputRouter
```
+## 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) => Dimension
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: string
setFallbackLocale: (locale: string) => void
setLocale: (locale: string) => void
setPluralSelector: (locale: string, selector: PluralSelector) => void
+setPseudoLocalization: (options: PseudoLocalizationOptions | null) => void
t: (key: string, params?: TParams) => string
static new (locale?: string, fallback?: string): LocalizationAPI
static prototype: LocalizationAPI
@@ -6678,6 +6679,12 @@ name: string
type: "property"
```
+## PseudoLocalizationOptions — interface @experimental
+```
+accents: boolean | undefined
+expansion: number | undefined
+```
+
## PtrLayout — interface @experimental
```
fields: readonly PtrFieldDesc[]
@@ -8711,6 +8718,30 @@ static new (): TextInputPlugin
static 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 @@ InputPlugin
InputRouter
```
+## 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) => Dimension
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: string
setFallbackLocale: (locale: string) => void
setLocale: (locale: string) => void
setPluralSelector: (locale: string, selector: PluralSelector) => void
+setPseudoLocalization: (options: PseudoLocalizationOptions | null) => void
t: (key: string, params?: TParams) => string
static new (locale?: string, fallback?: string): LocalizationAPI
static prototype: LocalizationAPI
@@ -6482,6 +6483,12 @@ name: string
type: "property"
```
+## PseudoLocalizationOptions — interface @experimental
+```
+accents: boolean | undefined
+expansion: number | undefined
+```
+
## PtrLayout — interface @experimental
```
fields: readonly PtrFieldDesc[]
@@ -8505,6 +8512,30 @@ static new (): TextInputPlugin
static 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 @@ InputPlugin
InputRouter
```
+## 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) => Dimension
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: string
setFallbackLocale: (locale: string) => void
setLocale: (locale: string) => void
setPluralSelector: (locale: string, selector: PluralSelector) => void
+setPseudoLocalization: (options: PseudoLocalizationOptions | null) => void
t: (key: string, params?: TParams) => string
static new (locale?: string, fallback?: string): LocalizationAPI
static prototype: LocalizationAPI
@@ -6755,6 +6756,12 @@ name: string
type: "property"
```
+## PseudoLocalizationOptions — interface @experimental
+```
+accents: boolean | undefined
+expansion: number | undefined
+```
+
## PtrLayout — interface @experimental
```
fields: readonly PtrFieldDesc[]
@@ -8778,6 +8785,30 @@ static new (): TextInputPlugin
static 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 @@ InputPlugin
InputRouter
```
+## 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) => Dimension
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: string
setFallbackLocale: (locale: string) => void
setLocale: (locale: string) => void
setPluralSelector: (locale: string, selector: PluralSelector) => void
+setPseudoLocalization: (options: PseudoLocalizationOptions | null) => void
t: (key: string, params?: TParams) => string
static new (locale?: string, fallback?: string): LocalizationAPI
static prototype: LocalizationAPI
@@ -6489,6 +6490,12 @@ name: string
type: "property"
```
+## PseudoLocalizationOptions — interface @experimental
+```
+accents: boolean | undefined
+expansion: number | undefined
+```
+
## PtrLayout — interface @experimental
```
fields: readonly PtrFieldDesc[]
@@ -8512,6 +8519,30 @@ static new (): TextInputPlugin
static 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 @@ InputPlugin
InputRouter
```
+## 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) => Dimension
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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/g
export { 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 Utilities
export {
diff --git a/sdk/src/ui/text/inspect-text.ts b/sdk/src/ui/text/inspect-text.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.mjs
new file mode 100644
index 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.tsx
new file mode 100644
index 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);