 |
VOOZH | about |
|
VOOZH | about |
This document describes the internationalization (i18n) system in the Light framework, which provides multi-language support through database-backed translations and localized content. The system supports user-specific language preferences and delivers translations through the GraphQL API.
For user management and authentication, see Authentication and Authorization. For system configuration, see System Configuration.
The internationalization system consists of three primary components: the Translate model for storing key-value translation pairs, the SystemValue model for storing localized system values with status flags, and user language preferences stored in the User model. All translation data is retrieved dynamically through the GraphQL API based on the authenticated user's language preference.
Diagram: Internationalization Data Model
Sources: db.json1-676
The Translate table stores translation key-value pairs for each supported language. Each translation entry consists of a key (name) and its translated value (value) for a specific language.
| Column | Type | Description |
|---|---|---|
translate_id | int (PK, auto_increment) | Unique identifier for translation entry |
language | varchar(5) | Language code (e.g., "en", "zh-hk") |
name | varchar(255) | Translation key identifier |
value | varchar(255) | Translated text content |
The table has indexes on language, name, action, and module columns for efficient querying. The language and name combination allows looking up specific translations quickly.
Sources: db.json550-605
The SystemValue table stores localized system values that can be enabled or disabled through a status flag. This is distinct from the Translate table as it supports longer text content and status management.
| Column | Type | Description |
|---|---|---|
systemvalue_id | int (PK, auto_increment) | Unique identifier for system value |
name | varchar(64) | Value identifier/key |
value | text | Localized content (supports longer text) |
status | int (default: 0) | Active/inactive flag |
language | varchar(5) | Language code |
The table has indexes on both language and name columns for efficient filtering and retrieval.
Sources: db.json500-549
Each user's language preference is stored in the User table's language column, which accepts a 2-5 character language code (e.g., "en", "zh-hk"). This preference determines which translations are automatically loaded for that user.
Sources: db.json64-68
Diagram: Translation Loading Process
Sources: src/Type/App.php143-148
The getI18nMessages method retrieves all translations for the authenticated user's preferred language. The method uses the #[InjectUser] annotation to access the current user context, extracts their language preference (defaulting to "en" if not set), and queries the Translate model for all matching records.
Sources: src/Type/App.php143-148
Returns all translations for the current authenticated user's language preference. This is the primary method used by client applications to load localized text.
Method Signature:
Implementation Details:
#[Logged] annotation)$user->language ?? 'en'Translate::Query(["language" => $language])->toArray()Light\Model\Translate objectsSources: src/Type/App.php138-148
Returns all translation records across all languages. This method is typically used for administrative purposes to manage translations.
Method Signature:
Implementation Details:
Light\Model\Translate objectsSources: src/Type/App.php127-135
Returns the list of supported languages in the system. Currently returns a hardcoded list that can be extended.
Method Signature:
Implementation Details:
["name" => "English", "value" => "en"]["name" => "中文", "value" => "zh-hk"]Sources: src/Type/App.php151-158
Queries the SystemValue table with optional filters and sorting. Requires the systemvalue.list permission.
Method Signature:
Implementation Details:
systemvalue.list permission["language" => "en"]) and sort parametersLight\Db\Query object for pagination supportSources: src/Type/App.php500-510
The system currently supports two languages by default:
| Language Code | Display Name |
|---|---|
en | English |
zh-hk | 中文 (Traditional Chinese - Hong Kong) |
The language list is defined in the getLanguages method and can be extended by modifying the return array. The language column in both Translate and SystemValue tables uses varchar(5) to accommodate standard language codes including regional variants (e.g., "en-US", "zh-CN").
Sources: src/Type/App.php151-158 db.json527-530 db.json561-564
Diagram: Model Comparison
Sources: db.json550-605 db.json500-549
| Feature | Translate | SystemValue |
|---|---|---|
| Value Length | varchar(255) - short text | text - long content |
| Status Management | No status field | Has status flag (active/inactive) |
| Primary Use Case | UI labels, messages, short strings | Longer localized content, system values |
| Name Length | varchar(255) - longer keys | varchar(64) - shorter identifiers |
| Additional Indexes | action, module columns (deprecated) | Only name and language |
The Translate model is optimized for storing UI strings and labels, while SystemValue is designed for longer localized content that may need to be enabled or disabled dynamically through the status flag.
Sources: db.json550-605 db.json500-549
When a client application initializes, it typically follows this pattern:
getI18nMessages with authenticated request#[InjectUser] annotationuser.language field (defaults to "en")Sources: src/Type/App.php143-148
The name column in the Translate table serves as the translation key. Common patterns include:
"user.login.button", "dashboard.title""auth.password.reset", "file.upload.error""save", "cancel", "delete.confirm"The name column supports up to 255 characters, allowing for descriptive, hierarchical key structures.
Sources: db.json566-569
SystemValue entries are suitable for:
The status field allows administrators to enable/disable specific values without deleting them, useful for A/B testing or gradual rollout of new translations.
Sources: db.json500-549
Both Translate and SystemValue are referenced as model imports in the GraphQL root type and extend the base Light\Model class, providing automatic audit trails and GraphQL type mapping.
Light\Model\Translate - Translation key-value pairs
Light\Model\SystemValue - Localized system values with status
These models are automatically exposed as GraphQL types through GraphQLite's annotation system, allowing them to be queried and mutated through the GraphQL API.
Sources: src/Type/App.php17 src/Type/App.php16
Diagram: GraphQL Query Methods
Refresh this wiki