feat(wip): resource translation

[alanpoulain]

Q	A
Branch?	main
Tickets	#1506
License	MIT
Doc PR	TODO

Introduces two interfaces: TranslatableInterface and TranslationInterface.
It's the user responsibility to implement these interfaces how they want, either by themselves or by using extensions like https://github.com/KnpLabs/DoctrineBehaviors/blob/master/docs/translatable.md.

During the serialization, if the resource uses the TranslatableInterface, the attribute value will be taken from the resource translation (represented by TranslationInterface), if available for the current locale.

During the deserialization (POST, PUT, PATCH), if the resource uses the TranslatableInterface, a resource translation will either be created or updated (if it already exists for the current locale).

In order to to it, the translatable resource needs to have the corresponding translation attribute (not mapped to Doctrine).
For instance, if we have a BookTranslation resource:

Click to expand

<?php

namespace App\Entity;

use ApiPlatform\Translation\TranslatableInterface;
use ApiPlatform\Translation\TranslationInterface;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class BookTranslation implements TranslationInterface
{
    #[ORM\Column(type: 'integer')]
    #[ORM\Id]
    #[ORM\GeneratedValue(strategy: 'AUTO')]
    public ?int $id = null;

    #[ORM\Column]
    public string $locale;

    #[ORM\Column]
    public string $name;

    #[ORM\ManyToOne(inversedBy: 'translations')]
    #[ORM\JoinColumn(onDelete: 'CASCADE', nullable: false)]
    public Book $translatable;

    public function getTranslatableResource(): TranslatableInterface
    {
        return $this->translatable;
    }

    public function getLocale(): string
    {
        return $this->locale;
    }

    public function setLocale(string $locale): void
    {
        $this->locale = $locale;
    }
}

Then the Book resource needs to have a name attribute:

Click to expand

<?php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Translation\TranslatableInterface;
use ApiPlatform\Translation\TranslationInterface;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;

#[ApiResource(
    normalizationContext: ['groups' => 'read'],
    translation: [
        'class' => BookTranslation::class,
    ],
)]
#[ORM\Entity]
class Book implements TranslatableInterface
{
    #[ORM\Column(type: 'integer')]
    #[ORM\Id]
    #[ORM\GeneratedValue(strategy: 'AUTO')]
    public ?int $id = null;

    #[Groups('read')]
    public string $name;
    
    /**
     * @var Collection<DummyTranslation>
     */
    #[ORM\OneToMany(targetEntity: BookTranslation::class, mappedBy: 'translatable', cascade: ['persist', 'remove'])]
    private Collection $translations;

    public function __construct()
    {
        $this->translations = new ArrayCollection();
    }

    public function getTranslations(): Collection
    {
        return $this->translations;
    }

    public function addTranslation(BookTranslation $translation): void
    {
        if (!$this->translations->contains($translation)) {
            $this->translations[] = $translation;
            $translation->translatable = $this;
        }
    }

    public function removeTranslation(BookTranslation $translation): void
    {
        $this->getTranslations()->removeElement($translation);
    }

    public function getResourceTranslation(string $locale): ?TranslationInterface
    {
        foreach ($this->getTranslations() as $translation) {
            if ($locale === $translation->getLocale()) {
                return $translation;
            }
        }

        return null;
    }

    public function getResourceTranslations(): iterable
    {
        return $this->getTranslations();
    }

    public function addResourceTranslation(TranslationInterface $translation): void
    {
        if ($translation instanceof BookTranslation) {
            $this->addTranslation($translation);
        }
    }

    public function removeResourceTranslation(TranslationInterface $translation): void
    {
        if ($translation instanceof BookTranslation) {
            $this->removeTranslation($translation);
        }
    }
}

You can also see that there is a new translation attribute for the resource.
It contains:

• class: the related translation class
• allTranslationsEnabled (or all_translations_enabled): to enable the retrieval of all translations
• allTranslationsClientEnabled (or all_translations_client_enabled): to allow the client to retrieve all translations
• allTranslationsClientParameterName (or all_translations_client_parameter_name): the parameter used to retrieve all translations

All the translations for a resource can be retrieved either by enabling allTranslationsEnabled (in this case they will always be sent in the response) or allTranslationsClientEnabled.

For instance with this configuration:

Click to expand

<?php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Translation\TranslatableInterface;
use Doctrine\ORM\Mapping as ORM;

