mirror of
https://github.com/stablyai/orca.git
synced 2026-09-22 16:02:32 +00:00
Neil
968dbd905f
* perf(renderer): take the English catalog, xterm WebGL addon and emoji data off the boot graph The renderer's boot graph — the entry chunk plus its 331 modulepreload links, all fetched and evaluated before first paint — carried three payloads nothing needs at that moment. `en.json` (644 KB) was an eager i18next resource, but every renderer string goes through `translate(key, fallback)` and `en` resolves that inline default, so most of the catalog was dead weight. The renderer now bundles a generated `en-runtime-required.json` holding only the 2,583 of 13,828 entries a default cannot reproduce: plural-suffixed keys, keys whose catalog value differs from a call site's default, and keys no call site references with a literal default. `en.json` stays the translator source and the input to the four lazy catalogs. `@xterm/addon-webgl` (243.6 KB) and `emojibase-data` (170 KB) are now primed right after the React root renders instead of statically imported. The load stays eager and `attachWebgl` stays synchronous — it reads the resolved constructor — so no terminal ever falls back to the DOM renderer for a frame. `isPluginPanelTabKey`/`isQualifiedPluginKey` move to schema-free sibling modules, re-exported from `plugin-manifest.ts`. This evicts the plugin manifest schema graph from the boot chunk but measures ~0 KB, because six other shared modules still put zod on the boot path. Boot graph: 332 chunks / 5107.2 KB -> 336 chunks / 4161.5 KB (-945.7 KB, -18.5%). A new ratchet parses the built index.html and fails if `en.json`, `@xterm/addon-webgl` or `emojibase-data` is preloaded again; it runs at the end of every `build:electron-vite`. * chore(i18n): pin the generated English subset to LF and mark it generated * fix(i18n): make the runtime-catalog gate merge-robust and prime emoji data in tests CI builds the merge of a PR with main, so a byte-for-byte comparison against a committed generated file fails the moment any unrelated PR adds a translate() call — which is what happened here. The check now asserts the property that actually matters instead of byte equality: every runtime-required entry is shipped, and nothing shipped disagrees with en.json. Entries that stopped being required are dead weight, never a wrong string, so they are reported and tolerated. Failures now name the offending keys rather than saying "stale". The generator itself was already deterministic (plain code-unit sort, no locale collation, order-independent set construction); a test now pins that a reversed call-site walk produces byte-identical output. Test fixes for the catalog prune and the deferred emoji load: - browser-search / NativeChatSupportedAgents asserted key presence on the renderer's runtime resource. The durable contract is en.json — the renderer deliberately no longer bundles entries a call site default reproduces — so they assert against the translator catalog. - Four emoji tests typed a shortcode in the same tick as mount, before the catalog the hook primes on mount resolves. Not reachable by a human; the tests now await the prime. * revert(renderer): keep the emoji shortcode catalog statically imported Deferring emojibase-data introduced a window that did not exist before: until the dynamic import settled, getPrimedEmojiShortcodeEntries returned [], so exactShortcodeIndex built an empty map and replaceCompletedWorkspaceEmojiShortcode returned null — leaving a typed `:wink:` in the field literally, and persisting it as the workspace display name. Pre-change the shared catalog was statically imported, so the first call at any tick returned full data. The window is reachable by anything that dispatches input in the same task as the field's mount effect — Playwright/CDP in the e2e suite and agent automation both do, and the WorktreeMetaDialog test failure was exactly that, producing 'Feature 😉' instead of 'Feature 😉'. Nothing that resolves a shortcode can be async without that race, and a wrong persisted name is not an acceptable trade for 166.7 KB, so the deferral is reverted rather than papered over in the tests. The boot-graph ratchet drops its emojibase-data probe and records why. Boot graph: 5108.9 KB -> 4329.9 KB (-779.0 KB, -15.2%), down from -945.7 KB. * fix(terminal): make the deferred WebGL addon load recoverable and refit on late attach Two defects the deferral introduced, neither possible with a static import. A failed load latched the DOM renderer for the whole session. `.then(onOk, onError)` settles fulfilled, so the memoized promise was cached forever with a null constructor: attachWebgl's re-prime got the cached promise back, and resetTerminalWebglSuggestion — the documented "GPU setting changed, retry" path — could not clear it either. The rejection path now clears the memo, latches the queued panes the way a failed construction does so they retry at a recovery boundary rather than every frame, and caps attempts so a genuinely missing chunk is not re-fetched forever. The recovery boundary re-arms it. The queued-attach drain skipped the refit. Every other late-attach path pairs attach with a refit because the grid was measured under DOM cell metrics and WebGL floors the device cell width. Post-deferral, openTerminal's attachWebgl queued and returned, the initial fit rAF then measured DOM metrics and sized the PTY from them, and the addon attached with no refit — a persistently narrow PTY and an unpainted right gutter, not a one-frame flicker. Both paths now go through one attachWebglAndRefit pairing so they cannot diverge again. Regression tests cover both, and each was verified to fail without its fix. The addon-load state machine moves to terminal-webgl-addon-loader.ts and the viewport presentation helpers to pane-viewport-present.ts, keeping pane-webgl-renderer.ts under the 300-line budget without a suppression.
144 lines
5.7 KiB
Markdown
144 lines
5.7 KiB
Markdown
# Localization Audit
|
|
|
|
This is the pre-work artifact for migrating Orca to a localized UI. The goal is
|
|
to make coverage repeatable: every detected user-facing string is either moved
|
|
behind the localization layer or explicitly excluded with a reason.
|
|
|
|
The accepted translation-source architecture and staged migration are recorded
|
|
in [`i18n-translation-source.md`](./i18n-translation-source.md).
|
|
|
|
## Coverage Contract
|
|
|
|
Coverage means all strings matching the audit scope below are accounted for:
|
|
|
|
- JSX text rendered in the renderer.
|
|
- Accessibility and form attributes such as `aria-label`, `ariaLabel`, `alt`,
|
|
`placeholder`, `title`, `label`, `description`, `subtitle`, and `tooltip`.
|
|
- User-facing object metadata such as Settings search `title`, `description`,
|
|
`keywords`, labels, badges, helper text, and tooltips.
|
|
- User-facing calls such as `toast.success(...)`, `toast.error(...)`, browser
|
|
`alert(...)`, `confirm(...)`, and `prompt(...)`.
|
|
|
|
The audit intentionally does not treat these as localization misses unless they
|
|
are surfaced directly as UI copy:
|
|
|
|
- Terminal output, agent output, git output, provider API errors, and shell
|
|
commands.
|
|
- File paths, URLs, environment variables, telemetry event names, IDs, and
|
|
protocol names.
|
|
- Developer logs, internal diagnostics, test fixtures, and snapshots.
|
|
- Brand, provider, model, command, and product names that should remain exact.
|
|
|
|
## Inventory Command
|
|
|
|
Generate a machine-readable inventory:
|
|
|
|
```sh
|
|
node config/scripts/audit-localization-coverage.mjs --json --output tmp/localization-candidates.json
|
|
```
|
|
|
|
Generate a reviewable Markdown inventory:
|
|
|
|
```sh
|
|
node config/scripts/audit-localization-coverage.mjs --markdown --output tmp/localization-candidates.md
|
|
```
|
|
|
|
Run the maintained coverage gate:
|
|
|
|
```sh
|
|
pnpm run verify:localization-coverage
|
|
```
|
|
|
|
Sync catalog keys after adding or removing `translate(...)` calls:
|
|
|
|
```sh
|
|
pnpm run sync:localization-catalog
|
|
```
|
|
|
|
The sync command adds missing `en.json` entries from each call's string fallback.
|
|
It never edits target catalogs: missing values remain absent and use the existing
|
|
runtime English fallback. Existing placeholder mismatches fail validation until
|
|
a localization PR fixes or retires the target entry.
|
|
|
|
Regenerate the runtime-required English subset after changing `en.json` or an
|
|
inline default:
|
|
|
|
```sh
|
|
pnpm run sync:localization-runtime-catalog
|
|
```
|
|
|
|
`src/renderer/src/i18n/en-runtime-required.json` is the only English catalog the
|
|
renderer bundles. Because `translate(key, fallback)` always supplies a default
|
|
and `en` resolves that default when the key is absent, it holds just the entries
|
|
a default cannot reproduce: plural-suffixed keys, keys whose value differs from
|
|
the inline default, and keys no call site references with a literal default
|
|
(dynamic keys and dynamic defaults). `en.json` remains the translator source and
|
|
the input to the four lazy target catalogs.
|
|
`pnpm run verify:localization-runtime-catalog` fails when the subset is stale.
|
|
|
|
Run maintained source extraction without committing a second English catalog:
|
|
|
|
```sh
|
|
pnpm run verify:localization-extraction
|
|
```
|
|
|
|
Extraction fails when a statically extracted key is absent from `en.json` or an
|
|
inline default has incompatible placeholders. Existing unreferenced English keys
|
|
and wording-only fallback drift are reported as migration debt; the permanent
|
|
bilingual translation source will reconcile them without a large disposition
|
|
database. Reviewed and stale translation state is likewise deferred to that
|
|
source rather than inferred permanently from Git history.
|
|
|
|
The legacy free-endpoint bootstrap and whole-catalog repair scripts intentionally
|
|
have no package-script entry points. Ordinary product and localization work must
|
|
not invoke tools that can overwrite an entire target catalog.
|
|
|
|
The coverage gate compares current candidates against
|
|
`config/localization-coverage-allowlist.json`. The committed allowlist is
|
|
small (10 reviewed entries — one test fixture title, five non-English
|
|
language-name search keywords, and four reviewed product-name search
|
|
keywords): new candidates fail the check and must be localized or added with
|
|
a reviewed reason in the same change.
|
|
|
|
The script scans `src/renderer/src` by default. That is the primary UI surface.
|
|
Use `--source-root src` for a wider audit when checking renderer-adjacent shared
|
|
copy, then classify non-renderer findings carefully because many are diagnostics
|
|
or external tool text.
|
|
|
|
## Migration States
|
|
|
|
Each candidate should end in one of these states:
|
|
|
|
- `localized`: the component reads the string from the locale catalog.
|
|
- `excluded`: the string is intentionally not localized, with a reason from the
|
|
coverage contract.
|
|
- `deferred`: the string is user-facing but belongs to a later PR wave.
|
|
|
|
`deferred` is acceptable for planning, but not for the localization coverage
|
|
gate.
|
|
|
|
## PR Waves
|
|
|
|
Recommended migration order:
|
|
|
|
1. Infrastructure, English catalog, language setting, and language selector.
|
|
2. Settings shell, Settings search metadata, and Appearance.
|
|
3. App shell, sidebars, titlebar, status bar, command surfaces, and global
|
|
dialogs/toasts.
|
|
4. Task pages, source control, hosted review, and provider-specific UI.
|
|
5. Terminal chrome, onboarding, feature tips, mobile, browser, and remaining
|
|
secondary surfaces.
|
|
|
|
## Proof Strategy
|
|
|
|
The final gate should combine three checks:
|
|
|
|
1. Scanner coverage: no unclassified localizable candidates remain.
|
|
2. Catalog correctness: existing translations have matching interpolation
|
|
variables; missing target entries are reported rather than rejected.
|
|
3. Runtime coverage: pseudo-localization and real locale smoke tests show no
|
|
obvious English leftovers or layout clipping in core screens.
|
|
|
|
Subagent or human review should verify ambiguous exclusions, but the scanner is
|
|
the coverage source of truth.
|