Localization (i18n)
Relevant source files
The following files were used as context for generating this wiki page:
Localization (i18n) in OpenWork is designed to make the platform accessible to a global audience by providing multi-language support across the desktop application's user interface, project documentation, and core agentic workflows. The project adopts a dual-track approach to localization: one focused on the static documentation (READMEs) and another on the dynamic App UI components.
The system supports a variety of languages including English, French, Spanish, Japanese, Simplified Chinese, and more. This is achieved through a combination of locale files, translation-ready components, and localized agent templates.
Sources: README.md:214-230, TRANSLATIONS.md:1-20
Architecture and Components
The localization architecture is split into two primary domains: documentation translation and application UI internationalization.
Documentation Translation
README translations are maintained as distinct files within the translated_readmes/ directory. Adding a new language involves creating a variant of the root README.md and updating index files to link the new content.
App UI Internationalization
The App UI uses an i18n module located in apps/app/src/i18n/. Translation keys are mapped to specific locale files within apps/app/src/i18n/locales/. A global t() function is used to resolve these keys into localized strings within the React application.
Sources: TRANSLATIONS.md:7-18, apps/app/src/app/utils/index.ts:3-3
Localization Logic Flow
The following diagram illustrates how the application resolves localized content:
This diagram shows the flow from a UI component calling the translation function to the resolution of a string from the locale-specific JSON files.
Sources: TRANSLATIONS.md:14-20, apps/app/src/app/utils/index.ts:3-3
Supported Languages and Locales
The project explicitly supports several languages across different parts of the ecosystem.
UI Locales
The application UI supports the following ISO codes:
| Language | Code |
|---|---|
| English | en |
| French | fr |
| Spanish | es |
| Catalan | ca |
| Brazilian Portuguese | pt-BR |
| Japanese | ja |
| Simplified Chinese | zh |
| Thai | th |
| Vietnamese | vi |
| Russian | ru |
Sources: README.md:218-227, TRANSLATIONS.md:16-18
Documentation Languages
The translated_readmes/ directory contains localized variants of the project documentation. Currently available translations include English, Simplified Chinese, Traditional Chinese, and Japanese.
Sources: README.md:214-216, translated_readmes/README.md:1-3
Technical Implementation Details
Translation Utilities
The system utilizes a central utility for string formatting and relative time calculations. The formatRelativeTime function, for example, relies on the t() function to provide localized time strings such as "just now", "seconds ago", or "minutes ago".
export function formatRelativeTime(timestampMs: number) {
const delta = Date.now() - timestampMs;
if (delta < 0) {
return t("time.just_now");
}
if (delta < 60_000) {
return t("time.seconds_ago", { count: Math.max(1, Math.round(delta / 1000)) });
}
// ...
}
Sources: apps/app/src/app/utils/index.ts:285-305
Localized Agent Guidance
OpenWork agents are initialized with localized guidance. The OPENWORK_ARTIFACT_GUIDANCE and OPENWORK_AGENT templates are injected into workspace files (like .opencode/agents/openwork.md) during workspace initialization. This ensures that the agent's "Working style" and understanding of "Artifacts" are consistent with the localized environment.
Sources: apps/server/src/workspace-init.ts:15-84
Verification and Testing
Localization is verified through end-to-end "evals." Specifically, the onboarding and welcome flows are checked to ensure that folder explanation i18n keys are correctly translated and that there are no missing keys during first-run experiences.
Sources: evals/onboarding-welcome-flows.md:104-106, evals/onboarding-welcome-flows.md:124-124
Contributing to Translations
The project encourages community contributions for localization.
- READMEs: Contributors can copy
README.mdtotranslated_readmes/README_<LANG>.mdand submit a PR after updating the indices. - App UI: Contributions are handled via the
apps/app/src/i18n/locales/directory.
Sources: TRANSLATIONS.md:1-20
Summary
Localization in OpenWork is a comprehensive system spanning documentation, UI strings, and agent behavior. By separating documentation from UI locales and using a centralized i18n module, the project maintains a scalable approach to supporting a global user base. Verification through automated flows ensures that localized strings are consistently rendered and that no translation keys are missing in critical user paths.