Internationalization (i18n)
Relevant source files
The following files were used as context for generating this wiki page:
Internationalization in the Duplicator project is a robust system designed to provide multi-language support across the user interface. It employs a JSON-based storage mechanism for translations and provides both server-side PHP helpers and a client-side JavaScript engine for real-time "inline" editing. The system supports French (default), English, Spanish, and German, with hooks for Italian and Portuguese.
Sources: app/controler/functions/i18n.php:8-15, app/models/admin/TranslationManager.php:12-13
Core Architecture
The i18n system is built around the I18nManager class, which handles language detection, file loading, and string translation. It operates as a Singleton to ensure consistent state across the application lifecycle.
Language Detection
The system determines the active language using a specific priority order:
- Session: Checked first for an existing
$_SESSION['language']value. - Parameters:
GETorPOSTrequests containing alangkey. - HTTP Headers: Parsing the
HTTP_ACCEPT_LANGUAGEheader from the browser. - Fallback: Defaulting to French (
fr) if no other method succeeds.
Sources: app/controler/functions/i18n.php:24-63
Storage Mechanism
Translations are stored in the /app/translations/ directory as JSON files named by their language code (e.g., en.json). These files use a nested object structure to categorize strings by page or functional area (e.g., header, admin, stats).
Sources: app/translations/en.json:1-10, app/models/admin/TranslationManager.php:17
Data Flow for String Translation
The following diagram illustrates how the system resolves a translation key into a localized string.
Key Components and Functions
PHP Helper Functions
The system provides several global functions to simplify translation within templates:
| Function | Description |
|---|---|
__($key, $params) | Returns the translated string. |
_e($key, $params) | Echoes the translation; if admin is logged in, wraps it in an editable span. |
_h($key, $params) | Returns a translation safe for HTML attributes. |
generateLanguageSelector() | Generates a Bootstrap-compatible dropdown menu for language switching. |
Sources: app/controler/functions/i18n.php:191-248
Admin Translation Management
The TranslationManager class provides backend logic for the administrative interface, allowing CRUD operations on translation files.
- Flattening: Converts nested JSON objects into a flat associative array (e.g.,
header.title) for easier display in tables. - Statistics: Calculates completion percentages for each language based on the number of translated vs. total keys.
- Import/Export: Supports CSV format for bulk translation updates.
Sources: app/models/admin/TranslationManager.php:30-48, app/models/admin/TranslationManager.php:164-188, app/models/admin/TranslationManager.php:200-220
Inline Translation System
A unique feature of this project is the InlineTranslationEditor, which allows administrators to edit UI text directly on the page where it appears.
Editing Workflow
When editing is enabled via the UI toggle in the footer, the JavaScript controller attaches event listeners to all elements with the .translation-editable class.
Logic Details
- Persistence: The state of the editor (enabled/disabled) is stored in the browser's
localStoragevia the keyinline-editing-enabled. - Visual Feedback: Uses CSS transitions and FontAwesome icons (e.g.,
fa-spinner,fa-check) to indicate saving state. - Security: The editor only initializes if
document.bodycontains theadmin-modeclass or a specific admin session is detected.
Sources: app/public/js/inline-translation.js:12-42, app/public/js/inline-translation.js:235-255
Database and File Interactions
While the primary translations are file-based, the system interacts with the server through specific administrative endpoints.
| Feature | Logic Location | Source |
|---|---|---|
| JSON Persistance | TranslationManager::updateTranslation() | TranslationManager.php:108 |
| CSV Export | TranslationManager::exportToCSV() | TranslationManager.php:200 |
| Ajax Updates | admin_translations.html.php | admin_translations.html.php:403 |
The updateTranslation method utilizes recursive logic to navigate nested keys in the JSON structure before saving back to disk using JSON_PRETTY_PRINT and JSON_UNESCAPED_UNICODE.
Sources: app/models/admin/TranslationManager.php:131-152, app/tests/Feature/AdminTranslationManagerTest.php:55-61
Conclusion
The Internationalization system in Duplicator is highly integrated, bridging the gap between static JSON localization and dynamic administrative management. By providing both flat-table editing and contextual inline editing, it ensures that maintaining multi-language support is accessible for non-technical administrators while remaining performant through PHP's file-system operations.