Module developers might be confused by both the Classic and New translation systems coexisting together. This page aims to help you choose the best one for your module.
The best translation system for your module depends on two factors:
If you target 1.7.6 or 1.7.7, you can choose one or the other. However, if you choose the New system, you will have to use Classic translation dictionaries (PHP-based).
| Target Minimum Version | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| ≤ 1.7.5 | 1.7.6 | 1.7.7 | ≥ 1.7.8 | ||||||
| Classic system | Recommended system | Yes | Yes | Yes | |||||
| New system | Not supported | It depends * | It depends * | Recommended system | |||||
Legend:
= Recommended system
No = Not available
Yes = Available
* Yes = Available, but only PHP dictionaries are supported (no export)
The chart below summarizes the differences between the two translation systems.
| Classic System | New System | |
|---|---|---|
| Available since | < 1.7 | 1.7.6+ |
| Translation interface | File-oriented (default interface) |
Translation domain-oriented (requires opt-in) |
| Wording contextualization / grouping | File where the wording appears | Translation domain |
| Automatic discovery of new wordings in module files | ✔️ Yes | ✔️ Yes |
| Custom translation storage | PHP-based dictionaries (stored within the module directory) |
Database |
| Translation distribution | PHP-based dictionaries | • PHP-based dictionaries • XLIFF files 1.7.8 |
| Export formats | PHP-based dictionaries | XLIFF files 1.7.8 |
| Export method | Copy files from the module’s directory | Download via export interface 1.7.8 |
| Supported environments | FO & BO | FO & BO |
| Method to use in PHP | l(...) |
trans(...) |
| Method to use in Smarty | {l mod="modulename" ...} |
{l d="Modules.Modulename.Something" ...} |
| Method to use in Twig | N/A | trans(...) |
| Supported in legacy controllers | ✔️ Yes | ✔️ Yes |
| Supported in Symfony controllers | ❌ No | ✔️ Yes |