PHPackages                             chamber-orchestra/translation-bundle - 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. [Database & ORM](/categories/database)
4. /
5. chamber-orchestra/translation-bundle

ActiveSymfony-bundle[Database & ORM](/categories/database)

chamber-orchestra/translation-bundle
====================================

Symfony bundle for multilingual entity localization and database-backed form field translations with XLIFF export.

v8.0.0(2mo ago)0144↑858.3%MITPHPPHP ^8.5CI passing

Since Feb 19Pushed 2mo agoCompare

[ Source](https://github.com/chamber-orchestra/translation-bundle)[ Packagist](https://packagist.org/packages/chamber-orchestra/translation-bundle)[ Docs](https://github.com/chamber-orchestra/translation-bundle)[ RSS](/packages/chamber-orchestra-translation-bundle/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (19)Versions (3)Used By (0)

[![PHP Composer](https://github.com/chamber-orchestra/translation-bundle/actions/workflows/php.yml/badge.svg)](https://github.com/chamber-orchestra/translation-bundle/actions/workflows/php.yml)

ChamberOrchestra Translation Bundle
===================================

[](#chamberorchestra-translation-bundle)

A Symfony 8 bundle for multilingual applications. Provides two complementary i18n systems:

1. **Entity localization** — multi-locale Doctrine entity pairs with automatic ORM relationship mapping at runtime.
2. **Form field localization** — database-backed translation keys for individual form fields with XLIFF export.

Features
--------

[](#features)

- **Automatic ORM mapping** via `TranslateSubscriber`: maps `oneToMany`/`manyToOne` associations at runtime — no manual Doctrine mapping required.
- **Locale fallback chain** in `translate()`: requested locale → language fallback (`en_US` → `en`) → kernel default locale.
- **`TranslatableProxyTrait`** for transparent property delegation: `$post->title` reads from the current translation without extra calls.
- **Form field localization** via `localization: true` on `TextType`, `TextareaType`, and `WysiwygType` — stores opaque UUID-based keys in the entity, displays human-readable values in the form.
- **`LocalizationLoaderChain`** — tagged, prioritized loader chain for resolving existing translation values; extend with custom loaders.
- **`ExportTranslationCommand`** (`translation:export`) — writes un-exported `Translation` records to `+intl-icu.{locale}.xliff` files grouped by domain, then marks them as exported.
- **CMS integration** (optional, requires `chamber-orchestra/cms-bundle`) — `TranslationsType` collection pre-populated per locale, rendered as Bootstrap nav tabs.

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

[](#requirements)

- PHP ^8.5
- Symfony 8.0 (framework-bundle, form, translation, uid, console, http-foundation)
- Doctrine ORM ^3.0 + DoctrineBundle ^3.0

Optional:

- `chamber-orchestra/doctrine-clock-bundle` — required if translatable entities use `TimestampCreateTrait`
- `chamber-orchestra/cms-bundle` — CMS form integration (`TranslationsType`, `AbstractTranslatableDto`)

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

[](#installation)

```
composer require chamber-orchestra/translation-bundle
```

Enable the bundle in `config/bundles.php`:

```
return [
    // ...
    ChamberOrchestra\TranslationBundle\ChamberOrchestraTranslationBundle::class => ['all' => true],
];
```

Usage
-----

[](#usage)

### System 1: Entity Localization

[](#system-1-entity-localization)

Define a translatable/translation entity pair. The `TranslateSubscriber` maps their Doctrine relationship automatically.

**Translatable entity** — implements `TranslatableInterface` + uses `TranslatableTrait`:

```
use ChamberOrchestra\TranslationBundle\Contracts\Entity\TranslatableInterface;
use ChamberOrchestra\TranslationBundle\Entity\TranslatableTrait;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class Post implements TranslatableInterface
{
    use TranslatableTrait;

    #[ORM\Id, ORM\GeneratedValue, ORM\Column]
    private int $id;

    // No manual Doctrine mapping needed for $translations —
    // TranslateSubscriber wires it automatically at loadClassMetadata.
}
```

**Translation entity** — implements `TranslationInterface` + uses `TranslationTrait`. The class name **must** be the translatable class name suffixed with `Translation`:

```
use ChamberOrchestra\TranslationBundle\Contracts\Entity\TranslationInterface;
use ChamberOrchestra\TranslationBundle\Entity\TranslationTrait;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ORM\Table(name: 'post_translation')]
class PostTranslation implements TranslationInterface
{
    use TranslationTrait;

    #[ORM\Id, ORM\GeneratedValue, ORM\Column]
    private int $id;

    #[ORM\Column]
    public string $title = '';

    // $locale and $translatable are provided by TranslationTrait.
    // The ManyToOne → Post association is mapped automatically.

    public function __construct(Post $post, string $locale, string $title)
    {
        $this->translatable = $post;
        $this->locale = $locale;
        $this->title = $title;
    }

    public function getId(): int { return $this->id; }
}
```

**Reading translations:**

```
// Current request locale (injected by TranslateSubscriber on postLoad):
$post->translate()->title;

// Explicit locale:
$post->translate('ru')->title;

// Fallback chain: fr_CA → fr → kernel default locale:
$post->translate('fr_CA')->title;
```

**Template shorthand** with `TranslatableProxyTrait` — delegates `$post->title` to `$post->translate()->title`:

```
use ChamberOrchestra\TranslationBundle\Entity\TranslatableProxyTrait;

class Post implements TranslatableInterface
{
    use TranslatableTrait;
    use TranslatableProxyTrait; // enables $post->title in Twig

    // ...
}
```

```
{# Both are equivalent after using TranslatableProxyTrait: #}
{{ post.translate().title }}
{{ post.title }}
```

**What `TranslateSubscriber` does automatically:**

TriggerAction`loadClassMetadata` on `Post`Maps `oneToMany` `translations` collection indexed by `locale`, cascade persist/remove`loadClassMetadata` on `PostTranslation`Maps `manyToOne` `translatable` with `CASCADE DELETE`; adds unique constraint `(translatable_id, locale)``postLoad`Injects `currentLocale` and `defaultLocale` from `RequestStack` / kernel default`prePersist`Injects `currentLocale` and `defaultLocale` on new entities---

### System 2: Form Field Localization

[](#system-2-form-field-localization)

Add `localization: true` to any `TextType`, `TextareaType`, or `WysiwygType` field. The entity stores an opaque key; the form shows the human-readable value.

```
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\Extension\Core\Type\TextareaType;

class ServiceType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('name', TextType::class, [
                'localization' => true,
                'localization_domain' => 'messages',   // default: 'messages'
                'localization_context' => ['ui' => 'service_name'], // optional, passed to TranslationEvent
            ])
            ->add('description', TextareaType::class, [
                'localization' => true,
            ]);
    }
}
```

**What happens on submit:**

1. `TranslatableTypeExtension` dispatches a `TranslationEvent(key, value, context)`.
2. Your listener persists the `Translation` entity:

```
use ChamberOrchestra\TranslationBundle\Events\TranslationEvent;
use ChamberOrchestra\TranslationBundle\Entity\Translation;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener]
final class TranslationPersistListener
{
    public function __construct(private readonly EntityManagerInterface $em) {}

    public function __invoke(TranslationEvent $event): void
    {
        $translation = Translation::create($event->key, $event->value, $event->context);
        $this->em->persist($translation);
    }
}
```

3. The entity stores the key (`messages@name.{uuid}`), not the human-readable text. Symfony's translator resolves it at render time once exported.

**Export stored translations to XLIFF:**

```
php bin/console translation:export
```

Writes `{domain}+intl-icu.{locale}.xliff` files to `%translator.default_path%`, marks records as exported, and dispatches `TranslationExportedEvent`.

**Translation key format:**

```
{domain}@[prefix.]uuid

```

```
use ChamberOrchestra\TranslationBundle\Utils\TranslationHelper;
use Symfony\Component\Uid\Uuid;

$uuid = Uuid::v7();
$key  = TranslationHelper::getLocalizationKey('messages', $uuid, 'service');
// → "messages@service.{uuid}"

TranslationHelper::getDomain($key);  // "messages"
TranslationHelper::getId($key);      // Uuid instance
TranslationHelper::getMessage($key); // "service.{uuid}"
```

---

### CMS Integration (optional)

[](#cms-integration-optional)

Requires `chamber-orchestra/cms-bundle`. Renders per-locale tabs in CMS edit forms:

```
use ChamberOrchestra\TranslationBundle\Cms\Form\Type\TranslatableTypeTrait;

class PostType extends AbstractType
{
    use TranslatableTypeTrait; // adds $builder->add('translations', TranslationsType::class, ...)

    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $this->addTranslationsField($builder, PostTranslationType::class);
    }
}
```

Configure available locales in `config/services.yaml`:

```
parameters:
    chamber_orchestra.translation_locales: [ru, en, de]
```

---

### Custom Localization Loaders

[](#custom-localization-loaders)

Implement `LocalizationLoaderInterface` and tag the service with `chamber_orchestra.localization_loader`. The `LocalizationLoaderChain` resolves existing translations by priority:

```
use ChamberOrchestra\TranslationBundle\Form\Loader\LocalizationLoaderInterface;

final class DatabaseLocalizationLoader implements LocalizationLoaderInterface
{
    public function load(string $key): ?string
    {
        // Return the human-readable value for this key, or null to pass through.
    }
}
```

```
# config/services.yaml
App\Localization\DatabaseLocalizationLoader:
    tags:
        - { name: chamber_orchestra.localization_loader, priority: 10 }
```

Testing
-------

[](#testing)

Integration tests require a PostgreSQL database. Set `DATABASE_URL` or use the default from `phpunit.xml.dist`:

```
composer install
DATABASE_URL="postgresql://user:pass@127.0.0.1:5432/mydb?serverVersion=17&charset=utf8" \
    ./vendor/bin/phpunit
```

Run only unit tests (no database required):

```
./vendor/bin/phpunit --testsuite Unit
```

License
-------

[](#license)

MIT

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance86

Actively maintained with recent releases

Popularity15

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~14 days

Total

2

Last Release

64d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/44037eb1c8dc2c4fa9871ac213653f33e22a9348dcec7132df07cc71933f2a2e?d=identicon)[wtorsi](/maintainers/wtorsi)

---

Top Contributors

[![wtorsi](https://avatars.githubusercontent.com/u/2115840?v=4)](https://github.com/wtorsi "wtorsi (1 commits)")

---

Tags

symfonyintllocalizationi18nl10ntranslationormdoctrinemultilingualtranslatableSymfony Bundlexliff

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/chamber-orchestra-translation-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/chamber-orchestra-translation-bundle/health.svg)](https://phpackages.com/packages/chamber-orchestra-translation-bundle)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M647](/packages/sylius-sylius)[a2lix/translation-form-bundle

Translate your doctrine objects easily with some helpers

3376.9M38](/packages/a2lix-translation-form-bundle)[easycorp/easyadmin-bundle

Admin generator for Symfony applications

4.3k16.7M309](/packages/easycorp-easyadmin-bundle)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[contao/core-bundle

Contao Open Source CMS

1231.6M2.3k](/packages/contao-core-bundle)[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)

PHPackages © 2026

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