I18n And Translation

Position

Prox OS is English-first for v0.1, not English-only forever.

The earlier three-layer multilingual model remains a future direction, but the current product posture pauses exposed language switching and translation UI so the first public preview and invite-only beta can reduce legal, support, QA, copywriting, and go-to-market complexity.

Native i18n infrastructure may remain in code when it is already part of the Shell implementation, but user-visible language switching should not be promoted as a v0.1 capability.

English-first v0.1

Rule	Meaning
Product UI	New shell and app copy should be English unless it belongs in formal locale bundles.
Docs	Repository docs stay English for AI and human readability.
User promise	Do not advertise full multilingual support during v0.1.
Existing infrastructure	Keep safe i18n plumbing when removing it would create unnecessary risk.
Future posture	Reintroduce multi-language UI after product-market signal, privacy/legal copy, payment copy, and support workflows stabilize.

Why I18n Is Paused

Privacy, legal, payment, support, and agent-permission copy must stabilize before every string is multiplied across locales.
Public preview and invite-only beta need tight feedback loops in one product language.
AI-readable docs and agent instructions should remain one canonical language.
Multi-language rollout should not imply regional legal, support, or payment readiness before those operations exist.

When I18n Returns

Requirement	Why it must be stable first
Privacy and Terms copy	Translated legal-adjacent copy must not drift from the source of truth.
Payment and marketplace posture	Pricing, refunds, tax, payouts, and builder incentives need exact language.
Permission and agent-action copy	Users must understand scopes, confirmation, audit, revocation, and risk.
Support workflow	Multi-language UI implies support expectations.
Regional rollout strategy	Locale support should match actual operational readiness.

Layer 1: OS Shell Native I18n

Future OS Shell native i18n should own stable strings for chrome, windows, menus, settings, command palette UI, permissions, and other shell-owned surfaces.

Current files:

apps/os-shell/src/i18n/resources.ts
apps/os-shell/src/i18n/languages/en.ts
apps/os-shell/src/i18n/languages/zhCN.ts
apps/os-shell/src/i18n/languages/es.ts
apps/os-shell/src/i18n/glossary.ts

This infrastructure is not a v0.1 product promise. Shell-level language preferences and language switchers should stay hidden or paused until the English source-of-truth copy is stable enough to localize.

Do not scatter if (language === ...) checks through components. Add stable keys to the shell dictionaries, route copy through useI18n(), and keep localized strings inside apps/os-shell/src/i18n/**. App copy that has not adopted i18n should remain English until the app owns native messages.

Layer 2: App-Level Declared I18n Support

Apps should eventually declare language support in the app manifest or app contract metadata:

type AppI18nSupport = {
  defaultLocale: 'en' | 'zh-CN' | 'es'
  supportedLocales: Array<'en' | 'zh-CN' | 'es'>
  translationMode: 'native' | 'ai_overlay' | 'unsupported' | 'mixed'
  glossaryNamespace?: string
}

For future work, the shell may use a lightweight adapter at apps/os-shell/src/shell/command/appI18nMetadata.ts before changing the manifest contract. During the English-first v0.1 phase, Cmd+K and titlebars should avoid promising app translation support as a current product feature.

Layer 3: AI Translation Overlay

AI translation is a fallback, not a replacement for native i18n. It may later support:

Translate current window.
Translate selected text.
Explain this app in my language.
Keep technical terms unchanged.
Use the Prox OS glossary.
Respect app bridge and iframe boundaries.

Runtime boundaries matter:

Local module apps can expose text and context through shell-owned contracts.
Same-origin iframe apps can cooperate through a future postMessage bridge.
Cross-origin iframe apps should not have their DOM read by the shell. They need an app translation bridge, browser capability, or explicit user grant.

Current Milestone Boundary

Paused for v0.1:

exposed RuntimeCommandStrip language switcher;
Settings and Display Options language picker;
titlebar translation menu;
Cmd+K language-support badges as a primary app capability.

Still allowed:

English shell copy through existing i18n dictionaries where removing the provider would be risky;
formal locale files under apps/os-shell/src/i18n/** as future-ready infrastructure;
docs that describe future localization and AI translation as roadmap, not current shipped capability.

Not implemented now:

real AI translation API calls;
AI Sidebar execution;
iframe text extraction;
app manifest contract migration;
real titlebar translation execution;
backend translation memory or glossary storage.

Future translation work should connect through app contracts, permissions, Activity/Audit Log, and a scoped AI action registry.

Future Studio Locale

A later Studio manifest may declare preferred locale, fallback locale, and resource-specific translation posture. That should not replace shell-level language. It should let a shared Studio, app, or dataset explain whether it is native, translated, or AI-assisted in the current user's language.

I18n And Translation

On this page