README

json-translation-bundle

Manage localized content in your Symfony applications.

Installation

composer require alexandre-fernandez/json-translation-bundle

Verify that the bundle is enabled in config/bundles.php :

return [
	// ...
    AlexandreFernandez\JsonTranslationBundle\JsonTranslationBundle::class => ['all' => true],
];

Configuration

# config/packages/json_translation.yaml
json_translation:
	# The default locale for the application, used as a fallback when no fallbacks are defined.
	# Use "%kernel.default_locale%" to use your application's default locale.
    default_locale: "en"
	# The enabled locales for the application, these will be the only supported ones, an empty array will accept any locale.
	# Use "%kernel.enabled_locales%" to use your application's enabled locales.
    enabled_locales: ["en", "fr", "es"]
	# Which locale will the application fallback on when the current locale is not found, an empty array will use this configuration's default locale instead.
    fallbacks: ["en", "es"]
	# If "true", `JsonTranslation` instances will default to the current request's locale, else they will default to this configuration's default locale.
    detect_request_locale: true

Basic usage

Add the translated property to its entity.

// src/Entity/Post.php
use App\Repository\PostRepository;
use Doctrine\ORM\Mapping as ORM;
use AlexandreFernandez\JsonTranslationBundle\Model\JsonTranslation;

#[ORM\Entity(repositoryClass: PostRepository::class)]
class Post
{
    #[ORM\Column(type: "json_translation")] // same as JsonTranslationType::TYPE (AlexandreFernandez\JsonTranslationBundle\Doctrine\Type\JsonTranslationType)
    private JsonTranslation $title;

    public function __construct()
    {
        $this->title = new JsonTranslation();
    }

    public function getTitle(): JsonTranslation
    {
        return $this->title;
    }

    public function setTitle(JsonTranslation $title): static
    {
        $this->title = $title;

        return $this;
    }
}

You can then populate title's translations using the setTranslation method, using ArrayAccess or using a translation array.

// using setTranslation
$post
	->getTitle()
	->setTranslation("en", "Hello")
	->setTranslation("fr", "Bonjour")
	->setTranslation("es", "Hola")
;

// using ArrayAccess
$post->getTitle()["en"] = "Hello";
$post->getTitle()["fr"] = "Bonjour";
$post->getTitle()["es"] = "Hola";

// using an array
$post->setTitle(JsonTranslation::createFromArray([
	"en" => "Hello",
	"fr" => "Bonjour",
	"es" => "Hola"
]));

JsonTranslation is Traversable, it can be used in a foreach.

foreach($title as $locale => $translation) {
	// ...
}

JsonTranslation is Stringable, it will automatically resolve to the current request locale (this behaviour can be disabled in the configuration).

<h1>{{ post.title }}</h1>

JsonTranslation Reference

static createFromArray(array $translations): static

Creates a new JsonTranslation instance from an array of translations (e.g, [ "en" => "hi", "fr" => "salut", "es" => null ]).

getEntries(): array

Returns all translation entries excluding null values (e.g., [ "en" => "hi", "fr" => "salut" ]).

getLocaleEntries(): array

Returns an array containing all the locales present in the translations (e.g., [ "en", "fr" ]).

getTranslationEntries(): array

Returns an array containing all the translations values (e.g., [ "hi", "salut" ]).

getLocale(): ?string

Returns the current JsonTranslation locale, when creating a new JsonTranslation it's initialized with the default locale or the current request's locale depending on your configuration. This is the locale which resolveTranslation and __toString default to.

setLocale(?string $locale): static

Sets the current JsonTranslation locale. See getLocale.

getTranslation(string $locale): ?string

Retrieves a translation for a specific locale.

setTranslation(string $locale, ?string $translation): static

Sets a translation for a specific locale. If $translation is null it will be deleted.

hasTranslation(string $locale): bool

Checks if a translation exists for a given locale.

deleteTranslation(string $locale): static

Deletes a translation for a specific locale. This can also be done using setTranslation.

resolveTranslation(?string $locale = null, bool $fallback = true): ?string

Resolves a translation based on the provided locale, with optional fallback. Defaults to the JsonTranslation current locale, see getLocale.

__toArray(): array

Alias for getEntries.

__toString(): string

Resolves a translation for the current JsonTranslation locale, see getLocale. If not found it will try to resolve a fallback locale (including the default locale).

__clone()

Clones the current JsonTranslation instance and enables usage with the clone keyword. This can be useful to change its reference to notify doctrine that the instance has changed.

JsonTranslationType Field

This field type is used to render and manage translations stored in a JsonTranslation object. It provides a user interface for editing translations for different locales.

The full list of options defined and inherited by this form type is available running this command in your app:

php bin/console debug:form JsonTranslationType

Basic form type usage

Imagine you have a field called title that stores translations in a JsonTranslation object. You can use JsonTranslationType to provide a user-friendly way to edit these translations:

use AlexandreFernandez\JsonTranslationBundle\Form\JsonTranslationType; // verify you're not importing the doctrine type

$builder->add('title', JsonTranslationType::class, [
	"locales" => ["en", "fr", "es"] // optional, defaults to the configuration's `enabled_locales`
]);

Field options

locales

type: array default: %json_translation.enabled_locales%

An array of locales that should be displayed in the form. If not specified, it defaults to the enabled locales in this bundle's config. The value can't be an empty array.

display_language

type: int or boolean default: JsonTranslationType::DISPLAY_LANGUAGE_CURRENT

Determines how the language associated with each translation is displayed. It accepts one of the following integer constants or false :

JsonTranslationType::DISPLAY_LANGUAGE_CURRENT (0): Displays the language name using the current request locale (e.g., "English (en)" if the current request is in English).

JsonTranslationType::DISPLAY_LANGUAGE_NATIVE (1): Displays the language name in its native language (e.g., "Français (fr)").

JsonTranslationType::DISPLAY_LANGUAGE_DEFAULT (2): Displays the language name using the application's default locale.

false: Does not display the language name next to the locale.

label_to_legend

type: bool default: true

If set to true, the form's label will be used as the legend of the fieldset that wraps the translations. The real label is then hidden ($formView->vars["label"] will be set to false and $formView->vars["legend"] will be populated with the label).

named_details

type: bool default: true

If set to true, the form's detail elements will have a name attribute. The name attribute groups multiple details elements, with only one open at a time.

Inherited Options

See KeyValueType.