Internationalization (i18n)
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The internationalization (i18n) system in Opcode is designed to provide a multi-lingual user interface, allowing the application to be accessible to a global developer audience. It utilizes i18next as the core engine to manage translations, language detection, and interpolation within React components.
The system supports a wide range of languages, including right-to-left (RTL) scripts like Arabic and character-based scripts like Korean and Chinese. It integrates directly with the application settings, enabling users to persist their preferred language across sessions using local storage.
Sources: src/i18n/index.ts:1-73, src/i18n/locales/en.json:67-68
Architecture and Configuration
The i18n implementation is centralized in the src/i18n directory. It uses a modular approach where translation strings are stored in JSON locale files and imported into a central configuration hub.
Core Engine and Plugins
The system initializes i18next with two primary plugins:
- LanguageDetector: Automatically detects the user's language based on
localStorage(keyed asapp_language) or the browser'snavigatorsettings. - initReactI18next: Provides the necessary bindings for React, allowing the use of the
useTranslationhook.
Sources: src/i18n/index.ts:46-73
Language Initialization Flow
The following diagram illustrates how the i18n system determines and loads the active language during application startup.
The system prioritizes local storage to ensure user preferences are maintained, falling back to English (en) if no detection succeeds.
Sources: src/i18n/index.ts:60-70
Translation Management
Translations are managed through structured JSON files. Each file contains nested objects categorized by UI modules such as nav, agents, settings, and mcp.
Supported Languages
Opcode explicitly supports 12 languages as defined in the supportedLanguages constant:
| Language | Code | Native Name |
|---|---|---|
| English | en | English |
| Chinese (Simplified) | zh | 简体中文 |
| Chinese (Traditional) | zh-TW | 繁體中文 |
| Japanese | ja | 日本語 |
| Korean | ko | 한국어 |
| German | de | Deutsch |
| French | fr | Français |
| Spanish | es | Español |
| Portuguese | pt | Português |
| Russian | ru | Русский |
| Arabic | ar | العربية |
| Vietnamese | vi | Tiếng Việt |
Sources: src/i18n/index.ts:31-44
Resource Mapping
The resources object maps language codes to their respective translation files, ensuring that the translation namespace is consistently populated for the i18next engine.
export const resources = {
en: { translation: en },
zh: { translation: zh },
// ... other mappings
ar: { translation: ar },
vi: { translation: vi },
} as const;
Sources: src/i18n/index.ts:16-29
Implementation in UI Components
React components consume the i18n system using the useTranslation hook. This provides a t function used to retrieve specific keys and an i18n instance for dynamic language switching.
Key Usage Patterns
- Static Keys: Simple retrieval of text, e.g.,
t('common.save'). - Dynamic Interpolation: Passing variables into translation strings, such as
t('agents.page', { current, total }). - Component Logic: Checking status strings or messages, as seen in
MCPImportExport.tsxwhere success messages returned from the API are handled via translation hooks.
Sources: src/components/ProjectSettings.tsx:41, src/components/MCPImportExport.tsx:41, src/i18n/locales/en.json:44
Data Flow in Component Translation
The following sequence shows how a component like ProjectSettings interacts with the translation layer.
Locale Structure Details
The locale files follow a specific schema to organize the extensive feature set of Opcode.
| Section | Description | Key Examples |
|---|---|---|
app | Global app metadata | name, welcome |
nav | Sidebar and navigation labels | usageDashboard, mcpServers |
agents | Agent creation and management | createAgentDesc, systemPrompt |
settings | User preference configurations | themeDesc, analytics |
mcp | Model Context Protocol configuration | addStdioServer, importFromDesktop |
storage | Database browser and SQL editor labels | sqlQuery, resetDatabase |
Sources: src/i18n/locales/en.json:1-600
Multi-language Feature Support
The i18n system handles complex UI states across different languages. For example, the usage section provides specific formatting for costs and token counts in English, Arabic, and Korean locales, maintaining consistency in technical terminology like "Cache Write" and "Input Tokens".
Sources: src/i18n/locales/en.json:300-310, src/i18n/locales/ar.json:300-310, src/i18n/locales/ko.json:300-310
RTL and Style Integration
The application uses Tailwind CSS and custom global styles to handle layout requirements. While the core i18n logic is in TypeScript, the styles.css file defines themes (Dark, Light, Gray, White) that are referenced in the settings.general.theme translation keys.
Sources: src/styles.css:120-220, src/i18n/locales/en.json:76-80
Conclusion
The internationalization framework in Opcode provides a robust foundation for multi-lingual development environments. By combining i18next with a structured locale hierarchy and automatic language detection, the project ensures a localized experience that persists across user sessions and adapts to diverse linguistic requirements.