The Phpro_Translations module helps you to manage translations via the Magento backend.
- Simple backend CRUD to manage translations
- Single and multi-inline editing via the grid-overview
- Import and export via CSV files via CLI
- Import and export via default Magento import/export functionality
- Prepare new translations via data patch scripts
- (Re)generate frontend translations (JSON translation files) via CLI and backend
composer require phpro/mage2-module-translations
Download the end user documentation (PDF)
All locales must be defined in an ISO format. Locale = ISO-639 (language) + "_" + ISO-3166 (country).
Examples of locales: en_US, nl_BE, nl_NL, fr_BE, de_DE, ...
CSV structure must be (key, value):
"Transkey 1","Transvalue 2"
"Transkey 2","Transvalue 2"
...
Use the phpro:translations:import command to import a CSV file for a given locale. Duplicate records are skipped and no updates are applied.
bin/magento phpro:translations:import /path/to/cs_CZ/cs_CZ.csv cs_CZ --clear-cache
Output:
Importing CSV file /path/to/cs_CZ/cs_CZ.csv for locale cs_CZ
#created: 193
#skipped: 4
#failed: 0
Caches cleared: full_page, block_html, translate
Done!
Use the phpro:translations:export command to export database translations to a CSV file for one or more locales. Separate multiple locales with a space. The exported CSV file is written in the var/translations folder of Magento.
bin/magento phpro:translations:export nl_BE cs_CZ
Output:
Exporting translations to CSV file
Csv file: /path/to/var/translations/20190531_085402_export_nl_BE_cs_CZ.csv
Total written rows: 390
Done!
CSV structure:
"New Account","Nieuwe account",nl_BE
"My Wish List","Mijn verlanglijst",nl_BE
"New Account","Nový účet",cs_CZ
"My Wish List","Mé oblíbené",cs_CZ
...
You can use the exported CSV file(s) to import on another environment. For example you can prepare new translations on a staging environment and import them later on a production environment.
CSV structure must be (key, value, locale):
"Transkey 1","Transvalue 2",nl_BE
"Transkey 2","Transvalue 2",nl_BE
"Transkey 1","Transvalue 2",fr_BE
"Transkey 2","Transvalue 2",fr_BE
...
Use the phpro:translations:import-full command to import a CSV file. Duplicate records are skipped and no updates are applied.
bin/magento phpro:translations:import-full /path/to/full_import_nl_BE_cs_CZ.csv --clear-cache
Output:
Importing CSV file /path/to/full_import_nl_BE_cs_CZ.csv
#created: 10
#skipped: 380
#failed: 0
Caches cleared: full_page, block_html, translate
Done!
Go to System → (Data Transfer) → Import to create or update translations based on a CSV file. Please reach out our end user documentation.
Generating/re-generating frontend translation will generate JSON file(s) which includes all the frontend/JS translations.
These files are stored in the pub/media/phpro_translations directory in their related theme/locale subdirectory.
- Go to "Translations -> Generate frontend translations" in the admin. Select "all store views" or select specific ones. Click the button "Generate translations files".
- Clear full page and block html caches via "System -> Cache Management".
- Also check the end user documentation
- Use the
phpro:translations:generate-frontend-translationscommand to re-generate new JSON file(s) - Make sure you clean full_page and block_html cache manually afterwards to apply and enable the newest translation JSON file for the storefront.
Re-generate for single store view
Specify the storeId argument to re-generate for specific store view (locale). Use the bin/magento store:list command to show the store IDs.
bin/magento phpro:translations:generate-frontend-translations 5
Re-generate for all
Leave the storeId argument empty to re-generate for all store views.
bin/magento phpro:translations:generate-frontend-translations
We recommend to re-generate all frontend translations during your build process with phpro:translations:generate-frontend-translations after the setup:upgrade --keep-generated step and just before deactivating maintenance.
The translations JSON files are stored in the directory pub/media/phpro_translations with a specific version string.
You can choose to have a these files optimally cached by browsers by configuring the Cache-Control header. A ngnix example below:
location /media/phpro_translations/ {
add_header X-Frame-Options "SAMEORIGIN";
add_header Cache-Control "public";
expires +1y;
}
Use the phpro:translations:prepare-keys command to collect translations phrases from the code base and prepare them. This will create a translation for every available locale.
To prepare, create or delete translations you can inject \Phpro\Translations\Api\TranslationDataManagementInterface as dependency into your data patch script of your module.
Add the translation key for all enabled locales of the Magento instance. If default translation is not set, the translation key will be used as default translation.
use Magento\Framework\Setup\Patch\DataPatchInterface;
use Magento\Framework\Setup\Patch\NonTransactionableInterface;
use Phpro\Translations\Model\TranslationDataManagement;
class HelloWorldTranslations implements DataPatchInterface, NonTransactionableInterface
{
private TranslationDataManagement $translationDataManagement;
public function __construct(
TranslationDataManagement $translationDataManagement
) {
$this->translationDataManagement = $translationDataManagement;
}
public function apply()
{
$this->translationDataManagement->prepare('Hello world!');
$this->translationDataManagement->prepare('Welcome %1', 'Hello %1');
// other translation keys here...
}
}
Add a translation for given locales.
use Magento\Framework\Setup\Patch\DataPatchInterface;
use Magento\Framework\Setup\Patch\NonTransactionableInterface;
use Phpro\Translations\Model\TranslationDataManagement;
class HelloWorldTranslations implements DataPatchInterface, NonTransactionableInterface
{
private TranslationDataManagement $translationDataManagement;
public function __construct(
TranslationDataManagement $translationDataManagement
) {
$this->translationDataManagement = $translationDataManagement;
}
public function apply()
{
$this->translationDataManagement->create('Hello world!', 'Hallo wereld!!!', ['nl_NL', 'nl_BE']);
$this->translationDataManagement->create('Hello world!', 'Hello world!!!', ['en_US']);
// other translation keys here...
}
}
Delete a translation for given translation key and locale(s). In case no locales are given, all enabled locales will be used for deletion.
use Magento\Framework\Setup\Patch\DataPatchInterface;
use Magento\Framework\Setup\Patch\NonTransactionableInterface;
use Phpro\Translations\Model\TranslationDataManagement;
class DeleteHelloWorldTranslations implements DataPatchInterface, NonTransactionableInterface
{
private TranslationDataManagement $translationDataManagement;
public function __construct(
TranslationDataManagement $translationDataManagement
) {
$this->translationDataManagement = $translationDataManagement;
}
public function apply()
{
$this->translationDataManagement->delete('Hello world!');
$this->translationDataManagement->delete('Welcome %1', ['nl_BE', 'nl_NL']);
// other translation keys here...
}
}
The checkbox "frontend" could be used to mark translations that need to be exported to a PWA installation. With a rest API call, the translations can be fetched and stored in the PWA translations files.
curl -G -k -H "Authorization: Bearer <token>" --data-urlencode "searchCriteria[filter_groups][0][filters][0][field]=frontend" --data-urlencode "searchCriteria[filter_groups][0][filters][0][value]=1" --data-urlencode "searchCriteria[filter_groups][1][filters][0][field]=locale" --data-urlencode "searchCriteria[filter_groups][1][filters][0][value]=<locale>" <Magento base url>rest/V1/phpro-translations/translation/search