Localization (i18n)
Relevant source files
The following files were used as context for generating this wiki page:
The localization system in Rocreate is a multi-language framework designed to support over 10 languages. It utilizes a JSON5-based translation pipeline that separates source translation data from the compiled artifacts used at runtime. This architecture ensures that the application remains performant by lazily loading language files while providing a developer-friendly workflow for adding and syncing translations.
The system relies on English as the "source of truth." All translations are synchronized against a base English file, and any missing keys automatically fall back to their English counterparts to prevent UI breakage.
Sources: README.md:16-17, CLAUDE.md:43-45
Architecture and Data Flow
The localization architecture consists of a build-time generation phase and a runtime consumption phase. Source files are stored as JSON5 to allow comments and better formatting, which are then compiled into standard JSON and TypeScript files for use in the application.
Translation Workflow
The following diagram illustrates the lifecycle of a translation from source to runtime application.
The build script generate.js validates that translation values exist and match the structure of the base English file.
Sources: src/languages/generate.js:77-137, README.md:57-60
Build-Time Components
| Component | Description |
|---|---|
src/languages/_base-en.json5 | The master list of all translation keys and their English values. |
src/languages/languages.json | Registry of supported languages with their ISO 639-1 codes and native names. |
src/languages/generate.js | Node.js script that handles adding new languages, syncing with base, and building artifacts. |
src/app/languages/ | Target directory for generated JSON and TS files. |
Sources: src/languages/generate.js:80-83, README.md:52-54, src/app/languages/languages.ts:1-70
Translation File Structure
Translations are organized by unique keys referenced within the codebase. Each entry in a source .json5 file contains metadata to assist translators.
{
"stabilizer": {
"hint": "Common feature in drawing software to make lines smoother",
"original": "Stabilizer",
"value": "抖动修正"
}
}
- hint: Provides context or a description of where the text appears in the UI.
- original: The English string as defined in the base file.
- value: The actual translated string.
Sources: README.md:65-79, src/languages/generate.js:25-30
Runtime Implementation
At runtime, the application initializes the language system before the main controller (KlApp) starts. Language files are imported dynamically using asynchronous loading to minimize the initial bundle size.
Sequence Diagram: Language Initialization
The loadLanguage function utilizes dynamic import() statements to fetch the corresponding JSON file for the requested language code.
Sources: src/app/script/main-standalone.ts:32-34, src/app/languages/languages.ts:71-112, src/app/script/klecks/ui/tool-tabs/file-ui.ts:40-41
Key Functions and Types
TTranslationCode: A generated TypeScript type containing a union of all valid translation keys. This provides autocompletion and type safety when using theLANG()function.loadLanguage(code: string): An asynchronous function that returns a partial record of translation keys to strings.languages: An array of objects containingcodeandnamefor all supported locales.
Sources: src/app/languages/languages.ts:71-114, src/languages/generate.js:93-137
Management Commands
The system provides several CLI commands via npm or bun to manage translation files.
| Command | Description |
|---|---|
npm run lang:build | Generates .json and .ts files in src/app/languages. |
npm run lang:add <code> | Creates a new translation file from the base English template. |
npm run lang:sync | Synchronizes existing translation files with the base English file (Updates keys). |
npm run lang:build -- --missing | Lists all keys that are missing translations in the console output. |
Sources: README.md:46-51, CLAUDE.md:12-16, src/languages/generate.js:203-219
Summary
The Localization system in Rocreate provides a robust pipeline for managing multi-language support. By utilizing a pre-compilation step, the project maintains type safety through generated TypeScript definitions while ensuring optimal performance via dynamic loading of translation assets. The strict adherence to an English "source of truth" and the inclusion of translator hints makes the system scalable for community contributions.