stitch2 0.9.1 → 0.11.0

package/README.md

@@ -37,6 +37,8 @@ file that already exists. From there the agent spends its effort on the design.
   and status filters, your DESIGN.md drawn as tokens and rules, the component catalog, and an inspector to
   approve, archive or leave a note on a version. Live reload; copyable references to paste to an agent.
   With a light and a dark theme (DESIGN.md's `light-*` colours), a switch (`T`) shows every screen in either one.
+  With languages configured, a Language switch (`L`) shows every screen in one of them, and the Languages page
+  shows a screen side by side in each.
   Pick mode (`P`) highlights any element of a screen and copies a reference with its source line, such as
   `home mobile v1 (design/screens/home/mobile-v1.html:36) <gg-button> “Start Push”`; Shift-click collects
   several to copy at once or add to the version's note.
@@ -44,7 +46,8 @@ file that already exists. From there the agent spends its effort on the design.
   other text, labels cut short with an ellipsis, content under fixed bars, fixed bars that overlap each other, tap
   targets (WCAG 2.2), text contrast in every theme, text that is not one of DESIGN.md's type levels, capitals without tracking,
   large numbers in monospace, components built by hand, components that differ between screens, and colours
-  written as values instead of DESIGN.md tokens.
+  written as values instead of DESIGN.md tokens. Each screen is also run in long and right-to-left
+  pseudo-languages and your locales (see below).
 - **Consistency report** (`stitch2 consistency`): every shared component (tab bar, header, buttons, chips, …)
   cropped from every screen, next to the catalog's version, with what differs (sizes, fonts, icon set, icons).
 - **Type audit** (`stitch2 type`): every text style a screen uses, and the level it matches.
@@ -73,7 +76,7 @@ file that already exists. From there the agent spends its effort on the design.
 - **Skills** for agents (`skills/`): `stitch2` (the design workflow, principles, typography, components,
   versions), `stitch2-design-md` (building the design system), `stitch2-variants` (fresh-eyes versions and
   testing skill changes), `stitch2-consistency` (verifying and fixing
-  consistency), `stitch2-app-sync` (keeping the app and the designs in step: design first, then the app) and,
+  consistency), `stitch2-i18n` (screens in every language), `stitch2-app-sync` (keeping the app and the designs in step: design first, then the app) and,
   optional, `stitch2-import-from-google-stitch` (drafting screens in Google Stitch through its MCP server).
 
 ## Setup
