Internationalization (i18n)
Relevant source files
The following files were used as context for generating this wiki page:
The Internationalization (i18n) system in DevUtils is designed to provide a multi-language experience for a suite of developer utilities. It utilizes industry-standard libraries to manage translation resources and detect user language preferences, ensuring that the user interface, tool descriptions, and error messages are accessible in English, Simplified Chinese, and Traditional Chinese.
Sources: lib/i18n.ts:1-32, package.json:54-55, 68
Core Architecture
The i18n architecture is built upon the i18next ecosystem, specifically leveraging react-i18next for React integration and i18next-browser-languagedetector for automatic locale discovery. The system centralizes all string resources into JSON files located in the messages/ directory, which are then imported and initialized within a core configuration file.
Sources: lib/i18n.ts:1-8, package.json:54-55, 68
Framework Integration
The project uses a standard initialization pattern where i18next is configured with translation resources and then passed to the React application through initReactI18next.
The diagram shows the initialization flow where the core engine utilizes a detector and React bindings to serve JSON-based language resources.
Sources: lib/i18n.ts:9-25
Language Resources and Configuration
Translation strings are organized by functional areas (e.g., app, sidebar, tools, settings, common) within locale-specific JSON files.
Supported Languages
| Language Code | Description | Source File |
|---|---|---|
en | English | messages/en.json |
zh | Simplified Chinese (简体中文) | messages/zh.json |
zh-TW | Traditional Chinese (繁體中文) | messages/zh-TW.json |
Sources: lib/i18n.ts:13-23, messages/en.json:692-694, messages/zh.json:692-694
Initialization Parameters
The i18n system is initialized with specific constraints to ensure stability and fallback behavior:
- Fallback Language: Defaulting to
enif a translation is missing or the detected language is unsupported. - Interpolation:
escapeValueis set tofalseas React inherently handles XSS protection. - Persistence: User language choice is cached in
localStorageto persist across sessions.
Sources: lib/i18n.ts:24-31
Implementation in Components
Components consume translations using the useTranslation hook provided by react-i18next. This allows for dynamic string replacement and reactive UI updates when the language changes.
Usage Patterns
Developers utilize the t function to access nested keys within the JSON resource files. The system supports complex features such as variable interpolation for dynamic values (e.g., item counts or format names).
// Example from data-converter.tsx
const { t } = useTranslation();
// Simple translation
<Label>{t("tools.jsonCsv.from")}</Label>
// Translation with interpolation
<Textarea
placeholder={t("tools.jsonCsv.inputPlaceholder", {
format: sourceFormat.toUpperCase(),
})}
/>
Sources: components/tools/data-converter.tsx:41, 480, 520, messages/en.json:160
Logic Flow for String Resolution
When a component requests a translation, the system follows a specific resolution path to ensure the correct string is rendered.
The sequence diagram illustrates the lookup process from a functional component to the resource store.
Sources: components/tools/blame-intern.tsx:112, lib/i18n.ts:13-21
Error Handling and Validation Messages
Internationalization extends to error reporting within individual tools. Error messages are defined under specific errors keys within each tool's configuration section in the JSON files. This ensures that validation logic, such as regex pattern errors or file processing failures, remains localized.
| Tool | Error Key Example | Description |
|---|---|---|
| Blame Intern | tools.blameIntern.errors.noBugDescription | Prompt when description is missing. |
| Data Converter | tools.jsonCsv.conversionFailed | Generic conversion failure. |
| Base64 | tools.base64.errors.invalidHex | Validation for hex strings. |
Sources: messages/en.json:117, 163, 110, components/tools/blame-intern.tsx:113
Conclusion
The i18n system provides a robust foundation for supporting a global developer audience. By separating translation data from component logic and utilizing standard web technologies, the project maintains a maintainable and scalable approach to localization.
Sources: lib/i18n.ts:1-32, README.md:1-5