A2lix TranslationForm Bundle

The bundle centralizes locale configuration through a LocaleProviderInterface.

By default, a SimpleLocaleProvider is registered and configured based on your bundle settings. If you need custom logic for determining available locales, you can replace the default service by configuring the locale_provider key in your bundle configuration.

When upgrading from version 3.x to 4.x, ensure your environment meets the new requirements and update your configuration and templates to accommodate breaking changes.

### Requirements for v4
- **PHP**: 8.4+
- **Symfony**: 7.4 or 8.0

Install the bundle using Composer to add translation management capabilities for Doctrine entities to your Symfony project.

composer require a2lix/translation-form-bundle

Configure the bundle in config/packages/a2lix.yaml. You can define which locales are enabled, which is the default, and which are required. If no template is specified, the bundle automatically prepends the Bootstrap 5 layout to Twig's form_themes.

a2lix_translation_form:
    enabled_locales: [en, fr, de]   # Optional. Default from framework.enabled_locales
    default_locale: en   # Optional. Default from framework.default_locale
    required_locales: [en]   # Optional. Default []
    # templating: "@A2lixTranslationForm/bootstrap_5_layout.html.twig"

The configuration keys in config/packages/a2lix.yaml have changed. Specifically, the locales key has been renamed to enabled_locales.

a2lix_translation_form:
    enabled_locales: [en, fr, de]   # Replaces 'locales'. Optional. Defaults to framework.enabled_locales
    default_locale: en            # Optional. Defaults to framework.default_locale
    required_locales: [en]        # Optional. Defaults to []

The default template has moved from Bootstrap 4 to Bootstrap 5. The Bootstrap 5 template uses the new tab API with data-bs-toggle and data-bs-target attributes. Alternatively, you can use the framework-agnostic native_layout.html.twig which requires no JS and is compatible with Gecko browsers.

# For Bootstrap 5
templating: "@A2lixTranslationForm/bootstrap_5_layout.html.twig"

# OR for framework-agnostic (No JS required)
templating: "@A2lixTranslationForm/native_layout.html.twig"

By default, the bundle uses a simple_locale_provider. If you need custom logic to determine available or required locales, you can provide your own service that implements A2lix\TranslationFormBundle\LocaleProvider\LocaleProviderInterface.

To use your custom provider, set the locale_provider key in your bundle configuration to your service's ID. When a custom provider is detected, the bundle will alias A2lix\TranslationFormBundle\LocaleProvider\LocaleProviderInterface to your service.

a2lix_translation_form:
    locale_provider: 'app.my_custom_locale_provider'

The LocaleSwitcher component allows you to render locale selection UI directly in Twig using the following syntax:

{# Render basic badges #}
<twig:A2lixTranslationForm:LocaleSwitcher render="basic" />

{# Render dropdown #}
<twig:A2lixTranslationForm:LocaleSwitcher render="dropdown" />

The bundle provides a locale_render helper to display localized locale names or formatted strings.

{{ locale_render('en') }}                     {# -> 'English' (localized) #}
{{ locale_render('en', 'locale_upper') }}     {# -> 'EN' #}
{{ locale_render('fr', 'locale_name_title') }}{# -> 'Français' #}

Use TranslationsType to handle translatable entities using either Gedmo PersonalTranslation or KnpDoctrineBehaviors.

• Gedmo PersonalTranslation: The bundle renders translation fields as separate translation objects and manages the creation/removal of Gedmo translation entities.
• KnpDoctrineBehaviors: Fields are bound directly to locale forms (one translation object per locale).

use A2lix\
TranslationFormBundle\\Form\\Type\\TranslationsType;
use Symfony\
Component\\Form\\Extension\\Core\\Type\\FormType;

$builder->add('translations', TranslationsType::class, [
    'translatable_class' => App\\Entity\\Post::class,
    // Optional:
    // 'locale_labels' => ['en' => 'English', 'fr' => 'Français'],
    // 'theming_granularity' => 'field', // or 'locale_field',
]);

Use TranslatedEntityType when you want an entity choice field (like a dropdown) where the labels are pulled from the entity's translations.

use A2lix\TranslationFormBundle\Form\Type\TranslatedEntityType;

$builder->add('category', TranslatedEntityType::class, [
    'class' => App\Entity\Category::class,
    'translation_property' => 'title',
]);