wexample/symfony-translations

A translations service overrides to support translations files includes and multiple domains in Symfony translations

1.0.58 2025-07-21 12:07 UTC

Requires

• symfony/translation: >=6.2
• wexample/php-helpers: ^1.0.62
• wexample/php-yaml: ^1.0.35
• wexample/symfony-helpers: ^1.0.64
• wexample/symfony-testing: ^1.0.58

Requires (Dev)

• phpunit/phpunit: ^9.5
• wexample/symfony-testing: ^1.0.26

MIT

• weeger

• symfony-ux

README

An extension for Symfony's Translation component that adds support for YAML includes, references, and inheritance through integration with the wexample/php-yaml package.

Developed by Wexample.

Features

• YAML Includes: Reference translations from other YAML files using the @domain::key syntax
• Domain Aliases: Create aliases for translation domains to simplify references
• Context-Aware Translations: Automatically resolve translation paths based on the current controller/route
• Inheritance: Extend translation files with the ~extends directive
• Debug Tools: Twig functions to debug translation domains, locales, and catalogs
• Bundle Integration: Automatic handling of bundle translations with proper domain resolution
• Fallback Mechanism: Returns the full domain and key if a translation is not found, making debugging easier

Installation

composer require wexample/symfony-translations

Basic Usage

In Twig Templates

{# Use domain aliases for cleaner translation references #}
{{ '@page::body' | trans }}

{# Use domain and key directly #}
{{ 'WexampleSymfonyDesignSystemBundle.pages.demo.index::page_title' | trans }}

{# Debug translation information #}
{{ dump_trans() }}
{{ dump_trans_locales() }}
{{ dump_trans_domains() }}

In YAML Files

# Reference another translation
title: "@common.labels::welcome"

# Use the same key from another domain
description: "@common.labels::%"

# Extend another translation file
~extends: "@common.base"

Domain Resolution

The translator automatically handles domain resolution in various contexts:

1. Bundle Translations: When using translations from bundles, the system automatically handles paths with or without the 'assets' directory:

   // Both will work and point to the same translation
   $translator->trans('WexampleSymfonyDesignSystemBundle.pages.demo.index::page_title');
   $translator->trans('WexampleSymfonyDesignSystemBundle.assets.pages.demo.index::page_title');

2. Domain Stack: You can push domains onto a stack for context-aware translations:

   $translator->setDomain('page', 'app.pages.home');
   $translator->trans('@page::title'); // Will use 'app.pages.home' as the domain

Console Commands

The package provides several useful console commands to help with translation management:

# Show all translations for 'en' locale
php bin/console translations:catalogue en

# Show translations for 'en' locale in the 'messages' domain
php bin/console translations:catalogue en --domain=messages

php bin/console translations:locales

# Basic usage
php bin/console translations:trans en "app.welcome"

# With domain and parameters
php bin/console translations:trans en "app.greeting" --domain=messages --parameters='{"name":"John"}'

Testing

phpunit