PHPackages                             salesrender/plugin-component-translations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. salesrender/plugin-component-translations

ActiveLibrary

salesrender/plugin-component-translations
=========================================

SalesRender plugin translations component

0.1.7(4mo ago)01.1k↓100%4proprietaryPHPPHP >=7.4.0

Since Feb 19Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/SalesRender/plugin-component-translations)[ Packagist](https://packagist.org/packages/salesrender/plugin-component-translations)[ RSS](/packages/salesrender-plugin-component-translations/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (7)Versions (12)Used By (4)

salesrender/plugin-component-translations
=========================================

[](#salesrenderplugin-component-translations)

Internationalization (i18n) component for SalesRender plugins, providing JSON-based text localization with CLI tools for managing translation files.

Overview
--------

[](#overview)

This component implements a complete translation system for the SalesRender plugin ecosystem. It enables plugins to support multiple languages by storing translations in structured JSON files organized by categories and source strings.

The `Translator` class acts as the central entry point: it loads locale-specific JSON files, resolves translated strings with optional parameter interpolation, and falls back to the default language when a translation is missing. The component also ships with Symfony Console commands that automate the creation and synchronization of translation files by statically analyzing your plugin source code for `Translator::get()` calls.

Translation files are stored in the `translations/` directory at the project root (resolved relative to Composer's autoloader). Each file is named using the `xx_YY` locale format (e.g., `ru_RU.json`, `en_US.json`) and contains a JSON structure grouping translations by category.

Installation
------------

[](#installation)

```
composer require salesrender/plugin-component-translations
```

Requirements
------------

[](#requirements)

- PHP >= 7.4
- `ext-json`
- [nikic/php-parser](https://github.com/nikic/PHP-Parser) ^4.3
- [symfony/console](https://github.com/symfony/console) ^5.0
- [haydenpierce/class-finder](https://gitlab.com/hpierce1102/ClassFinder) ^0.4.0
- [xakepehok/path](https://github.com/XAKEPEHOK/Path) ^0.2
- [adbario/php-dot-notation](https://github.com/adbario/php-dot-notation) ^2.2

Key Classes
-----------

[](#key-classes)

### `Translator`

[](#translator)

**Namespace:** `SalesRender\Plugin\Components\Translations`

The main static class for configuring and retrieving translations.

#### Methods

[](#methods)

MethodSignatureDescription`config``static config(string $default): void`Initializes the translator with a default locale (e.g., `ru_RU`). Must be called before any other method.`get``static get(string $category, string $message, array $params = []): string`Returns a translated string for the given category and message key. Supports parameter interpolation via `{key}` placeholders. Falls back to default language, then to the raw `$message` string.`setLang``static setLang(string $lang): void`Sets the current language. Only applies if the language exists in the available languages list. Accepts both `en_US` and `en-US` formats.`getLang``static getLang(): string`Returns the currently active language code.`getDefaultLang``static getDefaultLang(): ?string`Returns the default language code, or `null` if not configured.`getLanguages``static getLanguages(): array`Returns an array of all available language codes (discovered from translation files plus the default language).---

### `Helper`

[](#helper)

**Namespace:** `SalesRender\Plugin\Components\Translations\Components`

Utility class for path resolution and language discovery.

#### Methods

[](#methods-1)

MethodSignatureDescription`getTranslationsPath``static getTranslationsPath(): Path`Returns a `Path` object pointing to the `translations/` directory at the project root (resolved via Composer's `ClassLoader`).`getLanguages``static getLanguages(): array`Scans the translations directory and returns an array of available locale codes (filenames matching the `xx_YY` pattern).---

### `CrawlerCommand` (abstract)

[](#crawlercommand-abstract)

**Namespace:** `SalesRender\Plugin\Components\Translations\Commands`

Abstract Symfony Console command that provides the core logic for extracting translatable strings from source code. It uses `nikic/php-parser` to parse all PHP classes under the `SalesRender\Plugin` namespace and finds every `Translator::get('category', 'message')` call.

#### Methods

[](#methods-2)

MethodSignatureDescription`crawl``protected crawl(): array`Parses all project classes and extracts `Translator::get()` calls. Returns an associative array `[category => [message => true]]`.`asJson``protected asJson(array $data): string`Converts a translation scheme array into a pretty-printed JSON string.`schemeToExport``protected schemeToExport(array $scheme): array`Transforms the internal scheme format into the export format with `source`/`translated` pairs.---

### `LangAddCommand`

[](#langaddcommand)

**Namespace:** `SalesRender\Plugin\Components\Translations\Commands`

Symfony Console command registered as `lang:add`. Creates a new translation file for a specified locale by crawling the source code for translatable strings.

**Usage:**

```
php console lang:add en_US
```

---

### `LangUpdateCommand`

[](#langupdatecommand)

**Namespace:** `SalesRender\Plugin\Components\Translations\Commands`

Symfony Console command registered as `lang:update`. Synchronizes all existing translation files with the current source code, preserving existing translations and creating `.old.json` backups when changes are detected.

**Usage:**

```
php console lang:update
```

Usage
-----

[](#usage)

### Basic Configuration

[](#basic-configuration)

Configure the translator in your plugin's `bootstrap.php` file:

```
use SalesRender\Plugin\Components\Translations\Translator;

// Set the default language for the plugin
Translator::config('ru_RU');
```

### Retrieving Translations

[](#retrieving-translations)

Use `Translator::get()` with a category and a message key:

```
use SalesRender\Plugin\Components\Translations\Translator;

// Simple translation
$name = Translator::get('info', 'PLUGIN_NAME');
$description = Translator::get('info', 'PLUGIN_DESCRIPTION');

// Translation with parameter interpolation
$label = Translator::get('autocomplete', 'DYNAMIC_VALUE #{value}', ['value' => $query]);
$range = Translator::get('autocomplete', 'GROUP_FROM_TO ({min}-{max})', ['min' => 1, 'max' => 10]);

// Using in form definitions
$title = Translator::get('settings', 'Settings');
$fieldLabel = Translator::get('settings', 'Answer prefix');
$error = Translator::get('settings', 'Field can not be empty');
```

### Switching Languages at Runtime

[](#switching-languages-at-runtime)

```
use SalesRender\Plugin\Components\Translations\Translator;

// Set language for the current request
Translator::setLang('en_US');

// Hyphenated format is also accepted (automatically converted to underscore)
Translator::setLang('en-US');

// Get the active language
$currentLang = Translator::getLang(); // e.g., "en_US"

// Get all available languages
$languages = Translator::getLanguages(); // e.g., ['ru_RU', 'en_US']
```

### Using with Plugin Info

[](#using-with-plugin-info)

Translations are commonly used with lazy-evaluated closures for plugin metadata so that the language can be resolved at request time:

```
use SalesRender\Plugin\Components\Info\Info;
use SalesRender\Plugin\Components\Info\PluginType;
use SalesRender\Plugin\Components\Info\Developer;
use SalesRender\Plugin\Components\Translations\Translator;

Translator::config('ru_RU');

Info::config(
    new PluginType(PluginType::MACROS),
    fn() => Translator::get('info', 'PLUGIN_NAME'),
    fn() => Translator::get('info', 'PLUGIN_DESCRIPTION'),
    new PluginPurpose(
        new MacrosPluginClass(MacrosPluginClass::CLASS_HANDLER),
        new PluginEntity(PluginEntity::ENTITY_ORDER)
    ),
    new Developer('LeadVertex', 'support@leadvertex.com', 'leadvertex.com')
);
```

### Using in Batch Handlers

[](#using-in-batch-handlers)

The batch component sets the language from the batch context before processing:

```
use SalesRender\Plugin\Components\Translations\Translator;

// Set the language passed from the batch request
Translator::setLang(str_replace('-', '_', $batch->getLang()));

// All subsequent Translator::get() calls will use this language
$errorMessage = Translator::get('batch', 'Failed to create waybill');
```

Translation File Format
-----------------------

[](#translation-file-format)

Translation files are stored in the `translations/` directory at the project root:

```
project-root/
  translations/
    ru_RU.json
    en_US.json

```

### JSON Structure

[](#json-structure)

```
{
    "info": [
        {
            "source": "PLUGIN_NAME",
            "translated": "Example plugin"
        },
        {
            "source": "PLUGIN_DESCRIPTION",
            "translated": "This plugin was created for demo purposes"
        }
    ],
    "settings": [
        {
            "source": "Settings",
            "translated": "Settings"
        },
        {
            "source": "Field can not be empty",
            "translated": "Field can not be empty"
        }
    ],
    "autocomplete": [
        {
            "source": "GROUP_FROM_TO ({min}-{max})",
            "translated": "From {min} to {max}"
        }
    ]
}
```

Each top-level key is a **category** (the first argument to `Translator::get()`). Each category contains an array of objects with:

- `source` -- the message key (second argument to `Translator::get()`)
- `translated` -- the localized text

### Parameter Interpolation

[](#parameter-interpolation)

Parameters are referenced with `{key}` syntax in both the source and translated strings:

```
{
    "sender": [
        {
            "source": "Sender #{number}",
            "translated": "Sender #{number}"
        }
    ]
}
```

```
Translator::get('sender', 'Sender #{number}', ['number' => $this->number]);
```

CLI Commands
------------

[](#cli-commands)

### Adding a New Language

[](#adding-a-new-language)

```
php console lang:add en_US
```

Creates `translations/en_US.json` with all discovered translatable strings and empty `translated` values. The locale must match the `xx_YY` format (e.g., `en_US`, `ru_RU`, `de_DE`). The command fails if the file already exists.

### Updating Existing Translations

[](#updating-existing-translations)

```
php console lang:update
```

Scans all source code under the `SalesRender\Plugin` namespace, then for each existing translation file:

- Adds new strings that were found in the code (with empty `translated` values)
- Removes strings that no longer exist in the code
- Preserves all existing translations for unchanged strings
- Creates a `xx_YY.old.json` backup when changes are detected

Configuration
-------------

[](#configuration)

The translator requires a single configuration call before use:

```
Translator::config('ru_RU');
```

The locale must follow the `xx_YY` format (ISO 639-1 language code + underscore + ISO 3166-1 alpha-2 country code). Hyphens are automatically converted to underscores.

Calling any method (`get`, `getLang`, `setLang`, `getLanguages`) before `config()` throws a `RuntimeException` with the message `"Translator was not configured"`.

API Reference
-------------

[](#api-reference)

### `Translator`

[](#translator-1)

```
public static function config(string $default): void
public static function get(string $category, string $message, array $params = []): string
public static function setLang(string $lang): void
public static function getLang(): string
public static function getDefaultLang(): ?string
public static function getLanguages(): array
```

### `Helper`

[](#helper-1)

```
public static function getTranslationsPath(): \XAKEPEHOK\Path\Path
public static function getLanguages(): array
```

### CLI Commands

[](#cli-commands-1)

CommandArgumentsDescription`lang:add``lang` (required) -- Locale code in `xx_YY` formatCreates a new translation JSON file`lang:update`noneSynchronizes all translation files with the current source codeDependencies
------------

[](#dependencies)

PackageVersionPurpose`nikic/php-parser`^4.3Static analysis of PHP source code to extract `Translator::get()` calls`symfony/console`^5.0CLI command infrastructure (`lang:add`, `lang:update`)`haydenpierce/class-finder`^0.4.0Discovering classes under the `SalesRender\Plugin` namespace for crawling`xakepehok/path`^0.2Filesystem path resolution for the translations directory`adbario/php-dot-notation`^2.2Dot notation access to parsed PHP AST nodes during source code crawlingSee Also
--------

[](#see-also)

- [salesrender/plugin-component-info](https://github.com/SalesRender/plugin-component-info) -- Uses `Translator` for localized plugin name and description in JSON serialization
- [salesrender/plugin-core](https://github.com/SalesRender/plugin-core) -- Contains `LanguageMiddleware` that calls `Translator::setLang()` based on the HTTP `Accept-Language` header
- [salesrender/plugin-component-batch](https://github.com/SalesRender/plugin-component-batch) -- Calls `Translator::setLang()` to set language from the batch processing context

###  Health Score

45

—

FairBetter than 92% of packages

Maintenance85

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 50% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~213 days

Recently: every ~320 days

Total

11

Last Release

138d ago

PHP version history (3 changes)0.0.1PHP >=7.1.0

0.1.1PHP >=7.2.0

0.1.4PHP >=7.4.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/6140af7bf37913fbad3d596efa1376ede23a55ac226a15b61857f4e58fc26c22?d=identicon)[SalesRender](/maintainers/SalesRender)

---

Top Contributors

[![LightFuri](https://avatars.githubusercontent.com/u/46054834?v=4)](https://github.com/LightFuri "LightFuri (3 commits)")[![IvanKalashnikov](https://avatars.githubusercontent.com/u/6877306?v=4)](https://github.com/IvanKalashnikov "IvanKalashnikov (2 commits)")[![XAKEPEHOK](https://avatars.githubusercontent.com/u/3051649?v=4)](https://github.com/XAKEPEHOK "XAKEPEHOK (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/salesrender-plugin-component-translations/health.svg)

```
[![Health](https://phpackages.com/badges/salesrender-plugin-component-translations/health.svg)](https://phpackages.com/packages/salesrender-plugin-component-translations)
```

###  Alternatives

[vimeo/psalm

A static analysis tool for finding errors in PHP applications

5.8k77.5M6.7k](/packages/vimeo-psalm)[behat/behat

Scenario-oriented BDD framework for PHP

4.0k96.8M1.9k](/packages/behat-behat)[silverstripe/framework

The SilverStripe framework

7213.5M2.5k](/packages/silverstripe-framework)[prestashop/prestashop

PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers.

9.0k15.4k](/packages/prestashop-prestashop)[coenjacobs/mozart

Composes all dependencies as a package inside a WordPress plugin

4723.6M19](/packages/coenjacobs-mozart)[magento/magento2-functional-testing-framework

Magento2 Functional Testing Framework

15511.5M30](/packages/magento-magento2-functional-testing-framework)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)