Skip to content

Add extensible i18n/localization support #621

Open

Description

@johnsonkang

Problem or motivation

Hi, thanks for developing Pascal Editor.

Would you consider adding first-class, extensible i18n/localization support?

Ideally, it could cover:

Editor UI, menus, dialogs, tooltips, and commands
Inspector/property labels
Node and tool labels/descriptions
Plugin-provided UI strings
Runtime locale switching
Custom locale packs

It would be especially useful if plugins and downstream applications could register their own translations without modifying Pascal's core packages.

If you're open to this feature and have any related plans or development guidelines, I'd be happy to contribute a PR.

Proposed solution

No response

Alternatives considered

No response

Additional context

No response

Activity

  1. Aymericr commented on Aug 28, 2026

    @Aymericr
    Member

    Thanks — this is a well-scoped request and the plugin/downstream registration angle is the right frame; any i18n design that requires forking core strings is dead on arrival for us.

    I've just closed discussion #272 pointing here, so this issue is now the canonical i18n thread. What would move it forward is exactly what you offered: a short proposal covering (1) an inventory of user-facing string surfaces (editor UI, inspector labels, node/tool labels, plugin-provided strings — they have different owners and lifecycles), (2) how locale packs load and fall back, and (3) how a plugin registers translations without touching core packages. I won't commit to a framework before that contract exists, but I'll engage seriously with the proposal — start it as a comment here or a discussion, whichever you prefer.

  2. Aymericr commented on Sep 12, 2026

    @Aymericr
    Member

    Triage update: I closed #740 because it attempted the full UI migration before this issue’s extensibility contract was settled and mixed that work with unrelated fork repairs and repository artifacts. This remains the canonical open request. The next useful contribution is the short design proposed above: enumerate string owners/surfaces, define locale loading and fallback, and define how plugins register translations. Once that is agreed, implementation should land one package or surface at a time from current main.

  3. luis-caf commented on Oct 3, 2026

    @luis-caf

    Following up on the request above for (1) a string inventory, (2) locale loading/fallback and (3) plugin registration — here is a proposal backed by a scan of current main and a small working prototype.

    1. Inventory: who owns which strings

    Method: TypeScript AST scan (not regex) of packages/{editor,nodes,viewer,core,ui}/src and apps/editor, tests/fixtures/dist excluded; cli, mcp, ifc-converter out of scope (terminal/agent text). Every hit is classified by owner (package), audience, and form (JSX text, JSX prop, config object, node definition, label map, default name, constant/generated, toast). Spot checks: ~95% of sampled hits are real UI text; the scan catches ~82% of capitalised multi-word literals, so treat totals as a floor.

    User-interface strings: ~4.3k (2.7k unique) in 463 files

    Owner Strings Unique Files Lifecycle / who changes it
    nodes — one folder per node kind (definition.ts labels/descriptions, parametrics.ts field labels, panel.tsx inspectors, tool hints) 2,243 1,411 230 Changes with each node kind. Plugins ship node kinds of their own, so this is also the shape plugin strings have.
    editor — editor chrome (sidebar, panels, build panel, helpers, command palette, dialogs) 1,394 1,051 156 Changes with the editor UI; the build panel moved here from the app during September.
    core — generated display names (getDefaultLevelName), procedural item recipes, schema labels 325 257 55 Small, but some of it ends up inside scene data (see 2.4).
    apps/editor — the example host app 202 169 14 Host-owned. Downstream hosts replace or copy it; it consumes the contract, it does not need to be part of it.
    viewer 38 34 7 Small; good first surface.
    ui 2 2 2 —

    Strings that should NOT go through UI i18n

    Audience Strings Why it is separate
    Content (catalog item names, material library) 411 Data, not chrome: a host with its own catalog brings its own names (and languages).
    Exported data (glb-export.ts node names, etc.) 38 Must stay stable — downstream tools key on them. Translating would break consumers.
    Agent / MCP tool descriptions 50 Written for models; English is the API.
    Validation messages (core/validation) 25 User-visible but produced in core; need keys + params, not literals.
    Legal pages in the example app 100 Host content.
    Developer errors (new Error) 284 Not user-facing.

    2. Proposed contract

    2.1 Keys and English as the built-in fallback

    • Every user-facing string gets a key, and the English literal stays in the code as the default: t('editor.buildPanel.rooms.title', 'Rooms'). With no locale registered, behaviour and screenshots are identical to today — zero risk for English, and migration can go one surface at a time.
    • Namespaces follow ownership: editor.*, viewer.*, core.*, node.<kind>.*, plugin.<pluginId>.*.
    • Node definitions keep presentation.label / description in English; display goes through t(\node.${kind}.label`, def.presentation.label)`. No node definition has to change shape.

    2.2 Registration (no framework required in core)

    • core exposes a tiny registry: registerMessages(locale, namespace, messages) and setLocale(locale); editor exposes useTranslate() reading it (re-render on locale change).
    • Host app: calls registerMessages('pt-BR', 'editor', ptBrEditor) before mounting <Editor> — exactly how it already calls registerNode.
    • Plugins: a plugin manifest may carry translations: { [locale]: messages } for its own plugin.<id>.* / node.<kind>.* namespaces, registered when the plugin loads. Nothing in core packages is touched.
    • Locale packs for core namespaces can live outside the repo (npm @scope/pascal-locale-xx) or in-repo later; the contract does not care.

    2.3 Fallback

    pt-BR → pt → English literal in code. Missing keys never throw and never show the key; a dev-only warning lists them.

    2.4 Names saved into scene data

    Today both patterns exist:

    • display-time default: getDefaultLevelName() — "a name the user gave wins", otherwise computed when shown. Safe to translate.
    • write-time default: e.g. liquid-line/tool.tsx creates nodes with name: 'Liquid Line', which is persisted. Translating that literal would store the creator's language in the scene and in exports.

    Proposal: default names become display-time (store no name, or a key), following the level-name pattern. Out of scope for the first PRs, but the contract should state it so nobody "translates" write-time names.

    2.5 Server rendering and hydration

    If the locale is only known in the browser, server HTML (English) and the first client render (translated) differ and React throws Hydration failed — the prototype hit this on the first try. The hook therefore returns the English fallback for the server snapshot (useSyncExternalStore(subscribe, getVersion, () => SERVER)) and re-renders with the client locale right after hydration. Hosts that know the locale on the server (cookie/header) can call setLocale there too and skip the flash.

    2.6 Out of scope on purpose

    Exported names (GLB/IFC), agent/MCP text, catalog/material content, dev errors.

    3. Prototype

    Two commits on top of main @ 89e1442f: (1) core/src/i18n registry (88 lines, no dependency) + useTranslate() hook (21 lines) + tests, and the Build panel's Rooms section and "Advanced" header moved to 16 keys (build-panel.tsx +20/−6); (2) a host file registering pt-BR (+32 lines, outside core). With no locale (or ?lang=en) every string is the original English; with pt-BR the section is translated, including the caption that follows the armed shape. No translated text lives in core packages.

    4. Suggested rollout

    1. Registry + useTranslate() + fallback in core/editor, no strings migrated (one small PR).
    2. A CI guard in the same PR or right after: flag new user-facing literals that bypass t() (JSX text, label/title/aria-label props, node definition labels). Without it the migration never finishes: between 1.0.2 (2026-09-18) and main (2026-10-02) the UI gained 612 new unique strings in 14 days (~300/week, mostly editor and nodes). Our AST scan already does this detection and could be the starting point; it can start as a warning and only cover migrated surfaces.
    3. One surface per PR from current main: viewer (38 strings) → editor build panel → inspectors per node kind.
    4. Plugin manifest translations once a first plugin wants it.

    The scan script and the full per-string CSV are available if useful, and the prototype can be opened as a draft PR from current main.

    What we (Kliv, Brazil — pt-BR) can commit to once the contract is agreed: the registry PR (steps 1–2), the migration of two or three surfaces as reference (starting with viewer and the build panel), and the pt-BR locale pack, kept up to date as new keys land. We don't expect to migrate every surface ourselves.

  4. JakubPisula commented on Oct 25, 2026

    @JakubPisula

    Hi, +1 from a downstream host. We embed Pascal (forked, currently on 1.0.4) in RemontOS, a renovation-management app for Polish contractors, and our crews need the editor in Polish. We'd rather not fork core strings, so the contract proposed by @luis-caf above fits us well. A few notes from the host side:

    • Host-registered packs: registerMessages('pl', namespace, messages) from the host, outside core packages, is exactly what we need. Our own plugins (MEP, a pricing panel) already ship Polish UI and would use the plugin.<id>.* namespace.
    • Locale from the host before hydration: we open the editor in an iframe, and the host already knows the user's language. A documented way to set it up front (query param or host config) would avoid the English flash described in 2.5.
    • Number and unit formatting: Polish uses a decimal comma (2,75 m). It would help if the measurement readouts went through Intl.NumberFormat for the active locale, not only the labels.
    • Write-time default names: +1 to 2.4. We read scene data server-side (quantity take-off), so stored names must stay language-neutral.

    Once the registry lands, we'd be happy to contribute and maintain a pl locale pack.

  5. volkankurt2 commented on Oct 26, 2026

    @volkankurt2

    Hi — I build a downstream host on Pascal (a Turkish-market house design app that composes the editor, viewer and nodes as packages and stays in sync with main weekly), and I'd like to help move this forward with a Turkish (tr) locale pack once the contract is agreed.

    +1 to the shape in @luis-caf's proposal. From the host side, three things would make it work for us without forking:

    1. English literal as the in-code default (t(key, 'Rooms')): an untranslated surface stays exactly as today, so packs can land surface by surface and a stale pack degrades to English, never to a blank.
    2. Host registration before mount, like registerNode: registerMessages('tr', 'editor', messages) + setLocale('tr'), and a way to change the locale at runtime (our users switch TR/EN from the app's header; we keep the choice in a first-party cookie so the server renders the right <html lang>).
    3. Numbers and units through the same locale (decimal comma in Turkish: 3,10 m, 18,4 m²), so a translated label and its value don't disagree.

    Our own app layer already works this way (Turkish source strings as keys, an English catalog, a rule test that fails on any string without an entry), so we can contribute the tr pack and test it against real screens. Happy to start with the smallest surface you'd like to pilot (viewer looks like the obvious first one at ~38 strings).

  6. Aymericr commented on Oct 26, 2026

    @Aymericr
    Member

    Thanks @luis-caf for the proposal, and @JakubPisula and @volkankurt2 for offering to maintain packs. We'd like to support multiple languages, and this direction works for us:

    • English stays in code as the fallback.
    • Strings live in per-locale packs that hosts can register, so anyone can add or adapt a language without forking.
    • Numbers and units are formatted for the locale.

    The main goal is that it stays easy to maintain, so please keep the registry small. We'd like the first set of bundled languages to be English, Chinese, French, Spanish and Japanese, with community packs such as pl and tr on top.

    A small first PR that adds just the registry and the fallback, with a few strings converted, would be the right place to start. It should include screenshots of the editor in another language. The zh-CN work in #1022 can then rebase onto it.

  7. Aymericr commented on Oct 26, 2026

    @Aymericr
    Member

    Before the first PR, please write a short design note here that covers what apps embedding the editor have asked for in this thread:

    1. A host app can register its own language packs without editing core.
    2. A host app can set the locale before the editor loads, through the iframe or embed config.
    3. Numbers and units follow the locale, for example a decimal comma ("2,75 m") and mm units.
    4. Names saved in scenes stay language-neutral. Translation should change only the UI and never the scene data, because some hosts read scenes on the server.

    Once the note is agreed, the registry PR can follow.

  8. volkankurt2 commented on Oct 26, 2026

    @volkankurt2

    Thanks @Aymericr. Here is a short design note for the four points, building on @luis-caf's proposal (happy for @luis-caf to fold it into theirs or take the registry PR as planned).

    1. Host-registered packs, no core edits

    • core gets a small registry: registerMessages(locale, namespace, messages), setLocale(locale), getLocale(), subscribe(listener). No dependency.
    • Namespaces follow ownership: editor.*, viewer.*, core.*, node.<kind>.*, plugin.<id>.*. A host registers packs before mounting <Editor>, the same way it calls registerNode. Later registrations for the same locale/namespace merge over earlier ones, so a host can adapt a bundled pack.
    • In code, the English literal stays as the default: t('editor.buildPanel.rooms.title', 'Rooms'). Lookup: pt-BR → pt → the English literal. A missing key never throws and never shows the key. In development it logs a warning.

    2. Locale before the editor loads

    • An embed takes locale in its config (<Editor locale="tr" />); the standalone app and iframes take ?lang=tr. Either one calls setLocale before the first render.
    • A host that knows the locale on the server (cookie or header) sets it there too, so the server HTML and the first client render agree: no English flash, no hydration mismatch. Without it, the hook returns English for the server snapshot and switches right after hydration.
    • setLocale at runtime re-renders the subscribed components, so a host can offer a language switch.

    3. Numbers and units follow the locale

    • One formatter in core: formatNumber(value, { min, max }) and formatLength(meters, unit) on top of Intl.NumberFormat(getLocale()). A readout and its label then never disagree (2,75 m in tr and pl, 2.75 m in en).
    • The unit system (m / cm / mm, m²) is a separate setting from the language. Inputs accept the locale's decimal separator as well as ..

    4. Scene data stays language-neutral

    • Translation changes only what is rendered. Nothing in a scene, an export (GLB/IFC) or an MCP/agent result is translated.
    • Default names are computed when shown, following the getDefaultLevelName() pattern. A node stores a name only when a person gives one. Write-time defaults such as name: 'Liquid Line' move to display time surface by surface. Until a surface has moved, it keeps writing its English default, as it does today.
    • A test can guard this: build a scene under a non-English locale, serialize it, and expect it to equal the same scene built under English.

    First PR (as you suggested)
    The registry, the hook, the fallback and the number formatter, with the viewer strings (~38) converted, plus screenshots in a second language. #1022 rebases onto it. A CI check that flags new user-facing literals bypassing t() can follow as a warning on converted surfaces.

    From our side (Forehome, tr): we can test the registry against a real downstream host that switches language at runtime and renders on the server, and we will maintain the tr pack.

  9. Aymericr commented on Oct 26, 2026

    @Aymericr
    Member

    Thanks @volkankurt2, this note covers all four points and we're taking it as the agreed design, together with @luis-caf's contract.

    We're opening the first registry PR on our side now. It includes the registry and fallback, useTranslate(), setting the locale through embed config and ?lang=, locale-aware number and length formatting, a test that keeps scene data language-neutral, the viewer strings, and bundled en/zh-CN/fr/es/ja packs. It also adds tooling to find missing or stale keys and fill them with AI, with a human reviewing the result. I'll link the PR here as soon as it's up. @luis-caf, please hold off on a parallel registry PR. Reviews from all three of you would help a lot, especially testing it against a real host. After that, the pt-BR, pl and tr packs and further surface migrations are very welcome on top, and #1022 can rebase onto it.

  10. Aymericr commented on Oct 26, 2026

    @Aymericr
    Member

    The first registry PR is up: #1148. It adds the registry with English in-code fallback, useTranslate(), <Editor locale> and ?lang=, runtime switching, locale-aware number and length formatting with comma-decimal input, and a scene-serialization test across locales. The viewer and Build panel Rooms surfaces are converted (85 messages), with zh-CN, fr, es and ja packs. It also adds i18n:extract / i18n:check / i18n:translate tooling, which tracks hashed source strings, includes a CAD glossary, and supports AI fill with human review.

    @luis-caf @volkankurt2 @JakubPisula, reviews are very welcome, especially testing it against your hosts. The pt-BR, tr and pl packs can follow as soon as it lands. Screenshots will be inline in the PR description shortly.

  11. Aymericr commented on Oct 26, 2026

    @Aymericr
    Member

    Design note update (Maintainer bot): after reviewing Languine, lingo.dev, next-intl, Paraglide, react-i18next and FormatJS, we adopted Lingui 6 in #1148. It sits under the registry API agreed here (registerMessages, setLocale, getLocale, subscribe, the editor.* / viewer.* / core.* / node.<kind>.* / plugin.<id>.* namespaces, and English fallback through pt-BR → pt → en), so hosts and plugins never depend on Lingui directly.

    • No macros in published packages: messages use explicit IDs and runtime calls, so host apps need no Babel/SWC plugin or extra build step.
    • PO catalogs: one catalog per locale, compiled ahead of time, with a CI check (bun run i18n:check) for missing, stale or unreviewed entries.
    • AI-assisted translation: a translate command uses the Vercel AI SDK and our glossary. It validates placeholders and marks every machine translation fuzzy / Review: required until a person reviews it.
    • API status: the API stays marked @experimental until the first i18n release.

    The full-surface migration follows #1148 in about 22 PRs of up to about 400 strings each: panels, navbar, menus, sidebar, command palette, catalog, dialogs, layouts and tools, notifications, then every node kind and the viewer. Each PR tightens the CI guard for the areas it converts.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestready-for-humanNeeds human input during execution

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions