PHPackages locastic/api-platform-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. [Localization & i18n](/categories/localization) 4. / 5. locastic/api-platform-translation-bundle ActiveSymfony-bundle[Localization & i18n](/categories/localization) locastic/api-platform-translation-bundle ======================================== Translation bundle for Api platform based on Sylius translation v2.0.1(1mo ago)84480.1k↓46.7%30[4 issues](https://github.com/Locastic/ApiPlatformTranslationBundle/issues)MITPHPPHP ^8.2CI passing Since Sep 24Pushed 3w ago8 watchersCompare [ Source](https://github.com/Locastic/ApiPlatformTranslationBundle)[ Packagist](https://packagist.org/packages/locastic/api-platform-translation-bundle)[ RSS](/packages/locastic-api-platform-translation-bundle/feed)WikiDiscussions master Synced 2w ago READMEChangelog (10)Dependencies (21)Versions (21)Used By (0) Locastic Api Translation Bundle [ ![](https://camo.githubusercontent.com/6ddc97b05888a7e79d0181526177d2adafa37646ad2494d5922db240c9ed0164/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6c6f6361737469632f6170692d706c6174666f726d2d7472616e736c6174696f6e2d62756e646c652e737667) ](https://packagist.org/packages/locastic/api-platform-translation-bundle "License") [ ![](https://camo.githubusercontent.com/2b3da573870fbd031c0d8ac1c0350513fa7596daf5f20b48f44a96d9cad6f85f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f4c6f6361737469632f6170692d706c6174666f726d2d7472616e736c6174696f6e2d62756e646c652e737667) ](https://packagist.org/packages/locastic/api-platform-translation-bundle "Version") [ ![](https://github.com/Locastic/ApiPlatformTranslationBundle/actions/workflows/phpunit.yml/badge.svg) ](https://github.com/Locastic/ApiPlatformTranslationBundle/actions/workflows/phpunit.yml "Build status") [ ![](https://camo.githubusercontent.com/14cbea337f2e7728382c32cdc00dcedd0f8fd365d8ebf6df40883ee71ef11510/68747470733a2f2f706f7365722e707567782e6f72672f6c6f6361737469632f6170692d706c6174666f726d2d7472616e736c6174696f6e2d62756e646c652f646f776e6c6f616473) ](https://packagist.org/packages/locastic/api-platform-translation-bundle "Total Downloads") ========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== [](#locastic-api-translation-bundle----------------------------------------------------------------) Translation bundle for [API Platform](https://api-platform.com/) based on [Sylius translation](https://docs.sylius.com/en/1.2/book/architecture/translations.html): translations are stored per locale in a dedicated translation entity and exposed through your API as embedded objects, with the active locale resolved from each request. Supported versions: ------------------- [](#supported-versions) VersionPHPAPI PlatformDoctrine ORM2.x (`master`)`^8.2``^3.4 || ^4.0``^3.0`1.4`^8.1``^2.1 || ^3.0``^3.0`Installation: ------------- [](#installation) ``` composer require locastic/api-platform-translation-bundle ``` Configuration: -------------- [](#configuration) The bundle works without any configuration. All options and their defaults: ``` # config/packages/api_platform_translation.yaml api_platform_translation: # Locales accepted from the ?locale= query parameter and Accept-Language # negotiation. Empty (the default) inherits framework.enabled_locales; # when both are empty, any requested locale is accepted. enabled_locales: [] # Locale used when a translation for the current locale does not exist. # null (the default) inherits framework.default_locale. fallback_locale: null # true (the legacy behavior): reading a translation that does not exist # creates an empty one and attaches it to the entity, and with the # documented cascade persist mapping a plain read can then insert empty # rows into the database. false: reads never write, a missing translation # just shows empty fields. Setters work either way, they write through # getOrCreateTranslation() (see below). The default flips to false in # 3.0; leaving the option unset is deprecated since 2.1. auto_create_translations: true # Whether queries for translatable resources fetch-join the translations, # so listing N resources issues one query instead of one per entity per # locale. Set false to restore lazy loading. eager_load_translations: true # Ordered sources the request locale is resolved from; the first source # producing a locale wins. Remove a source to disable it. locale_resolution: - query_param - accept_language ``` For example, to resolve the locale from the `Accept-Language` header only and ignore the `?locale=` query parameter: ``` api_platform_translation: locale_resolution: [accept_language] ``` Implementation: --------------- [](#implementation) **Translatable entity:** - Extend your resource with `Locastic\ApiPlatformTranslationBundle\Model\AbstractTranslatable` - Add a `createTranslation()` method which returns a new object of the translation entity - Add a `translations` property: a `OneToMany` to the translation entity, indexed by locale, with the `translations` serialization group - Add virtual fields for all translatable fields; getters delegate to `getTranslation()` (current locale, with fallback), setters to `getOrCreateTranslation()` (exact locale, created and attached when missing) Example: ``` use ApiPlatform\Metadata\ApiResource; use ApiPlatform\Metadata\Get; use ApiPlatform\Metadata\GetCollection; use ApiPlatform\Metadata\Patch; use ApiPlatform\Metadata\Post; use ApiPlatform\Metadata\Put; use Doctrine\Common\Collections\Collection; use Doctrine\ORM\Mapping as ORM; use Locastic\ApiPlatformTranslationBundle\Model\AbstractTranslatable; use Locastic\ApiPlatformTranslationBundle\Model\TranslationInterface; use Symfony\Component\Serializer\Attribute\Groups; #[ORM\Entity] #[ApiResource( operations: [ new Get(), new GetCollection(), new Post(normalizationContext: ['groups' => ['translations']]), new Patch(normalizationContext: ['groups' => ['translations']]), // PUT replaces the resource; standard_put must be off so it edits the // managed entity instead of building a new one (see the notes below). new Put( normalizationContext: ['groups' => ['translations']], extraProperties: ['standard_put' => false], ), ], normalizationContext: ['groups' => ['article_read']], denormalizationContext: ['groups' => ['article_write']], filters: ['translation.groups'], )] class Article extends AbstractTranslatable { #[ORM\Id] #[ORM\GeneratedValue] #[ORM\Column] private ?int $id = null; #[ORM\OneToMany( targetEntity: ArticleTranslation::class, mappedBy: 'translatable', fetch: 'EXTRA_LAZY', indexBy: 'locale', cascade: ['persist'], orphanRemoval: true, )] #[Groups(['article_write', 'translations'])] protected Collection $translations; public function getId(): ?int { return $this->id; } #[Groups(['article_read'])] public function getTitle(): ?string { return $this->getTranslation()->getTitle(); } public function setTitle(string $title): void { $this->getOrCreateTranslation()->setTitle($title); } protected function createTranslation(): TranslationInterface { return new ArticleTranslation(); } } ``` **Translation entity:** - Add an entity with all translatable fields. The convention is the name of the translatable entity + `Translation` - Extend `Locastic\ApiPlatformTranslationBundle\Model\AbstractTranslation` - Add the `translations` serialization group to all fields, plus your usual read/write groups Example: ``` use Doctrine\ORM\Mapping as ORM; use Locastic\ApiPlatformTranslationBundle\Model\AbstractTranslation; use Locastic\ApiPlatformTranslationBundle\Model\TranslatableInterface; use Symfony\Component\Serializer\Attribute\Groups; #[ORM\Entity] class ArticleTranslation extends AbstractTranslation { #[ORM\Id] #[ORM\GeneratedValue] #[ORM\Column] #[Groups(['translations'])] private ?int $id = null; #[ORM\ManyToOne(targetEntity: Article::class, inversedBy: 'translations')] protected ?TranslatableInterface $translatable = null; #[ORM\Column] #[Groups(['article_read', 'article_write', 'translations'])] private ?string $title = null; #[ORM\Column] #[Groups(['article_write', 'translations'])] protected ?string $locale = null; public function getId(): ?int { return $this->id; } public function getTitle(): ?string { return $this->title; } public function setTitle(string $title): void { $this->title = $title; } } ``` **API resource notes:** - The `translation.groups` filter (registered by this bundle) lets clients request all translation objects in a response via `?groups[]=translations`. Without the `translations` group, responses contain only the requested (or fallback) locale. - Add the `translations` group to the `normalizationContext` of `POST` and `PUT`/`PATCH` operations, as in the example above, so write operations return all translation objects. **Editing translations (`PUT` vs `PATCH`):** the bundle populates the submitted translations onto the managed entity, keeping existing translation rows (and their ids) stable, following the HTTP semantics of each method: - `PATCH` (`application/merge-patch+json`) is a partial edit: it updates the submitted locales and leaves the others untouched. This is the recommended way to edit translations and needs no extra configuration. - `PUT` is a full replace: locales absent from the payload are removed. For `PUT` you **must** disable API Platform's `standard_put`, either per operation (`extraProperties: ['standard_put' => false]`, as above) or once for the whole API: ``` # config/packages/api_platform.yaml api_platform: defaults: extra_properties: standard_put: false ``` With `standard_put` on, API Platform deserializes into a brand-new object and copies its properties (including the `translations` collection) over the managed entity, so translations cannot be matched to their existing rows. The bundle detects this misconfiguration and fails with an explicit error instead of letting the write die in the persistence layer. Usage: ------ [](#usage) ### Request a single locale [](#request-a-single-locale) Pass the locale as a query parameter: ``` GET /articles/1?locale=de ``` Or use the `Accept-Language` HTTP header: ``` GET /articles/1 Accept-Language: de ``` Translatable fields are returned in the requested locale; when no translation exists for it, the fallback locale is used. **Restricting locales:** if [`framework.enabled_locales`](https://symfony.com/doc/current/reference/configuration/framework.html#enabled-locales) or the bundle's own `enabled_locales` option (which takes precedence) is configured, only those locales are accepted: a `?locale=` value outside the list and non-matching `Accept-Language` headers fall back to the default locale. When neither is configured (Symfony's default), any requested locale is accepted. ### Return all translations in a response [](#return-all-translations-in-a-response) Add the `translations` serialization group through the `translation.groups`filter (registered by this bundle, enabled on the resource via `filters: ['translation.groups']`): ``` GET /articles/1?groups[]=translations ``` The group is added on top of the operation's normalization groups, so the response contains the single-locale virtual fields plus the full collection: ``` { "@id": "/articles/1", "title": "test", "translations": { "en": { "id": 2, "title": "test", "content": "test", "locale": "en" }, "de": { "id": 3, "title": "test de", "content": "test de", "locale": "de" } } } ``` ### Create a resource with translations (POST) [](#create-a-resource-with-translations-post) Submit `translations` as an object keyed by locale; each entry must repeat its `locale` field: ``` { "datetime": "2017-10-10", "translations": { "en": { "title": "test", "content": "test", "locale": "en" }, "de": { "title": "test de", "content": "test de", "locale": "de" } } } ``` ### Update translations (PATCH, recommended) [](#update-translations-patch-recommended) A merge patch updates only the submitted locales and leaves the others untouched; existing translation rows are updated in place, no `id` needed: ``` PATCH /articles/1 Content-Type: application/merge-patch+json ``` ``` { "translations": { "de": { "title": "test edit de", "locale": "de" } } } ``` Here the `de` title is updated while the `en` translation is left as is. ### Replace all translations (PUT) [](#replace-all-translations-put) `PUT` is a full replace: locales absent from the payload are removed. It requires `standard_put` to be disabled (see the editing notes under [Implementation](#implementation) above). Send the `id` of each existing translation so it is updated instead of replaced: ``` { "datetime": "2017-10-10T00:00:00+02:00", "translations": { "de": { "id": 3, "title": "test edit de", "content": "test edit de", "locale": "de" }, "en": { "id": 2, "title": "test edit", "content": "test edit", "locale": "en" } } } ``` Limitations: ------------ [](#limitations) - **Filtering and ordering by translated fields is not supported.** The translated values live on the translation entity and are exposed through virtual getters, so built-in API Platform filters (`SearchFilter`, `OrderFilter`, ...) cannot target them on the resource. Filtering on translation fields requires a custom filter joining the translation entity. Contribution ------------ [](#contribution) If you have an idea on how to improve this bundle, feel free to contribute. If you have problems or you found some bugs, please open an issue. Support ------- [](#support) Want us to help you with this bundle or any API Platform/Symfony project? Write us an email on ### Health Score 68 — FairBetter than 99% of packages Maintenance93 Actively maintained with recent releases Popularity51 Moderate usage in the ecosystem Community27 Small or concentrated contributor base Maturity84 Battle-tested with a long release history Bus Factor1 Top contributor holds 58.4% 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 ~149 days Recently: every ~197 days Total 20 Last Release 42d ago Major Versions v1.4.1 → v2.0.02026-07-07 PHP version history (6 changes)v1.0PHP ^7.1 v1.3PHP ^7.2.5 v1.3.4PHP ^8.0 1.x-devPHP ^8.1 v1.4.1PHP >=8.4 v2.0.0PHP ^8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/13758a6abd53618188475ebd3bab831a8669a3ebe7f9880a12a2ec1ba80b9643?d=identicon)[antonioperic](/maintainers/antonioperic) --- Top Contributors [![paullla](https://avatars.githubusercontent.com/u/6206691?v=4)](https://github.com/paullla "paullla (45 commits)")[![jewome62](https://avatars.githubusercontent.com/u/472429?v=4)](https://github.com/jewome62 "jewome62 (5 commits)")[![antonioperic](https://avatars.githubusercontent.com/u/2453151?v=4)](https://github.com/antonioperic "antonioperic (5 commits)")[![alanpoulain](https://avatars.githubusercontent.com/u/10920253?v=4)](https://github.com/alanpoulain "alanpoulain (4 commits)")[![guillaume-sainthillier](https://avatars.githubusercontent.com/u/5052984?v=4)](https://github.com/guillaume-sainthillier "guillaume-sainthillier (2 commits)")[![k-37](https://avatars.githubusercontent.com/u/60838818?v=4)](https://github.com/k-37 "k-37 (1 commits)")[![konradkozaczenko](https://avatars.githubusercontent.com/u/57705320?v=4)](https://github.com/konradkozaczenko "konradkozaczenko (1 commits)")[![luca-nardelli](https://avatars.githubusercontent.com/u/6215162?v=4)](https://github.com/luca-nardelli "luca-nardelli (1 commits)")[![Margauxfeslard](https://avatars.githubusercontent.com/u/48242659?v=4)](https://github.com/Margauxfeslard "Margauxfeslard (1 commits)")[![maxhelias](https://avatars.githubusercontent.com/u/12966574?v=4)](https://github.com/maxhelias "maxhelias (1 commits)")[![nirav-programmer](https://avatars.githubusercontent.com/u/421466?v=4)](https://github.com/nirav-programmer "nirav-programmer (1 commits)")[![Oipnet](https://avatars.githubusercontent.com/u/13480665?v=4)](https://github.com/Oipnet "Oipnet (1 commits)")[![pascal-zarrad](https://avatars.githubusercontent.com/u/14060618?v=4)](https://github.com/pascal-zarrad "pascal-zarrad (1 commits)")[![pgrimaud](https://avatars.githubusercontent.com/u/1866496?v=4)](https://github.com/pgrimaud "pgrimaud (1 commits)")[![samnela](https://avatars.githubusercontent.com/u/1852108?v=4)](https://github.com/samnela "samnela (1 commits)")[![SpartakusMd](https://avatars.githubusercontent.com/u/438308?v=4)](https://github.com/SpartakusMd "SpartakusMd (1 commits)")[![tacman](https://avatars.githubusercontent.com/u/619585?v=4)](https://github.com/tacman "tacman (1 commits)")[![Alex--C](https://avatars.githubusercontent.com/u/5671931?v=4)](https://github.com/Alex--C "Alex--C (1 commits)")[![ArnoudThibaut](https://avatars.githubusercontent.com/u/14937343?v=4)](https://github.com/ArnoudThibaut "ArnoudThibaut (1 commits)")[![CoalaJoe](https://avatars.githubusercontent.com/u/5689499?v=4)](https://github.com/CoalaJoe "CoalaJoe (1 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/locastic-api-platform-translation-bundle/health.svg) ``` [![Health](https://phpackages.com/badges/locastic-api-platform-translation-bundle/health.svg)](https://phpackages.com/packages/locastic-api-platform-translation-bundle) ``` ### Alternatives [easycorp/easyadmin-bundle Admin generator for Symfony applications 4.3k18.3M430](/packages/easycorp-easyadmin-bundle)[2lenet/crudit-bundle The easy like Crud'it Bundle. 1617.3k16](/packages/2lenet-crudit-bundle)[sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.5k6.0M777](/packages/sylius-sylius)[pimcore/pimcore Content & Product Management Framework (CMS/PIM/E-Commerce) 3.8k3.9M535](/packages/pimcore-pimcore)[rcsofttech/audit-trail-bundle Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking. 12017.1k](/packages/rcsofttech-audit-trail-bundle)[sulu/sulu Core framework that implements the functionality of the Sulu content management system 1.3k1.4M236](/packages/sulu-sulu) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)