phpro / mage2-module-translations
Manage translations via the Magento backend
Installs: 33 799
Dependents: 0
Suggesters: 0
Security: 0
Stars: 13
Watchers: 6
Forks: 12
Open Issues: 4
Type:magento2-module
Requires
- php: ^8.2
- magento/framework: ^102.0|^103.0
- magento/module-backend: ^101.0|^102.0
- magento/module-ui: ^101.0|^102.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ~3.59.0
- magento/magento-coding-standard: ^33
- php-parallel-lint/php-parallel-lint: ^1.3
- phpro/grumphp-shim: ^2.6
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: ~3.7
README
Translation module for Magento 2
The Phpro_Translations
module helps you to manage translations via the Magento backend.
Features
- 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
Installation
composer require phpro/mage2-module-translations
End user documentation
Download the end user documentation (PDF)
Usage (technical)
Locales
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, ...
Import and export
Import Magento translation CSVs
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!
Export to CSV
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
...
Import CSV (including locale)
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!
Import via backend
Go to System → (Data Transfer) → Import to create or update translations based on a CSV file. Please reach out our end user documentation.
Re-generate frontend translations
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.
Via backend
- 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
Via CLI
- Use the
phpro:translations:generate-frontend-translations
command 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
During build process
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.
Browser cache optimizations
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;
}
Collect translations from code base
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.
Add translations during development
To prepare, create or delete translations you can inject \Phpro\Translations\Api\TranslationDataManagementInterface
as dependency into your data patch script of your module.
Prepare
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...
}
}
Create
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
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...
}
}
PWA
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.
API call that can be used in build scripts
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
Hyvä
Install the Hyvä compatibilty module. Minimum version is 1.2.3.
composer require hyva-themes/magento2-phpro-translations