#[ApiResource(
    normalizationContext: ['groups' => 'read'],
    translation: [
        'class' => BookTranslation::class,
        'allTranslationsClientEnabled' => true,
        // or 'all_translations_client_enabled' => true,
        'allTranslationsClientParameterName' => 'allT',
        // or 'all_translations_client_parameter_name' => 'allT',
    ],
)]
#[ORM\Entity]
class Book implements TranslatableInterface
{
    // ...
}

If the following request is sent:
GET /books?allT=1

The response will be:

Click to expand

{
    "@context": {
        "@vocab": "http://example.com/docs.jsonld#",
        "hydra": "http://www.w3.org/ns/hydra/core#",
        "name": {
            "@container": "@language",
            "@id": "Book/name"
        }
    },
    "@id": "/books",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "@id": "/books/1",
            "@type": "Book",
            "name": {
                "en": "Name in English",
                "fr": "Nom en français"
            }
        }
    ],
    "hydra:totalItems": 1,
    "hydra:view": {
        "@id": "/books?allT=1",
        "@type": "hydra:PartialCollectionView"
    }
}

The JSON-LD context is also changed accordingly (see https://json-ld.org/spec/latest/json-ld/#string-internationalization).

TODO:

• Update the JSON Schema.
• Make sure it works with GraphQL.

To change the locale, you can enable and use the Accept-Language header: https://symfony.com/blog/new-in-symfony-5-4-language-negotiation

See also:

• Unified API: JSON-LD and internationalisation Sylius/Sylius#11412
• [ADR] Strategy for resource internationalization in API Sylius/Sylius#12752

[lchrusciel]

Hey Alan,

thanks a lot for your work, looks really good. I cannot wait to test it in Sylius. One question tho. Is it required to have name property on a translatable entity? Can we achieve the same result with the getter method or some YAML/XML config?

[alanpoulain]

Hello @lchrusciel,
Yes of course, API Platform only needs to understand it as a property of your resource, so having only a getter is possible, as well as using the properties key in YAML / XML.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[SpartakusMd]

Hey @alanpoulain, it seems really nice.

I wanted to mention another approach to implementing translations, that can be seen in https://github.com/Locastic/ApiPlatformTranslationBundle.

The translations there are stored in the translations property in the response. For translated properties, the format stays always the same, but the value will be in the requested language. I would say this approach is better in the fact that it doesn't change the format of existing fields in the response.

In the projects we use, the translations are not returned by default and can be requested via the ?groups[]=... as we use GroupFilter.

For example if you make a get request in french and also retrieve the translations, you'll get the following:

{
    "title":"Dummy traduit en français",
    "content":"C'est un dummy !",
    "notTranslatedField": "Not translated",
    "translations": { 
        "en":{
            "title":"Dummy translated in English",
            "content":"It's a dummy!",
            "locale":"en"
        },
        "fr":{
            "title":"Dummy traduit en français",
            "content":"C'est un dummy !",
            "locale":"fr"
        }
    }
}

What do you think about this approach?

[alanpoulain]

Hello @SpartakusMd.
I know this bundle, its way of doing it is OK but does not follow any standard.
I'm not sure to understand your point, if you request a resource in a specific language, the format of existing fields will not be changed.
For instance, if you send the request GET /books/1 with the header Accept-Language: fr, you will have the following response:

{
    "@context": {
        "@vocab": "http://example.com/docs.jsonld#",
        "hydra": "http://www.w3.org/ns/hydra/core#",
        "@language": "fr"
    },
    "@id": "/books/1",
    "@type": "Book",
    "name": "Nom en français"
}

The format is only changed if you request all the translations.

[SpartakusMd]

Exactly. The format is only changed if you request all the translations and it becomes something like this:

{
    "@context": {
        "@vocab": "http://example.com/docs.jsonld#",
        "hydra": "http://www.w3.org/ns/hydra/core#",
        "@language": "fr"
    },
    "@id": "/books/1",
    "@type": "Book",
    "name": {
        "fr": "Nom en français"
    }
}

The field name changes from string to object. While I'm ok with it, it was flagged from the mobile teams it's hard for them to implement 2 different formats (there are cases when you need and don't need translations). This is why I was asking about it.

[alanpoulain]

OK I understand your point but it will not be changed since the specification defines it like this: https://www.w3.org/TR/json-ld/#example-71-language-map-expressing-a-property-in-three-languages

[celorodovalho]

There's no update about this PR?

[VincentLanglet]

Hi, are you still interested by this PR ? Do you have time to finish it and resolve the conflict ?
Thanks

Also, now Symfony has his own Translatable interface, does it still make sens to have one in ApiPlatform ?

[alanpoulain]

No I think this PR should be closed or taken over.