@@ -183,6 +186,49 @@ for (const locale of ['de', 'ru', 'ar']) {
 Warnings worth reading for translations: `truncated` (a label cut short with an ellipsis), `text-crowded` (two
 controls' labels nearly touching) and `clipped`.
 
+## Screens in every language
+
+A screen is written once, in the source language, with each product string marked by its message key from your
+app's own translation files. stitch2 swaps the text in when the screen is opened in another language, so one file
+shows every locale and the screens use the same strings as the product:
+
+```html
+<span data-t="nav.home">Home</span>
+<ex-header title="Settings" data-t-title="settings.title"></ex-header>
+<p data-t="workout.sets" data-t-args="count=16">16 sets</p>   <!-- plural form picked by count -->
+<p translate="no">Dumbbell Bench Press</p>                   <!-- sample content stays as written -->
+<ex-row meta="5 exercises · Linear" data-t-meta="{plan.exercises|count=5} · {plan.linear}"></ex-row>  <!-- a template -->
+<ex-row meta="Sun, 4 Oct · 7,920 kg"
+  data-t-meta="{@date|value=2026-10-04;weekday=short;day=numeric;month=short} · {@number|value=7920} {unit.kg}"></ex-row>
+```
+
+```json
+"i18n": {
+  "source": "en",
+  "locales": ["en", "de", "ru", "ar"],
+  "messages": { "en": "src/i18n/en.ts", "*": "src/i18n/locales/{locale}.ts" },
+  "check": ["de", "ar"]
+}
+```
+
+Messages are JSON or a JS/TS module (its default export, else its first exported object); nested objects become
+dotted keys, and plurals are objects keyed by CLDR category (`one`, `few`, `other`…). A value with braces is a
+template: each `{key|name=value;…}` becomes its message and the rest is kept, and `{@date|…}` and `{@number|…}`
+format with `Intl` in the screen's language. Two pseudo-languages need
+no translations: **pseudo** makes every text about 40% longer, accented and bracketed, so cut text shows, and
+**pseudo-rtl** lays the page out right to left.
+
+- The canvas's Language switch (`L`) shows every screen in one language; the **Languages** page shows each
+  screen side by side in the check languages, or in all of them, with the number of missing translations.
+- `stitch2 check` runs every screen in pseudo, pseudo-rtl and the locales in `check`; an issue that only shows
+  in one language carries it ("pseudo: Text overflows…"). A key missing from the source messages is an error.
+- `stitch2 i18n` lists, per screen, keys the source or a locale lacks, translations whose `{placeholders}`
+  differ, and text with no key; `--suggest` names existing messages with the same text.
+- Components that draw their own labels read them with `translate(key, fallback)` from `stitch2/elements`.
+
+The `stitch2-i18n` skill teaches agents to write keyed screens and to fix text that does not fit: room in the
+layout first, then a shorter natural word, never a smaller type size.
+
 ## Commands
 
 | Command | What it does |
@@ -191,7 +237,8 @@ controls' labels nearly touching) and `clipped`.
 | `stitch2 init --name N --primary #hex [options]` | Writes a complete DESIGN.md from a few choices |
 | `stitch2 extract <url or file…>` | Writes a DESIGN.md measured from an existing site or screens |
 | `stitch2 canvas` | The canvas at http://localhost:4400 (`PORT` and `HOST` to change) |
-| `stitch2 check [filter] [--shots] [--strict]` | All checks, in every theme; `--shots` saves renders to `<design>/renders/` (`--light.png` for the other theme) |
+| `stitch2 check [filter] [--shots] [--strict] [--locales l,…]` | All checks, in every theme and check language; `--shots` saves renders to `<design>/renders/` (`--light.png`, `--pseudo.png`…) |
+| `stitch2 i18n [filter] [--locale l] [--suggest] [--json]` | Message keys the source or a locale lacks, and screen text with no key |
 | `stitch2 consistency [kind…]` | The consistency report, `<design>/consistency/index.html` |
 | `stitch2 type [filter] [--json]` | The type audit |
 | `stitch2 screens [name] [--status s] [--json]` | Versions, statuses and notes |

package/config.schema.json

@@ -67,6 +67,30 @@
       "items": { "type": "string" },
       "description": "The themes every screen must work in, by their data-theme value. Defaults to DESIGN.md's: dark (the plain colours), plus light when it has light-* colours. The canvas switches between them and check runs in each."
     },
+    "i18n": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Languages. Screens mark product text with message keys (data-t, data-t-<attr>, data-t-args); the canvas switches language and check runs each screen in the pseudo-languages and the locales in check.",
+      "properties": {
+        "source": { "type": "string", "default": "en", "description": "The language screens are written in." },
+        "locales": { "type": "array", "items": { "type": "string" }, "description": "Locales with translations, besides the source language." },
+        "messages": {
+          "description": "Message files, relative to this file: JSON or a JS/TS module (default export, else its first exported object). A pattern with {locale}, or a map per locale with * for the rest.",
+          "oneOf": [
+            { "type": "string" },
+            { "type": "object", "additionalProperties": { "type": "string" } }
+          ]
+        },
+        "check": {
+          "description": "Locales stitch2 check runs besides pseudo and pseudo-rtl, or \"all\".",
+          "oneOf": [
+            { "type": "array", "items": { "type": "string" } },
+            { "const": "all" }
+          ]
+        },
+        "rtl": { "type": "array", "items": { "type": "string" }, "description": "Right-to-left locales, if not ar, he, fa, ur, ps and yi." }
+      }
+    },
     "skills": {
       "type": "array",
       "items": {

package/dist/canvas.html

@@ -27,6 +27,7 @@
   .seg button { background: none; border: 0; border-radius: 6px; color: var(--muted); cursor: pointer; flex: 1; padding: 4px 6px; white-space: nowrap; }
   .seg button.on { background: var(--panel2); color: var(--text); }
   .seg[hidden] { display: none; }
+  #langFilter { background: var(--bg); border: 1px solid var(--edge); border-radius: 8px; color: var(--text); padding: 5px 8px; width: 100%; }
   #tree { flex: 1; overflow: auto; padding: 6px 8px 16px; }
   #tree h4 { color: var(--faint); font-size: 11px; letter-spacing: .06em; margin: 14px 6px 6px; text-transform: uppercase; }
   .item { align-items: center; background: none; border: 0; border-radius: 6px; color: var(--muted); cursor: pointer; display: flex; gap: 8px; padding: 6px 8px; text-align: left; width: 100%; }
@@ -107,6 +108,7 @@
     <div class="seg" id="statusFilter"><button type="button" data-v="active" class="on" title="Everything except archived versions">Active</button><button type="button" data-v="approved" title="The reference versions agents build on">Approved</button><button type="button" data-v="review" title="Finished by an agent, waiting for your decision">Needs review</button><button type="button" data-v="all" title="Including archived versions">All</button></div>
     <div class="seg" id="deviceFilter"><button type="button" data-v="all" class="on">All devices</button><button type="button" data-v="mobile">Mobile</button><button type="button" data-v="desktop">Desktop</button></div>
     <div class="seg" id="themeFilter" hidden title="Show every screen in this theme (T)"></div>
+    <select id="langFilter" title="Show every screen in this language (L)" aria-label="Language"></select>
   </header>
   <nav id="tree"></nav>
   <footer>
@@ -140,8 +142,29 @@ let designDir = 'design'
 let THEMES = ['dark']
 let theme = localStorage.getItem('stitch2-theme') ?? 'dark'
 const themed = () => THEMES.length > 1
-const themeNote = () => (themed() && theme !== THEMES[0] ? ` in the ${theme} theme` : '')
-const forTheme = (issues) => (issues ?? []).filter((i) => !i.theme || !themed() || i.theme === theme)
+// Languages: screens reload in the one picked (?lang=…); the source language shows them as written.
+let LANGS = ['en']
+let SOURCE = 'en'
+let lang = localStorage.getItem('stitch2-lang') ?? 'en'
+const langQuery = () => (lang === SOURCE ? '' : `&lang=${encodeURIComponent(lang)}`)
+const themeNote = () =>
+  [themed() && theme !== THEMES[0] ? `in the ${theme} theme` : '', lang !== SOURCE ? `in ${lang}` : '']
+    .filter(Boolean)
+    .map((s) => ' ' + s)
+    .join(',')
+const forTheme = (issues) =>
+  (issues ?? []).filter((i) => (!i.theme || !themed() || i.theme === theme) && (!i.locale || i.locale === lang))
+const langName = (l) =>
+  l === 'pseudo' ? 'Pseudo: long text' : l === 'pseudo-rtl' ? 'Pseudo: right to left' : `${new Intl.DisplayNames([l], { type: 'language' }).of(l) ?? l} (${l})${l === SOURCE ? ', source' : ''}`
+function setLang(l) {
+  lang = l
+  localStorage.setItem('stitch2-lang', l)
+  document.getElementById('langFilter').value = l
+  for (const f of frames.values()) f.iframe.src = `/${f.screen.path}?pick${langQuery()}`
+  for (const f of frames.values()) badge(f)
+  if (selected) inspector(selected)
+  summary()
+}
 function applyTheme(f) {
   if (!themed()) return
   try { f.iframe.contentDocument.documentElement.dataset.theme = theme } catch {}
@@ -283,6 +306,7 @@ function tree() {
   item('DESIGN.md', 'tokens · rules', docOpen('/design'), () => openDoc('/design'))
   item('Consistency report', 'components × screens', docOpen('/consistency/index.html'), () => openDoc('/consistency/index.html'))
   item('App comparison', 'approved × live app', docOpen('/compare/index.html'), () => openDoc('/compare/index.html'))
+  item('Languages', 'screens × languages', docOpen('/languages'), () => openDoc('/languages'))
   const all = rows()
   const comp = all.find((r) => r.key === '~components')
   if (comp?.visible.length) {
@@ -379,7 +403,7 @@ function frameFor(s) {
   const iframe = el.querySelector('iframe')
   iframe.style.width = `${s.width}px`
   iframe.style.height = `${s.width > 700 ? 800 : 844}px`
-  iframe.src = `/${s.path}?pick`
+  iframe.src = `/${s.path}?pick${langQuery()}`
   const f = { el, iframe, screen: s, height: s.width > 700 ? 800 : 844 }
   iframe.addEventListener('load', () => { applyTheme(f); measure(f); setTimeout(() => measure(f), 800); setTimeout(() => measure(f), 2500) })
   el.querySelector('.shield').addEventListener('click', () => select(f, false))
@@ -410,7 +434,7 @@ function inspector(f) {
   const s = f.screen
   const issues = forTheme(checks.screens?.[s.path])
   box.innerHTML = `<h3><span class="dot ${s.status}"></span><span class="h"></span><button type="button" class="copy" title="Copy a reference to paste to an agent">Copy</button><button type="button" class="close" title="Close (Esc)">×</button></h3>
-    <div class="facts"><span class="f"></span> · <a target="_blank"></a></div>
+    <div class="facts"><span class="f"></span> · <a target="_blank"></a> · <a href="#" class="langs" title="This screen in every language, side by side">languages</a></div>
     ${s.kind === 'screen' ? `<div class="status">${['approved', 'review', 'draft', 'archived'].map((st) => `<button type="button" data-st="${st}" title="${STATUS_HINT[st]}" class="${s.status === st ? 'on' : ''}">${st === 'approved' ? 'Approve' : st === 'review' ? 'Needs review' : st === 'draft' ? 'Draft' : 'Archive'}</button>`).join('')}</div>
     <textarea placeholder="Note for the agent: what to keep, what to change"></textarea><button type="button" class="save">Save note</button>` : ''}
     <h4>Checks</h4><ul></ul>`
@@ -445,6 +469,7 @@ function inspector(f) {
   const a = box.querySelector('.facts a')
   a.href = `/${s.path}`
   a.textContent = s.path
+  box.querySelector('.facts .langs').onclick = (e) => { e.preventDefault(); openDoc(`/languages?screen=${encodeURIComponent(s.path)}`) }
   box.querySelector('h3 .close').onclick = () => select(null)
   box.querySelector('h3 .copy').onclick = () => copy(ref(s))
   for (const b of box.querySelectorAll('.status button')) b.onclick = () => setMeta(s.path, { status: b.dataset.st })
@@ -508,14 +533,15 @@ function elementAt(e) {
   return el ? { f, el } : null
 }
 function describe(el) {
+  const key = el.closest('[data-s2-key]')?.getAttribute('data-s2-key')
   const text = (el.innerText || el.getAttribute('aria-label') || el.getAttribute('placeholder') || el.getAttribute('alt') || el.value || '').trim().replace(/\s+/g, ' ')
-  return { tag: el.getAttribute('data-s2-tag') ?? el.localName, line: el.getAttribute('data-s2-line'), text: text.length > 48 ? `${text.slice(0, 47)}…` : text }
+  return { tag: el.getAttribute('data-s2-tag') ?? el.localName, line: el.getAttribute('data-s2-line'), key, text: text.length > 48 ? `${text.slice(0, 47)}…` : text }
 }
 function elementRef(f, el) {
   const d = describe(el)
   const s = f.screen
   const who = s.kind === 'components' ? 'component catalog' : `${s.screen} ${s.device} ${s.version}`
-  return `${who}${themeNote()} (${designDir}/${s.path}:${d.line}) <${d.tag}>${d.text ? ` “${d.text}”` : ''}`
+  return `${who}${themeNote()} (${designDir}/${s.path}:${d.line}) <${d.tag}>${d.text ? ` “${d.text}”` : ''}${d.key ? ` [${d.key}]` : ''}`
 }
 function drawBox(f, el, cls, label) {
   const r = el.getBoundingClientRect()
@@ -682,6 +708,7 @@ addEventListener('keydown', (e) => {
   if (e.key === 'Escape') { closeDoc(); select(null) }
   if (e.key === 'f' || e.key === 'F') fit()
   if ((e.key === 't' || e.key === 'T') && themed()) setTheme(THEMES[(THEMES.indexOf(theme) + 1) % THEMES.length])
+  if (e.key === 'l' || e.key === 'L') setLang(LANGS[(LANGS.indexOf(lang) + 1) % LANGS.length])
   if (e.key === '0') zoomAt((innerWidth - SIDE) / 2, innerHeight / 2, 1)
   if (e.key === '+' || e.key === '=') zoomAt((innerWidth - SIDE) / 2, innerHeight / 2, view.z * 1.2)
   if (e.key === '-') zoomAt((innerWidth - SIDE) / 2, innerHeight / 2, view.z / 1.2)
@@ -712,6 +739,13 @@ fetch('/api/config').then((r) => r.json()).then((c) => {
   seg.innerHTML = THEMES.map((t) => `<button type="button" data-v="${t}">${t[0].toUpperCase()}${t.slice(1)}</button>`).join('')
   for (const b of seg.querySelectorAll('button')) b.onclick = () => setTheme(b.dataset.v)
   setTheme(theme)
+  SOURCE = c.sourceLocale ?? 'en'
+  LANGS = c.locales?.length ? c.locales : [SOURCE]
+  if (!LANGS.includes(lang)) lang = SOURCE
+  const sel = document.getElementById('langFilter')
+  sel.innerHTML = LANGS.map((l) => `<option value="${l}">${langName(l)}</option>`).join('')
+  sel.value = lang
+  sel.onchange = () => setLang(sel.value)
   document.title = c.name
   load(true)
 })

package/dist/check.js

@@ -5,7 +5,10 @@
  * the canvas shows as badges.
  * Every screen is checked in its own theme, then again in each other theme DESIGN.md defines (designThemes):
  * colours change there, so contrast is checked again, tagged with the theme.
- * Usage: stitch2 check [path filter…] [--shots] [--strict]
+ * Then again in each check language (i18n.ts: the pseudo-languages and the config's): layout problems that
+ * show only there (a label running into its neighbour, text cut off, a control drawn backwards right to left),
+ * and keys a locale has no translation for, tagged with the locale.
+ * Usage: stitch2 check [path filter…] [--shots] [--strict] [--locales ru,ar | all | none]
  *   --shots   also save page-tall renders to design/renders/ (one per theme)
  *   --strict  exit 1 when any screen has errors (for CI and agent loops)
  */
@@ -16,6 +19,7 @@ import { colourIssues } from './colours.js';
 import { config } from './config.js';
 import { collectComponents, collectOptions, consistencyIssues, reuseIssues, } from './consistency.js';
 import { designThemes, typeLevels } from './design-md.js';
+import { checkLocales } from './i18n.js';
 import { listScreens, ROOT } from './screens.js';
 import { startServer } from './serve.js';
 import { collectText, typeIssues } from './typecheck.js';
@@ -23,7 +27,9 @@ import { audit } from './audit.js';
 const args = process.argv.slice(2);
 const shots = args.includes('--shots');
 const strict = args.includes('--strict');
-const filters = args.filter((a) => !a.startsWith('--'));
+const localesFlag = args.indexOf('--locales');
+const locales = checkLocales(localesFlag >= 0 ? args[localesFlag + 1] : undefined);
+const filters = args.filter((a, i) => !a.startsWith('--') && (localesFlag < 0 || i !== localesFlag + 1));
 const screens = listScreens().filter((s) => !filters.length || filters.some((f) => s.path.includes(f)));
 const levels = typeLevels();
 const themes = designThemes();
@@ -61,15 +67,58 @@ for (const s of screens) {
     }
     if (themes.length > 1)
         await setTheme(base);
+    const typed = typeIssues(levels, await page.evaluate(collectText));
+    if (shots)
+        await shoot(s);
+    // The other languages, in the screen's own theme. Reported once per element and kind, in the first locale.
+    const unknownSeen = new Set();
+    for (const locale of locales) {
+        await page
+            .goto(`http://127.0.0.1:${server.port}/${s.path}?lang=${encodeURIComponent(locale)}`, { waitUntil: 'networkidle', timeout: 30_000 })
+            .catch(() => { });
+        await page.waitForTimeout(600);
+        for (const i of await page.evaluate(audit, { comfortable: config.comfortableTarget })) {
+            const key = `${i.type} ${i.selector}`;
+            if (i.type === 'contrast' || seen.has(key))
+                continue;
+            seen.add(key);
+            themed.push({ ...i, locale, message: `${locale}: ${i.message}` });
+        }
+        const lost = await page.evaluate(() => window.__stitch2?.missing ?? []);
+        for (const m of lost) {
+            const selector = `[data-s2-key="${m.all}"]`;
+            const unknown = m.unknown.split(' ').filter(Boolean);
+            const fresh = unknown.filter((k) => !unknownSeen.has(k));
+            fresh.forEach((k) => unknownSeen.add(k));
+            if (fresh.length)
+                themed.push({
+                    severity: 'error',
+                    type: 'i18n-unknown-key',
+                    selector,
+                    text: m.text,
+                    message: `No message for ${fresh.join(' ')}: add it to the source language's messages`,
+                });
+            const lacks = m.keys.split(' ').filter((k) => !unknown.includes(k));
+            if (lacks.length)
+                themed.push({
+                    severity: 'warning',
+                    type: 'i18n-missing',
+                    locale,
+                    selector,
+                    text: m.text,
+                    message: `${locale}: no translation for ${lacks.join(' ')}`,
+                });
+        }
+        if (shots)
+            await shoot(s, undefined, locale);
+    }
     results[s.path] = [
         ...layout,
         ...themed,
-        ...typeIssues(levels, await page.evaluate(collectText)),
+        ...typed,
         ...reuseIssues(s.path, found),
         ...colourIssues(s.path),
     ];
-    if (shots)
-        await shoot(s);
 }
 await browser.close();
 server.close();
@@ -79,12 +128,13 @@ async function setTheme(theme) {
     }, theme);
     await page.waitForTimeout(150);
 }
-/** A page-tall render; renders in another theme than the screen's own get a --<theme> suffix. */
-async function shoot(s, theme) {
+/** A page-tall render; renders in another theme or language than the screen's own get a --<theme> suffix. */
+async function shoot(s, theme, locale) {
     const height = await page.evaluate(() => document.documentElement.scrollHeight);
     await page.setViewportSize({ width: s.width, height: Math.max(844, Math.min(height, 6000)) });
     mkdirSync(join(ROOT, 'renders'), { recursive: true });
-    const name = s.path.replaceAll('/', '__').replace(/\.html$/, theme ? `--${theme}.png` : '.png');
+    const suffix = theme ?? locale;
+    const name = s.path.replaceAll('/', '__').replace(/\.html$/, suffix ? `--${suffix}.png` : '.png');
     await page.screenshot({ path: join(ROOT, 'renders', name) });
     await page.setViewportSize({ width: s.width, height: 844 });
 }

package/dist/cli.js

@@ -38,6 +38,10 @@ const COMMANDS = {
     compare: ['compare.ts', '[screen…] [--strict]  The live app against the approved screens ("app" in the config)'],
     elements: ['build-elements.ts', '<entry> [--out file]  Bundle the project\'s components (defineElements) for the screens'],
     lint: ['', "Google's DESIGN.md linter on the project's DESIGN.md"],
+    i18n: [
+        'i18n-report.ts',
+        '[filter] [--locale l] [--suggest] [--json]  Keys screens use that a locale lacks, and screen text with no key',
+    ],
     screens: ['list.ts', '[name] [--status s] [--json]  Screen versions, statuses and notes'],
     localize: ['assets.ts', '[filter]  Copy remote images a screen uses into its assets/ folder'],
     sandbox: [

package/dist/config.d.ts

@@ -38,6 +38,8 @@ export interface LabConfig {
             prepare?: string;
         }>;
     };
+    /** Languages: message files the screens' data-t keys come from (see i18n.ts). */
+    i18n?: I18nConfig;
     /** Token files stitch2 tokens also writes for the app (see exports.ts). */
     exports?: {
         format: 'css' | 'tailwind4' | 'dtcg';
@@ -49,6 +51,18 @@ export interface LabConfig {
         };
     }[];
 }
+export interface I18nConfig {
+    /** Locales with translations, besides the source language. */
+    locales?: string[];
+    /** The language screens are written in (default en). */
+    source?: string;
+    /** Where messages live, relative to the config: "src/i18n/{locale}.json", or per locale with "*" as the rest. */
+    messages?: string | Record<string, string>;
+    /** Locales stitch2 check runs besides the pseudo-languages ("all" for every one). */
+    check?: string[] | 'all';
+    /** Right-to-left locales, if not the usual (ar, he, fa, ur, ps, yi). */
+    rtl?: string[];
+}
 export declare const CONFIG_NAME = "stitch2.config.json";
 export declare const CONFIG_FILE: string | undefined;
 /** The folder paths in the config are relative to (the project root). */

package/dist/elements.d.ts

@@ -29,4 +29,13 @@ export interface ElementsOptions<C> {
     /** Runs after every element has rendered, e.g. to draw icon placeholders (lucide.createIcons). */
     after?: () => void;
 }
+/**
+ * A message in the locale the screen is shown in (the canvas's Language switch), for labels a component draws
+ * itself. Without one (the source language, or outside stitch2) it returns the fallback.
+ *
+ *   render: (C, props) => renderToStaticMarkup(createElement(C, { labels: { home: translate('nav.home', 'Home') }, ...props }))
+ */
+export declare function translate(key: string, fallback: string, args?: Record<string, string>): string;
+/** The locale the screen is shown in ("en", "ru", "ar-XB" for the right-to-left pseudo-language), or undefined. */
+export declare const screenLocale: () => string | undefined;
 export declare function defineElements<C>(components: Record<string, C>, options: ElementsOptions<C>): void;

package/dist/elements.js

@@ -18,6 +18,18 @@
  * values stay strings. The element's content becomes children, rendered where the component puts them.
  * Bundle the entry with `stitch2 elements <entry>› and load the bundle in the screens and the template.
  */
+/**
+ * A message in the locale the screen is shown in (the canvas's Language switch), for labels a component draws
+ * itself. Without one (the source language, or outside stitch2) it returns the fallback.
+ *
+ *   render: (C, props) => renderToStaticMarkup(createElement(C, { labels: { home: translate('nav.home', 'Home') }, ...props }))
+ */
+export function translate(key, fallback, args) {
+    const s = globalThis.__stitch2;
+    return s?.t(key, args) ?? fallback;
+}
+/** The locale the screen is shown in ("en", "ru", "ar-XB" for the right-to-left pseudo-language), or undefined. */
+export const screenLocale = () => globalThis.__stitch2?.lang;
 const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 export function defineElements(components, options) {
     const { prefix, render } = options;
@@ -30,7 +42,8 @@ export function defineElements(components, options) {
             connectedCallback() {
                 const props = {};
                 for (const a of Array.from(this.attributes)) {
-                    if (a.name.startsWith('data-s2-'))
+                    // stitch2's own markers and the message keys (i18n.ts translated them already) are not props.
+                    if (a.name.startsWith('data-s2-') || a.name === 'data-t' || a.name.startsWith('data-t-'))
                         continue;
                     props[camel(a.name)] = a.value === '' ? true : a.value;
                 }

package/dist/i18n-report.d.ts

@@ -0,0 +1,17 @@
+interface Use {
+    key: string;
+    line: number;
+    plural: boolean;
+}
+interface Loose {
+    text: string;
+    line: number;
+    attr?: string;
+    suggest?: string[];
+}
+/** The keys a screen uses and its text with no key, from its markup (scripts, styles and SVG left out). */
+export declare function scan(html: string): {
+    uses: Use[];
+    loose: Loose[];
+};
+export {};

package/dist/i18n-report.js

@@ -0,0 +1,138 @@
+/**
+ * How far the screens are translated, for agents writing them in several languages:
+ *
+ *   stitch2 i18n [filter] [--locale l] [--suggest] [--json]
+ *
+ * Errors: keys screens use (data-t, data-t-<attr>) that the source messages lack, which show the screen's own
+ * text in every language. Warnings: keys a locale lacks (they fall back to the source language), translations
+ * whose {placeholders} differ from the source's, and product text in screens with no key. Text that is sample
+ * content (names, numbers, user input) opts out with translate="no" or data-t-skip. --suggest names source
+ * messages with the same text as an unkeyed one. Archived screens are skipped. Exits 1 on errors.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ROOT } from './config.js';
+import { loadMessages, realLocales, sourceLocale } from './i18n.js';
+import { listScreens } from './screens.js';
+const args = process.argv.slice(2);
+const opt = (n) => (args.includes(n) ? args[args.indexOf(n) + 1] : undefined);
+const filter = args.find((a, i) => !a.startsWith('--') && args[i - 1] !== '--locale');
+const locales = opt('--locale')?.split(',') ?? realLocales();
+const suggest = args.includes('--suggest');
+/** Attributes that hold text people read. On components (a dash in the tag) any attribute that reads as words. */
+const TEXT_ATTRS = new Set(['title', 'label', 'placeholder', 'aria-label', 'alt']);
+const NOT_TEXT = /^(class|id|style|href|src|srcset|type|name|value|for|role|slot|lang|dir|icon|variant|tone|size|width|height|viewbox|d|fill|stroke|xmlns|rel|target|tabindex|loading|translate)$/;
+const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr']);
+const words = (s) => /\p{L}{2,}/u.test(s);
+const readsAsText = (s) => words(s) && (/\s/.test(s.trim()) || /\p{Lu}/u.test(s) || /[^\x00-\x7f]/.test(s));
+function attrsOf(s) {
+    const out = {};
+    for (const m of s.matchAll(/([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g))
+        out[m[1].toLowerCase()] = m[2] ?? m[3] ?? m[4] ?? '';
+    return out;
+}
+/** The keys a screen uses and its text with no key, from its markup (scripts, styles and SVG left out). */
+export function scan(html) {
+    const uses = [];
+    const loose = [];
+    const body = html.replace(/<(script|style|svg|template)\b[\s\S]*?<\/\1>|<!--[\s\S]*?-->/gi, (m) => m.replace(/[^\n]/g, ' '));
+    const start = body.search(/<body\b/i);
+    const lineAt = (i) => body.slice(0, i).split('\n').length;
+    const stack = [];
+    const re = /<(\/?)([a-zA-Z][\w-]*)((?:"[^"]*"|'[^']*'|[^>"'])*?)(\/?)>|([^<]+)/g;
+    re.lastIndex = Math.max(0, start);
+    for (let m = re.exec(body); m; m = re.exec(body)) {
+        const line = lineAt(m.index);
+        const top = stack[stack.length - 1];
+        if (m[5] !== undefined) {
+            const text = m[5].replace(/\s+/g, ' ').trim();
+            if (words(text) && !top?.keyed && !top?.skip)
+                loose.push({ text: text.replaceAll('&amp;', '&'), line });
+            continue;
+        }
+        const tag = m[2].toLowerCase();
+        if (m[1]) {
+            const at = stack.map((s) => s.tag).lastIndexOf(tag);
+            if (at >= 0)
+                stack.length = at;
+            continue;
+        }
+        const a = attrsOf(m[3]);
+        const plural = 'data-t-args' in a && /(^|,)\s*count\s*=/.test(a['data-t-args']);
+        const skip = !!top?.skip || 'data-t-skip' in a || a.translate === 'no';
+        for (const [name, value] of Object.entries(a)) {
+            const keyed = name === 'data-t' || (name.startsWith('data-t-') && name !== 'data-t-args' && name !== 'data-t-skip');
+            if (keyed && value.includes('{'))
+                for (const m of value.matchAll(/\{([^{}|@][^{}|]*)(?:\|([^}]*))?\}/g))
+                    uses.push({ key: m[1], line, plural: plural || /(^|;)\s*count\s*=/.test(m[2] ?? '') });
+            else if (name === 'data-t')
+                uses.push({ key: value, line, plural });
+            else if (keyed)
+                for (const k of value.split(','))
+                    uses.push({ key: k.trim(), line, plural });
+            else if (!skip && !name.startsWith('data-') && !NOT_TEXT.test(name) && !('data-t-' + name in a)) {
+                const textual = TEXT_ATTRS.has(name) ? words(value) : tag.includes('-') && readsAsText(value);
+                if (textual)
+                    loose.push({ text: value, line, attr: name });
+            }
+        }
+        if (!m[4] && !VOID.has(tag))
+            stack.push({ tag, keyed: !!top?.keyed || 'data-t' in a, skip });
+    }
+    return { uses, loose };
+}
+const has = (msgs, u) => u.key in msgs || (u.plural && u.key + '.other' in msgs);
+const holes = (s) => [...s.matchAll(/\{(\w+)\}/g)].map((m) => m[1]).sort().join(',');
+const source = await loadMessages(sourceLocale());
+const byLocale = Object.fromEntries(await Promise.all(locales.map(async (l) => [l, await loadMessages(l)])));
+const byText = new Map();
+for (const [k, v] of Object.entries(source)) {
+    const n = v.trim().toLowerCase();
+    byText.set(n, [...(byText.get(n) ?? []), k]);
+}
+const screens = listScreens().filter((s) => s.kind === 'screen' && s.status !== 'archived' && (!filter || s.path.includes(filter) || s.screen === filter));
+const report = screens.map((s) => {
+    const { uses, loose } = scan(readFileSync(join(ROOT, s.path), 'utf8'));
+    const unknown = uses.filter((u) => !has(source, u));
+    const missing = {};
+    const placeholders = [];
+    for (const l of locales) {
+        const msgs = byLocale[l];
+        const lacks = [...new Set(uses.filter((u) => has(source, u) && !has(msgs, u)).map((u) => u.key))];
+        if (lacks.length)
+            missing[l] = lacks;
+        for (const u of uses)
+            if (u.key in msgs && u.key in source && holes(msgs[u.key]) !== holes(source[u.key]))
+                placeholders.push({ locale: l, key: u.key });
+    }
+    if (suggest)
+        for (const x of loose)
+            x.suggest = byText.get(x.text.toLowerCase());
+    return { path: s.path, keys: new Set(uses.map((u) => u.key)).size, unknown, missing, placeholders, loose };
+});
+if (args.includes('--json'))
+    console.log(JSON.stringify({ source: sourceLocale(), locales, screens: report }, null, 2));
+else {
+    if (!Object.keys(source).length)
+        console.log('No source messages: set i18n.messages in stitch2.config.json (see the stitch2-i18n skill).\n');
+    for (const r of report) {
+        const lines = [];
+        for (const u of r.unknown)
+            lines.push(`  error  line ${u.line}: ${u.key} is not in the ${sourceLocale()} messages`);
+        for (const [l, keys] of Object.entries(r.missing))
+            lines.push(`  warn   ${l} lacks ${keys.length}: ${keys.join(', ')}`);
+        for (const p of r.placeholders)
+            lines.push(`  warn   ${p.locale} ${p.key}: placeholders differ from ${sourceLocale()}`);
+        for (const x of r.loose)
+            lines.push(`  text   line ${x.line}${x.attr ? ` [${x.attr}]` : ''}: "${x.text.slice(0, 60)}" has no key${x.suggest ? ` (${x.suggest.join(' or ')}?)` : ''}`);
+        console.log(`${r.path}  ${r.keys} keys${lines.length ? '' : ', all translated'}`);
+        if (lines.length)
+            console.log(lines.join('\n'));
+    }
+    const errors = report.reduce((n, r) => n + r.unknown.length, 0);
+    const loose = report.reduce((n, r) => n + r.loose.length, 0);
+    const lacking = locales.filter((l) => report.some((r) => r.missing[l]));
+    console.log(`\n${screens.length} screens, ${errors} unknown keys, ${loose} texts with no key${lacking.length ? `, missing translations in ${lacking.join(', ')}` : ''}.`);
+}
+if (report.some((r) => r.unknown.length))
+    process.exitCode = 1;

package/dist/i18n.d.ts

@@ -0,0 +1,29 @@
+import { type I18nConfig } from './config.ts';
+export type { I18nConfig };
+export declare const PSEUDO: readonly ['pseudo', 'pseudo-rtl'];
+export declare const i18nConfig: () => I18nConfig;
+export declare const sourceLocale: () => string;
+export declare const realLocales: () => string[];
+export declare const isRtl: (locale: string) => boolean;
+/** Every language the canvas offers: the source, the pseudo-languages, and the project's own. */
+export declare const allLocales: () => string[];
+/** The locales check runs: with an i18n block, the pseudo-languages plus the configured ones; else only --locales. */
+export declare function checkLocales(override?: string): string[];
+/**
+ * A locale's messages: JSON, or a JS/TS module (its default export, else its first exported object; Node strips
+ * the types). Re-read when the file changes. Empty when the file is missing.
+ */
+export declare function loadMessages(locale: string): Promise<Record<string, string>>;
+/** What a page needs to show a locale: its messages over the source language's, and its direction. */
+export declare function pagePayload(locale: string): Promise<{
+    locale: string;
+    lang: string;
+    dir: string;
+    pseudo: boolean;
+    messages: {
+        [x: string]: string;
+    };
+    missing: string[];
+}>;
+/** The script for a screen opened in a locale; serve adds it after pick mode has numbered the lines. */
+export declare function localeScript(locale: string): Promise<string>;

package/dist/i18n.js

@@ -0,0 +1,275 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Languages for screens. A screen is written in the source language and marks the text that belongs to the product
+ * with message keys from the project's own translation files:
+ *
+ *   <span data-t="nav.library">Exercises</span>                 the element's text
+ *   <gg-header title="Settings" data-t-title="settings.title">  an attribute (also comma lists: data-t-options)
+ *   <p data-t="count.sets" data-t-args="count=16">16 sets</p>   {count} filled in, plural form picked by count
+ *   <x-row meta="5 exercises · Linear" data-t-meta="{plan.count|count=5} · {plan.linear}">
+ *                                                                a template: messages in braces, the rest kept
+ *   <x-row meta="Sun, 4 Oct" data-t-meta="{@date|value=2026-10-04;weekday=short;day=numeric;month=short}">
+ *                                                                dates and numbers ({@number|value=7920}) by Intl
+ *
+ * Opened with ?lang=<locale> (the canvas's Language switch, and check), the page's text is replaced from that
+ * locale's messages before its components render, and the page gets lang and dir. Two pseudo-languages need no
+ * translations: "pseudo" makes every text about 40% longer with accented letters, "pseudo-rtl" lays the page out
+ * right to left. Project components can read the same messages with translate() from stitch2/elements.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { extname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { BASE, config } from './config.js';
+export const PSEUDO = ['pseudo', 'pseudo-rtl'];
+const RTL = ['ar', 'he', 'fa', 'ur', 'ps', 'yi'];
+export const i18nConfig = () => config.i18n ?? {};
+export const sourceLocale = () => i18nConfig().source ?? 'en';
+export const realLocales = () => i18nConfig().locales?.filter((l) => l !== sourceLocale()) ?? [];
+export const isRtl = (locale) => locale === 'pseudo-rtl' || (i18nConfig().rtl ?? RTL).includes(locale.split('-')[0].toLowerCase());
+/** Every language the canvas offers: the source, the pseudo-languages, and the project's own. */
+export const allLocales = () => [sourceLocale(), ...PSEUDO, ...realLocales()];
+/** The locales check runs: with an i18n block, the pseudo-languages plus the configured ones; else only --locales. */
+export function checkLocales(override) {
+    if (override === 'none')
+        return [];
+    const list = override ? (override === 'all' ? [...PSEUDO, ...realLocales()] : override.split(',')) : undefined;
+    if (list)
+        return list.filter((l) => l !== sourceLocale());
+    if (!config.i18n)
+        return [];
+    const c = i18nConfig().check;
+    return [...PSEUDO, ...(c === 'all' ? realLocales() : (c ?? []))];
+}
+function messagesFile(locale) {
+    const m = i18nConfig().messages;
+    if (!m)
+        return undefined;
+    const pattern = typeof m === 'string' ? m : (m[locale] ?? m['*']);
+    return pattern ? resolve(BASE, pattern.replaceAll('{locale}', locale)) : undefined;
+}
+/** Nested objects become dotted keys; only strings are kept. */
+function flatten(o, prefix = '', out = {}) {
+    if (o && typeof o === 'object')
+        for (const [k, v] of Object.entries(o)) {
+            const key = prefix ? prefix + '.' + k : k;
+            if (typeof v === 'string')
+                out[key] = v;
+            else
+                flatten(v, key, out);
+        }
+    return out;
+}
+const cache = new Map();
+/**
+ * A locale's messages: JSON, or a JS/TS module (its default export, else its first exported object; Node strips
+ * the types). Re-read when the file changes. Empty when the file is missing.
+ */
+export async function loadMessages(locale) {
+    const file = messagesFile(locale);
+    if (!file || !existsSync(file))
+        return {};
+    const at = statSync(file).mtimeMs;
+    const hit = cache.get(file);
+    if (hit && hit.at === at)
+        return hit.messages;
+    let data;
+    if (extname(file) === '.json')
+        data = JSON.parse(readFileSync(file, 'utf8'));
+    else {
+        const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href + '?t=' + at)));
+        data = mod.default ?? Object.values(mod).find((v) => v && typeof v === 'object');
+    }
+    const messages = flatten(data);
+    cache.set(file, { at, messages });
+    return messages;
+}
+/** What a page needs to show a locale: its messages over the source language's, and its direction. */
+export async function pagePayload(locale) {
+    const pseudo = PSEUDO.includes(locale);
+    const source = await loadMessages(sourceLocale());
+    const own = pseudo || locale === sourceLocale() ? {} : await loadMessages(locale);
+    return {
+        locale,
+        lang: locale === 'pseudo' ? sourceLocale() + '-XA' : locale === 'pseudo-rtl' ? 'ar-XB' : locale,
+        dir: isRtl(locale) ? 'rtl' : 'ltr',
+        pseudo: locale === 'pseudo',
+        // Keys the locale lacks fall back to the source language, and are reported.
+        messages: { ...source, ...own },
+        missing: pseudo || locale === sourceLocale() ? [] : Object.keys(source).filter((k) => !(k in own)),
+    };
+}
+/** Runs in the page. Plain JS on purpose: it is sent as source into the screen's head. */
+function runtime(p) {
+    const missing = new Set(p.missing);
+    const plural = new Intl.PluralRules(p.lang);
+    // {@date|value=…;weekday=short…} and {@number|value=…;maximumFractionDigits=1…}: Intl's options, in the locale.
+    const intl = (key, args) => {
+        const opts = {};
+        for (const [k, v] of Object.entries(args))
+            if (k !== 'value')
+                opts[k] = v === 'true' ? true : v === 'false' ? false : /^\d+$/.test(v) ? Number(v) : v;
+        try {
+            return key === '@date'
+                ? // As written, whatever the viewer's time zone: the value is read and shown in UTC.
+                    new Intl.DateTimeFormat(p.lang, { timeZone: 'UTC', ...opts }).format(new Date(/T.*(Z|[+-]\d\d:?\d\d)$/.test(args.value ?? '') || !/T/.test(args.value ?? '') ? (args.value ?? '') : args.value + 'Z'))
+                : new Intl.NumberFormat(p.lang, opts).format(Number(args.value));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const t = (key, args) => {
+        if (key === '@date' || key === '@number')
+            return intl(key, args ?? {});
+        let msg;
+        if (args && args.count !== undefined) {
+            const n = Number(args.count);
+            msg = p.messages[key + '.' + plural.select(n)] ?? p.messages[key + '.other'];
+        }
+        msg = msg ?? p.messages[key];
+        if (msg === undefined)
+            return undefined;
+        return msg.replace(/\{(\w+)\}/g, (m, k) => (args && args[k] !== undefined ? args[k] : m));
+    };
+    const known = (key) => key.startsWith('@') || key in p.messages || key + '.other' in p.messages;
+    const lacks = (key) => missing.has(key) || missing.has(key + '.other') || !known(key);
+    const parseArgs = (s, sep = ',') => {
+        const out = {};
+        for (const part of (s ?? '').split(sep)) {
+            const i = part.indexOf('=');
+            if (i > 0)
+                out[part.slice(0, i).trim()] = part.slice(i + 1).trim();
+        }
+        return out;
+    };
+    const lostList = [];
+    window.__stitch2 = { locale: p.locale, lang: p.lang, dir: p.dir, t, missing: lostList };
+    document.documentElement.lang = p.lang;
+    document.documentElement.dir = p.dir;
+    let done = false;
+    const translate = () => {
+        if (done)
+            return;
+        done = true;
+        for (const el of Array.from(document.querySelectorAll('*'))) {
+            const keys = [];
+            for (const a of Array.from(el.attributes)) {
+                if (a.name !== 'data-t' && !a.name.startsWith('data-t-'))
+                    continue;
+                if (a.name === 'data-t-args' || a.name === 'data-t-skip')
+                    continue;
+                const args = parseArgs(el.getAttribute('data-t-args'));
+                let v;
+                if (a.value.includes('{')) {
+                    // A template: each {key} or {key|name=value;name=value} becomes its message, the rest stays as written.
+                    let whole = true;
+                    v = a.value.replace(/\{([^{}|]+)(?:\|([^}]*))?\}/g, (_m, key, inline) => {
+                        keys.push(key);
+                        const r = t(key, { ...args, ...parseArgs(inline, ';') });
+                        if (r === undefined)
+                            whole = false;
+                        return r ?? '';
+                    });
+                    if (!whole)
+                        v = undefined;
+                }
+                else if (a.name === 'data-t') {
+                    v = t(a.value, args);
+                    keys.push(a.value);
+                }
+                else {
+                    // A list attribute (options="A,B"): one key per item.
+                    const parts = a.value.split(',').map((k) => k.trim());
+                    const vals = parts.map((k) => t(k, args));
+                    if (vals.every((x) => x !== undefined))
+                        v = vals.join(',');
+                    keys.push(...parts);
+                }
+                if (v === undefined)
+                    continue;
+                if (a.name === 'data-t')
+                    el.textContent = v;
+                else
+                    el.setAttribute(a.name.slice(7), v);
+            }
+            if (!keys.length)
+                continue;
+            el.setAttribute('data-s2-key', keys.join(' '));
+            const lost = keys.filter(lacks);
+            if (lost.length) {
+                el.setAttribute('data-s2-i18n-missing', lost.join(' '));
+                lostList.push({
+                    keys: lost.join(' '),
+                    all: keys.join(' '),
+                    text: (el.textContent ?? '').trim().slice(0, 60),
+                    // Not even in the source language: the screen shows its own text in every language.
+                    unknown: lost.filter((k) => !known(k)).join(' '),
+                });
+            }
+        }
+    };
+    // Pseudo-language: every visible text, accented and about 40% longer, bracketed so a cut end shows.
+    const MAP = {
+        a: 'á', b: 'ƀ', c: 'ç', d: 'ð', e: 'é', f: 'ƒ', g: 'ĝ', h: 'ĥ', i: 'í', j: 'ĵ', k: 'ķ', l: 'ļ', m: 'ɱ', n: 'ñ',
+        o: 'ó', p: 'þ', r: 'ŕ', s: 'š', t: 'ţ', u: 'ú', w: 'ŵ', y: 'ý', z: 'ž',
+        A: 'Á', B: 'Ɓ', C: 'Ç', D: 'Ð', E: 'É', G: 'Ĝ', H: 'Ĥ', I: 'Í', J: 'Ĵ', K: 'Ķ', L: 'Ļ', N: 'Ñ', O: 'Ó',
+        R: 'Ŕ', S: 'Š', T: 'Ţ', U: 'Ú', W: 'Ŵ', Y: 'Ý', Z: 'Ž',
+    };
+    const seen = new WeakSet();
+    const stretch = (s) => {
+        const core = s.trim();
+        if (!/\p{L}/u.test(core))
+            return s;
+        const extra = Math.max(1, Math.round(core.length * 0.3));
+        const lead = s.slice(0, s.indexOf(core));
+        return lead + '[' + core.replace(/[A-Za-z]/g, (c) => MAP[c] ?? c) + ' ' + '·'.repeat(extra) + ']' + s.slice(lead.length + core.length);
+    };
+    const SKIP = 'script,style,code,pre,textarea,[data-t-skip],svg';
+    const pseudoAll = (root) => {
+        const w = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+        for (let n = w.nextNode(); n; n = w.nextNode()) {
+            if (seen.has(n) || n.parentElement?.closest(SKIP))
+                continue;
+            seen.add(n);
+            n.textContent = stretch(n.textContent ?? '');
+        }
+        if (root instanceof Element || root instanceof Document)
+            for (const el of Array.from(root.querySelectorAll('[placeholder]'))) {
+                if (el.hasAttribute('data-s2-pseudo'))
+                    continue;
+                el.setAttribute('data-s2-pseudo', '');
+                el.setAttribute('placeholder', stretch(el.getAttribute('placeholder') ?? ''));
+            }
+    };
+    // Translate once the body is parsed and before components render: the first customElements.define (the
+    // components' deferred bundle) or DOMContentLoaded, whichever comes first.
+    const define = customElements.define.bind(customElements);
+    customElements.define = (name, cls, opts) => {
+        translate();
+        return define(name, cls, opts);
+    };
+    document.addEventListener('DOMContentLoaded', () => {
+        translate();
+        if (!p.pseudo)
+            return;
+        pseudoAll(document.body);
+        new MutationObserver((list) => {
+            for (const m of list)
+                for (const n of Array.from(m.addedNodes))
+                    pseudoAll(n);
+        }).observe(document.body, { childList: true, subtree: true });
+    });
+}
+/** The script for a screen opened in a locale; serve adds it after pick mode has numbered the lines. */
+export async function localeScript(locale) {
+    const payload = await pagePayload(locale);
+    const json = JSON.stringify(payload).replaceAll('<', '\\u003c');
+    return '<script>(' + runtime.toString() + ')(' + json + ')</script>';
+}

package/dist/languages-page.d.ts

@@ -0,0 +1 @@
+export declare function languagesPage(only?: string): string;

package/dist/languages-page.js

@@ -0,0 +1,100 @@
+/**
+ * The Languages page (/languages on the canvas server): each screen in a row, once per language, so a label that
+ * only breaks in German or a layout that flips wrong in Arabic shows next to the others. ?screen=<path> shows one
+ * screen; otherwise every active screen. Starts with the check languages; "All" adds every locale.
+ */
+import { allLocales, checkLocales, sourceLocale } from './i18n.js';
+import { listScreens } from './screens.js';
+export function languagesPage(only) {
+    const screens = listScreens()
+        .filter((s) => (only ? s.path === only : s.kind === 'screen' && s.status !== 'archived'))
+        .map((s) => ({ path: s.path, label: s.kind === 'components' ? 'Component catalog' : s.screen + ' ' + s.device + ' ' + s.version, width: s.width }));
+    const data = { screens, source: sourceLocale(), check: [sourceLocale(), ...checkLocales()], all: allLocales() };
+    return `<!doctype html><html><head><meta charset="utf-8"><title>Languages</title><style>
+  body { background: #0f0f11; color: #e4e4e7; font: 13px/1.4 system-ui, sans-serif; margin: 0; }
+  header { align-items: center; background: #0f0f11; border-bottom: 1px solid #26262b; display: flex; gap: 12px; padding: 12px 140px 12px 20px; position: sticky; top: 0; z-index: 1; }
+  header h1 { font-size: 15px; margin: 0 8px 0 0; }
+  header p { color: #71717a; margin: 0 0 0 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .seg { background: #18181b; border: 1px solid #26262b; border-radius: 8px; display: flex; padding: 2px; }
+  .seg button { background: none; border: 0; border-radius: 6px; color: #a1a1aa; cursor: pointer; font: inherit; padding: 4px 10px; }
+  .seg button.on { background: #27272a; color: #fafafa; }
+  section { padding: 16px 20px 8px; }
+  section h2 { color: #a1a1aa; font-size: 13px; font-weight: 600; margin: 0 0 10px; }
+  section h2 code { color: #71717a; font-weight: 400; margin-left: 8px; }
+  .row { align-items: flex-start; display: flex; gap: 24px; overflow-x: auto; padding-bottom: 16px; }
+  .frame { flex: none; }
+  .frame .label { align-items: center; color: #a1a1aa; display: flex; flex-wrap: wrap; gap: 4px 6px; margin-bottom: 6px; min-width: 0; white-space: nowrap; }
+  .frame .label .n { min-width: 0; overflow: hidden; text-overflow: ellipsis; }
+  .frame .label > :not(.n) { flex: none; }
+  .frame .label b { color: #fafafa; }
+  .frame .miss { background: #422006; border-radius: 99px; color: #fbbf24; font-size: 11px; padding: 1px 7px; }
+  .frame .label button { background: #18181b; border: 1px solid #26262b; border-radius: 6px; color: #a1a1aa; cursor: pointer; font: inherit; font-size: 11px; margin-left: auto; padding: 1px 7px; }
+  .frame .box { border-radius: 14px; overflow: hidden; }
+  .frame iframe { background: #fff; border: 0; display: block; }
+  </style></head><body>
+  <header><h1>Languages</h1>
+    <div class="seg" id="set"><button type="button" data-v="check" title="The source, the pseudo-languages and the ones check runs">Check languages</button><button type="button" data-v="all">All</button></div>
+    <div class="seg" id="zoom"><button type="button" data-v="0.4">40%</button><button type="button" data-v="0.6">60%</button><button type="button" data-v="1">100%</button></div>
+    <p>Pseudo: every text about 40% longer, and right to left. Copy a frame to reference it.</p></header>
+  <main></main>
+  <script>
+  const D = ${JSON.stringify(data).replaceAll('<', '\\u003c')}
+  const theme = localStorage.getItem('stitch2-theme')
+  let set = localStorage.getItem('stitch2-lang-set') ?? 'check'
+  let zoom = Number(localStorage.getItem('stitch2-lang-zoom') ?? 0.4)
+  const name = (l) => l === 'pseudo' ? 'Pseudo: long text' : l === 'pseudo-rtl' ? 'Pseudo: right to left' : (new Intl.DisplayNames([l], { type: 'language' }).of(l) ?? l) + (l === D.source ? ', source' : '')
+  async function copy(text) {
+    try { await navigator.clipboard.writeText(text) } catch { const t = document.createElement('textarea'); t.value = text; document.body.append(t); t.select(); document.execCommand('copy'); t.remove() }
+  }
+  function render() {
+    for (const b of document.querySelectorAll('#set button')) b.classList.toggle('on', b.dataset.v === set)
+    for (const b of document.querySelectorAll('#zoom button')) b.classList.toggle('on', Number(b.dataset.v) === zoom)
+    const langs = set === 'all' ? D.all : D.check
+    const main = document.querySelector('main')
+    main.innerHTML = ''
+    if (!D.screens.length) main.innerHTML = '<section><h2>No screens.</h2></section>'
+    for (const s of D.screens) {
+      const sec = document.createElement('section')
+      sec.innerHTML = '<h2></h2><div class="row"></div>'
+      sec.querySelector('h2').textContent = s.label
+      const code = document.createElement('code'); code.textContent = s.path; sec.querySelector('h2').append(code)
+      for (const l of langs) {
+        const f = document.createElement('div')
+        f.className = 'frame'
+        f.style.width = s.width * zoom + 'px'
+        f.innerHTML = '<div class="label"><b></b><span class="n"></span><span class="miss" hidden></span><button type="button">Copy</button></div><div class="box"><iframe loading="lazy" scrolling="no"></iframe></div>'
+        f.querySelector('b').textContent = l
+        f.querySelector('.n').textContent = name(l)
+        f.querySelector('button').onclick = () => copy(s.label + (l === D.source ? '' : ' in ' + l) + ' (' + s.path + ')')
+        const box = f.querySelector('.box')
+        const frame = f.querySelector('iframe')
+        frame.style.width = s.width + 'px'
+        frame.style.height = '844px'
+        frame.style.zoom = zoom
+        frame.src = '/' + s.path + (l === D.source ? '' : '?lang=' + encodeURIComponent(l))
+        const measure = () => {
+          try {
+            const doc = frame.contentDocument
+            frame.style.height = Math.max(doc.documentElement.scrollHeight, 400) + 'px'
+            const miss = frame.contentWindow.__stitch2?.missing ?? []
+            const m = f.querySelector('.miss')
+            m.hidden = !miss.length
+            m.textContent = miss.length + ' missing'
+            f.querySelector('.n').hidden = !!miss.length && zoom < 0.6
+            m.title = miss.map((x) => x.keys).join(', ')
+          } catch {}
+        }
+        frame.addEventListener('load', () => {
+          if (theme) try { frame.contentDocument.documentElement.dataset.theme = theme } catch {}
+          measure(); setTimeout(measure, 800); setTimeout(measure, 2500)
+        })
+        sec.querySelector('.row').append(f)
+      }
+      main.append(sec)
+    }
+  }
+  for (const b of document.querySelectorAll('#set button')) b.onclick = () => { set = b.dataset.v; localStorage.setItem('stitch2-lang-set', set); render() }
+  for (const b of document.querySelectorAll('#zoom button')) b.onclick = () => { zoom = Number(b.dataset.v); localStorage.setItem('stitch2-lang-zoom', String(zoom)); render() }
+  render()
+  </script></body></html>`;
+}

package/dist/pick.js

@@ -9,7 +9,7 @@
 /** Tags that are never picked by themselves: their nearest picked ancestor stands for them. */
 const SKIP = new Set(['body', 'br', 'i', 'script', 'style', 'template', 'path', 'line', 'polyline', 'polygon', 'circle', 'ellipse', 'rect', 'g', 'defs', 'stop', 'use', 'text', 'tspan']);
 /** Runs in the screen before its own scripts: components that replace themselves pass their line on. */
-const SHIM = `<script>(()=>{const d=customElements.define.bind(customElements);customElements.define=(name,cls,opts)=>{const p=cls.prototype,cb=p.connectedCallback;if(cb)p.connectedCallback=function(...a){const line=this.getAttribute('data-s2-line'),parent=this.parentNode,before=this.previousSibling,after=this.nextSibling;const r=cb.apply(this,a);if(line){if(this.isConnected)this.setAttribute('data-s2-tag',name);else if(parent)for(let n=before?before.nextSibling:parent.firstChild;n&&n!==after;n=n.nextSibling)if(n.nodeType===1&&!n.hasAttribute('data-s2-line')){n.setAttribute('data-s2-line',line);n.setAttribute('data-s2-tag',name)}}return r};return d(name,cls,opts)}})()</script>`;
+const SHIM = `<script>(()=>{const d=customElements.define.bind(customElements);customElements.define=(name,cls,opts)=>{const p=cls.prototype,cb=p.connectedCallback;if(cb)p.connectedCallback=function(...a){const line=this.getAttribute('data-s2-line'),parent=this.parentNode,before=this.previousSibling,after=this.nextSibling;const r=cb.apply(this,a);if(line){const key=this.getAttribute('data-s2-key');if(this.isConnected)this.setAttribute('data-s2-tag',name);else if(parent)for(let n=before?before.nextSibling:parent.firstChild;n&&n!==after;n=n.nextSibling)if(n.nodeType===1&&!n.hasAttribute('data-s2-line')){n.setAttribute('data-s2-line',line);n.setAttribute('data-s2-tag',name);if(key)n.setAttribute('data-s2-key',key)}}return r};return d(name,cls,opts)}})()</script>`;
 /** The page with source lines on its body's elements and the shim at the start of its head. */
 export function annotate(html) {
     const bodyAt = html.search(/<body[\s>]/i);

package/dist/serve.js

@@ -1,5 +1,5 @@
 /**
- * The stitch2 server: the canvas at /, DESIGN.md drawn at /design, the screen list at /api/screens
+ * The stitch2 server: the canvas at /, DESIGN.md drawn at /design, screens side by side per language at /languages, the screen list at /api/screens
  * (POST /api/screens/meta sets a version's status or note), check results at /api/checks, live-reload events
  * at /events, and every file under design/ by its path. Local only (127.0.0.1).
  * Usage: stitch2 canvas   (PORT=4400 by default)
@@ -10,7 +10,9 @@ import { dirname, extname, join, normalize } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CONFIG_FILE, config } from './config.js';
 import { designThemes } from './design-md.js';
+import { allLocales, localeScript, sourceLocale } from './i18n.js';
 import { designPage } from './design-page.js';
+import { languagesPage } from './languages-page.js';
 import { annotate } from './pick.js';
 /**
  * Inlines <link rel="stylesheet" type="text/tailwindcss" href="…">: the Tailwind v4 browser build reads @theme and
@@ -71,6 +73,10 @@ export function startServer(port) {
             res.writeHead(200, { 'content-type': TYPES['.html'], 'cache-control': 'no-store' });
             return res.end(designPage());
         }
+        if (url.pathname === '/languages') {
+            res.writeHead(200, { 'content-type': TYPES['.html'], 'cache-control': 'no-store' });
+            return res.end(languagesPage(url.searchParams.get('screen') ?? undefined));
+        }
         if (url.pathname === '/compare/index.html' && !existsSync(join(ROOT, 'compare/index.html'))) {
             res.writeHead(200, { 'content-type': TYPES['.html'], 'cache-control': 'no-store' });
             return res.end('<body style="background:#0f0f11;color:#a1a1aa;font:15px system-ui;padding:32px">No comparison yet: run <code>stitch2 compare</code> with the app running.</body>');
@@ -115,7 +121,7 @@ export function startServer(port) {
             return;
         }
         if (url.pathname === '/api/config')
-            return json({ ...config, themes: designThemes() });
+            return json({ ...config, themes: designThemes(), locales: allLocales(), sourceLocale: sourceLocale() });
         if (url.pathname === '/api/screens')
             return json(listScreens());
         if (url.pathname === '/api/checks') {
@@ -145,7 +151,13 @@ export function startServer(port) {
         // The canvas loads screens with ?pick: their elements carry source lines for picking.
         if (extname(file) === '.html') {
             const html = inlineTailwind(readFileSync(file, 'utf8'), file);
-            res.end(url.searchParams.has('pick') ? annotate(html) : html);
+            const page = url.searchParams.has('pick') ? annotate(html) : html;
+            const lang = url.searchParams.get('lang');
+            if (!lang || lang === sourceLocale())
+                return res.end(page);
+            // After the lines are numbered: the locale's script may span several lines.
+            void localeScript(lang).then((script) => res.end(page.replace(/<head(\s[^>]*)?>/i, (h) => h + script)), (e) => res.end(page.replace(/<body([^>]*)>/i, (b) => b + '<pre style="color:#e5484d">stitch2: ' + String(e) + '</pre>')));
+            return;
         }
         else
             res.end(readFileSync(file));

package/dist/typecheck.d.ts

@@ -11,6 +11,8 @@ export interface Issue {
     text: string;
     /** Set when the issue depends on the theme (contrast): the data-theme it was found in. */
     theme?: string;
+    /** Set when the issue shows only in another language: the locale it was found in. */
+    locale?: string;
 }
 export interface TextItem {
     selector: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitch2",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "A design canvas, layout and type checks, component consistency and screen versioning for agent-built UI, on Google's DESIGN.md format.",
   "license": "MIT",
   "author": "ifokeev",

package/skills/stitch2/SKILL.md

@@ -42,7 +42,8 @@ References, read before the first screen:
 4. **Build** the next version, `<screens>/<screen>/<device>-v<N>.html`, from the project's template (status
    `draft`; never edit an approved version). Assemble it from the components; plain markup only where none
    applies, with token classes, `.type-<level>` classes for text, the spacing scale, and the states DESIGN.md
-   defines. Never add classes to a component to change how it looks, and never write a colour value (hex,
+   defines. When the config has `i18n`, mark every product string with its message key (`data-t`, see
+   **stitch2-i18n**). Never add classes to a component to change how it looks, and never write a colour value (hex,
    `rgb()`, `hsl()`): only DESIGN.md's colours, as token classes or `var(--<prefix>-<name>)`.
 5. **Check** `stitch2 check <path> --shots --strict`. Fix every error (overflow, wrapped labels, content under
    fixed bars, fixed bars overlapping each other, tap targets, contrast, cramped text) and every warning about type (`type-*`), hand-built
@@ -51,7 +52,9 @@ References, read before the first screen:
    short with an ellipsis (`truncated`) is a warning to fix with room, not a smaller size. When DESIGN.md has a
    light and a dark theme, every screen is checked in both: an issue marked with a theme
    ("light theme: Low contrast…") is fixed in DESIGN.md's colours for that theme when it shows on many
-   screens, or in the screen when it is one element. Look at both renders (`--light.png`).
+   screens, or in the screen when it is one element. Look at both renders (`--light.png`). With `i18n`, check
+   also runs the screen in the pseudo-languages and the config's locales; fix what they flag as the
+   **stitch2-i18n** skill says.
 6. **Look and critique.** View the render in `<design>/renders/` (crop the first screenful). Score it with the
    rubric in principles.md, fix what fails, repeat 5–6 at most three times.
 7. **Hand over.** Set the version's status to `review`, point the user to it on the canvas, and report what
@@ -65,7 +68,8 @@ References, read before the first screen:
 |---|---|
 | `setup [--name N --primary #hex] [options]` | Sets a project up in one step; keeps every file that exists |
 | `canvas` | The canvas at http://localhost:4400: screens and versions, DESIGN.md, the consistency report, approval and notes |
-| `check [filter] [--shots] [--strict]` | Layout, type, reuse and consistency checks; `--shots` saves renders |
+| `check [filter] [--shots] [--strict] [--locales l,…]` | Layout, type, reuse and consistency checks, in every theme and check language; `--shots` saves renders |
+| `i18n [filter] [--locale l] [--suggest]` | Message keys screens use that the source or a locale lacks, and text with no key (stitch2-i18n) |
 | `consistency [kind…]` | Every shared component cropped from every screen, next to the catalog's version |
 | `type [filter] [--json]` | Every text style a screen uses and the type level it matches |
 | `screens [name] [--status s] [--json]` | Every version with its status and the user's note |

package/skills/stitch2-i18n/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: stitch2-i18n
+description: Design screens that work in every language the product ships — text marked with the project's message keys, checked in pseudo-languages, right to left and the real locales, side by side on the canvas. Use when a project has i18n in stitch2.config.json, when writing or changing screen text, when the user mentions languages, translations, RTL or a label that breaks in one language, or before handing over screens of a multilingual product.
+---
+
+# Screens in every language with stitch2
+
+A screen is written once, in the source language, and every product string in it carries a **message key** from
+the project's own translation files. stitch2 replaces the text from those files when the screen is opened in
+another language, so one HTML file shows every locale, and the screen and the app share the same strings.
+The checks then run each screen in the languages that break layouts: **pseudo** (every text about 40% longer,
+accented, in brackets, so a cut end shows), **pseudo-rtl** (right to left) and the locales in the config.
+
+## Setup
+
+`stitch2.config.json` names the messages; paths are relative to it:
+
+```json
+"i18n": {
+  "source": "en",
+  "locales": ["en", "de", "ru", "ar"],
+  "messages": { "en": "src/i18n/en.ts", "*": "src/i18n/locales/{locale}.ts" },
+  "check": ["de", "ar"]
+}
+```
+
+`messages` is one pattern (`"src/i18n/{locale}.json"`) or a map with `*` for the rest. JSON, or a JS/TS module:
+its default export, else its first exported object. Nested objects become dotted keys (`nav.home`). Plurals
+are objects keyed by CLDR category: `{ "one": "{count} set", "other": "{count} sets" }`. `check` lists the
+locales `stitch2 check` runs besides the two pseudo-languages; pick the longest (German, Finnish, Russian) and
+one right-to-left language, or `"all"`.
+
+Use the app's own files. Never copy messages into the design folder: two copies drift.
+
+## Marking text
+
+```html
+<span data-t="nav.home">Home</span>                              <!-- the element's text -->
+<s2-header title="Settings" data-t-title="settings.title">       <!-- an attribute, before the component renders -->
+<input placeholder="Search" data-t-placeholder="exercises.search" />
+<p data-t="workout.sets" data-t-args="count=16">16 sets</p>     <!-- {count} filled in, plural form by count -->
+<p translate="no">Dumbbell Bench Press</p>                      <!-- sample content: names, user input, numbers -->
+<s2-row meta="5 exercises · Linear" data-t-meta="{plan.exercises|count=5} · {plan.linear}">
+```
+
+A value with braces is a **template**: each `{key}` or `{key|name=value;name=value}` becomes its message and
+the rest stays as written. Use it for lines the app builds from several messages and data (a meta line, a
+list of `label=url` links: `data-t-links="{site.features}=#features,{site.docs}=/docs"`); sample data inside
+it stays literal. Without braces, `data-t-<attr>` on a comma list takes one key per item.
+
+Dates and numbers are written by the locale too: `{@date|value=2026-10-04;weekday=short;day=numeric;month=short}`
+("Sun, 4 Oct", "вс, 4 окт.") and `{@number|value=7920}` ("7,920", "7 920"); the options are `Intl.DateTimeFormat`'s and
+`Intl.NumberFormat`'s, and dates are read and shown in UTC. Pair a number with the unit's message:
+`{@number|value=82.5} {unit.kg}`.
+
+- Keep the source text in the markup: the screen reads correctly without stitch2, and a missing key shows it.
+- Key every string the product owns: labels, buttons, headings, empty states, hints, units, tab names, the
+  placeholder and aria-label too. Sample data (an exercise name, a user's note, a number) gets `translate="no"`.
+- `data-t` replaces the element's whole text, so put it on the innermost element holding just that string;
+  an icon next to the label stays outside it.
+- Components that draw their own labels (a tab bar's tab names) take them from `translate(key, fallback)` in
+  `stitch2/elements` (or `window.__stitch2.t(key)` in plain JS), so the labels follow the language.
+- Reuse the app's keys. Search the source messages for the text before inventing one (`stitch2 i18n --suggest`
+  lists matches). A new string gets a key in the app's naming scheme, added to the **source** messages first and
+  then to every locale; when you cannot write a good translation, add it to the source only and say so: the
+  locale falls back to the source and the report lists it.
+
+## Check
+
+1. `stitch2 i18n [filter] --suggest`: per screen, keys the source lacks (errors: they show the screen's own text
+   everywhere), keys each locale lacks, translations whose `{placeholders}` differ from the source, and text
+   with no key. Fix until it reports no unknown keys and no unkeyed product text.
+2. `stitch2 check <path> --shots`: runs the screen in the source, then in each check language. Issues that only
+   appear in a language carry it ("pseudo: Text overflows…", "ar: …"); renders are saved as
+   `--pseudo.png`, `--ar.png`. `--locales de,ar`, `all` or `none` overrides the config for one run.
+3. Look at the screen side by side: the canvas's **Languages** page (sidebar, or "languages" in a screen's
+   inspector) shows it once per language at the same size; the Language switch (`L`) shows the whole canvas in
+   one language. Read the pseudo frames for cut or overlapping text and the right-to-left ones for anything
+   that did not flip.
+
+## Fixing text that does not fit
+
+In this order, and never by shrinking the type below its level:
+
+1. **Make room in the layout.** Let the text wrap where a second line is fine (headings, hints, cards); let a
+   row stack its label above its value; give a button the full width; move a secondary action out of a crowded
+   bar. Fixed widths and `whitespace-nowrap` on text are the usual cause.
+2. **Use a shorter natural word** in that locale, the one a native speaker would use (a translator's choice,
+   not an abbreviation the product does not use elsewhere). Change it in the locale's messages, which the app
+   shares.
+3. **Change the component** when one component fails in many languages (a tab label, a chip): fix it once in
+   the component and the catalog, then re-check every screen.
+
+Ellipsis is acceptable only for user content (a long exercise name), never for a label the product owns.
+
+## Right to left
+
+Use logical properties so layouts flip by themselves: `ms-*`/`me-*`, `ps-*`/`pe-*`, `start-*`/`end-*`,
+`text-start`, `rounded-s-*`. Icons that point (back, next, chevrons, progress) get `rtl:-scale-x-100`;
+icons that show objects (a dumbbell, a clock) and numbers, charts and media controls do not flip.
+
+## Hand over
+
+Tell the user which languages you checked, what you changed to make each fit (layout, word, component), and
+which locales still fall back to the source for new keys, by key.