# phpro/mage2-module-translations

> Manage translations via the Magento backend

`composer require phpro/mage2-module-translations`

Canonical URL: https://packagento.com/phpro/mage2-module-translations

## At a glance

- **Vendor**: phpro (https://packagento.com/phpro.md)
- **Latest version**: 1.7.0 — released 2025-07-10
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/phpro/mage2-module-translations and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require phpro/mage2-module-translations:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Manage translations via the Magento backend

## README

![](https://github.com/phpro/phpro-mage2-module-translations/workflows/.github/workflows/grumphp.yml/badge.svg)

![](https://shields.io/badge/Hyv%C3%A4_Theme-Compatible---?style=for-the-badge&labelColor=F6F7FF&color=0B23B9&logoColor=0B23B9&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZD0iTTkuNjI1IDkuNzdjMS4zNTUtMS4wNDcgMy4wMDgtMS43MDcgNC44NjctMS43MDcgMy44MDUgMCA3LjUwOCAyLjM2NyA3LjUwOCA4LjQzM1YyNGgtNC44Njd2LTcuNTA0YzAtMy4xMjktMS41MjgtNC4zMDgtMy42MTMtNC4zMDgtMS43MjMgMC0yLjk3My45Ni0zLjY2OCAxLjk3NlYyNEg0Ljk2NVY0LjUzMUgyTDMuNTYzIDBoNi4wNjJ2OS43N3pNMTYuNjQgMEgyMmwtMS41NyA0LjUzMWgtNS4zNTJMMTYuNjQgMHoiLz48L3N2Zz4K)

## 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)](./resources/phpro-translation-module-EUD.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.

_(README truncated for .md surface. Full README on https://packagento.com/phpro/mage2-module-translations.)_

## Changelog

### [1.0.0] - 2022-01-28
#### Added
- 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

### [1.1.0] - 2022-05-18
#### Added
- PHP 8.0 compatibility

### [1.2.0] - 2022-05-19
#### Added
- PHP 8.1 compatibility
#### Removed
- PHP 8.0 compatibility

### [1.2.1] - 2022-06-29
#### Bugfix
- Fix return type

### [1.2.2] - 2022-10-14
#### Added
- Hyva support: remove requirejs from head.additional

### [1.3.0] - 2024-03-28
#### Updated
- PHP ^8.1 compatibility 

### [1.4.0] - 2024-06-05
#### Updated
- Set minimum PHP version to 8.3
#### Bugfix
- Fix return types console commands
- Locales are not found if set in env.php and not in core_config_table

### [1.4.1] - 2024-07-02
#### Bugfix
- Fix faulty doc blocs preventing di:compile

### [1.4.2] - 2024-07-05
#### Updated
- Allow PHP 8.2

### [1.5.0] - 2024-07-19
#### Bugfix
- Proxied classes used in console commands
#### Removed
- Removed \Phpro\Translations\Model\Translation\Source\Locales dependency in \Phpro\Translations\Console\Command\PrepareKeysCommand

### [1.6.0] - 2025-03-17
#### Updated
- Reallow PHP 8.1
#### Bugfix
- Fix CSP in checkout

### [1.7.0] - 2025-07-10
#### Added
- Compatibility with PHP 8.4: Use explicit nullable type

## Recent Versions

| Version | Released |
|---|---|
| 1.7.0 | 2025-07-10 |
| 1.6.1 | 2025-05-16 |
| 1.6.0 | 2025-03-17 |
| 1.5.0 | 2024-07-19 |
| 1.4.2 | 2024-07-05 |
| 1.4.1 | 2024-07-02 |
| 1.4.0 | 2024-07-01 |
| 1.4.0-rc1 | 2024-05-24 |
| 1.3.0 | 2024-03-28 |
| 1.2.3 | 2022-11-30 |

Showing 10 of 15 versions. Full release history on https://packagento.com/phpro/mage2-module-translations.

## Dependencies

### Require

| Package | Constraint |
|---|---|
| magento/framework | ^102.0\|^103.0 |
| magento/module-backend | ^101.0\|^102.0 |
| magento/module-ui | ^101.0\|^102.0 |
| php | ^8.1 |

### Require (dev)

| Package | Constraint |
|---|---|
| friendsofphp/php-cs-fixer | ^3.59 |
| magento/magento-coding-standard | * |
| php-parallel-lint/php-parallel-lint | ^1.3 |
| phpro/grumphp-shim | ^2.6 |
| phpunit/phpunit | ^9.5 |
| squizlabs/php_codesniffer | ~3.7 |

## Quality

Latest release (1.7.0) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | 1 |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Fail | 17 | 2 errors, 15 warnings (ruleset: Magento2) |
| PHPMD | Warning | 13 | 13 rule violations (MissingImport:9, UnusedFormalParameter:4) |
| Cpd | Pass | 0 |  |
| Composer validate | Pass | 0 |  |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 28 | 28 | – | – |
| 2.4.8 | – | 29 | 29 | – |
| 2.4.9 | – | – | 29 | 30 |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | 2 | 2 | – |
| 2.4.9 | – | – | 2 | 2 |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["phpro/mage2-module-translations"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

phpro is a Magento 2 vendor on Packagento. See https://packagento.com/phpro.md for their full catalogue.