Symfony Translation Component

https://github.com/symfony/translation
Admin
The Symfony Translation component provides tools to internationalize your application.
Tokens:101,988
Snippets:709
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install symfony/translation with Composer

Source: https://github.com/symfony/translation/blob/8.2/README.md

Install the Translation component using Composer.

```bash
composer require symfony/translation
```

--------------------------------

### Set and get catalogue metadata example

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/MessageCatalogue.md

Example of setting and getting catalogue metadata. After setCatalogueMetadata, getCatalogueMetadata returns the stored value, here ['version' => '2.0'].

```php
$catalogue->setCatalogueMetadata('product', ['version' => '2.0'], 'messages');
$catalogue->getCatalogueMetadata('product', 'messages'); // ['version' => '2.0']
```

--------------------------------

### trans usage example

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/PseudoLocalizationTranslator.md

Shows how to use the trans method to get a pseudo-localized string.

```php
$pseudo = new PseudoLocalizationTranslator($translator);
echo $pseudo->trans('Hello World!'); // something like "[Ĥéļļö Ŵöŕļð¡]"
```

--------------------------------

### ChainExtractor usage example

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Extractors.md

Shows how to instantiate ChainExtractor, add extractors for PHP and Twig formats, set a prefix, and extract messages from a directory. The example uses extractors from other packages.

```php
use Symfony\Component\Translation\Extractor\ChainExtractor;
use Symfony\Component\Translation\MessageCatalogue;

$chain = new ChainExtractor();
$chain->addExtractor('php', $phpAstExtractor);
$chain->addExtractor('twig', $twigExtractor); // from another package

$catalogue = new MessageCatalogue('en');
$chain->setPrefix('__');
$chain->extract(__DIR__.'/src', $catalogue);
```

--------------------------------

### Using fallback catalogues

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/MessageCatalogue.md

Example of setting up a fallback catalogue and checking for message existence.

```php
$en = new MessageCatalogue('en', ['messages' => ['Hello' => 'Hello']]);
$fr = new MessageCatalogue('fr', ['messages' => ['Hello' => 'Bonjour']]);
$fr->addFallbackCatalogue($en);

$fr->has('Hello');      // true (defined)
$fr->has('Something');  // false (not in fallback either)
```

--------------------------------

### runWithLocale usage example

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LocaleSwitcher.md

Example usage of runWithLocale: switches to 'de', translates 'Hello', and restores the original locale after the callback.

```php
$result = $switcher->runWithLocale('de', function (string $locale) use ($translator) {
    return $translator->trans('Hello'); // translated with de
});
// locale is back to the original after this line
```

--------------------------------

### Instantiate LocaleSwitcher

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LocaleSwitcher.md

Example of instantiating LocaleSwitcher with an initial locale 'en' and a list of locale-aware services.

```php
use Symfony\Component\Translation\LocaleSwitcher;

$switcher = new LocaleSwitcher('en', [$translator, $validator, $otherLocaleAware]);
```

--------------------------------

### Instantiating a MessageCatalogue

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/MessageCatalogue.md

Example of creating a new MessageCatalogue instance with messages classified by domain.

```php
use Symfony\Component\Translation\MessageCatalogue;

$catalogue = new MessageCatalogue('fr', [
    'messages'   => ['Hello' => 'Bonjour'],
    'validators' => ['This value is invalid.' => 'Cette valeur est invalide.'],
]);
```

--------------------------------

### Using TranslatableMessage

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/TranslatableMessage.md

Example of creating a TranslatableMessage with parameters and domain, then translating it with a specific locale.

```php
use Symfony\Component\Translation\TranslatableMessage;

$msg = new TranslatableMessage('order.summary', ['%count%' => 3], 'orders');
echo $msg->trans($translator, 'fr'); // translated, e.g. "3 articles"
```

--------------------------------

### Configure framework.translator with fallbacks, pseudo-localization, providers, and globals

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/configuration.md

Example configuration for the framework.translator node, showing fallbacks, logging, pseudo-localization, providers, and globals. The globals section demonstrates both the scalar shorthand (app_name) and the message variant (legal_notice) with an optional domain.

```yaml
framework:
    translator:
        fallbacks: [en]
        logging: true
        pseudo_localization:
            enabled: true
            brackets: true
            expansion_factor: 2.0
        providers:
            lokalise:
                dsn: 'lokalise://%env(LOKALISE_TOKEN)%@default'
                domains: [messages, validators]
                locales: [en, fr]
        globals:
            app_name: 'Acme'            # scalar → injected as %app_name%
            legal_notice:               # message variant
                message: 'legal.notice'
                domain: legal
```

--------------------------------

### Using the t() helper

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/TranslatableMessage.md

Example of using the t() helper to create TranslatableMessage objects and translate them.

```php
$button = t('Save');                       // TranslatableMessage('Save')
$thanks = t('Thanks, %name%!', ['%name%' => $user->getName()]);
echo $button->trans($translator);
```

--------------------------------

### Instantiate Translator with cacheDir and debug

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Translator.md

Example of instantiating the Translator with a French locale, a cache directory, and debug mode enabled. The cacheDir and debug parameters are optional; debug mode revalidates cached files against resource freshness.

```php
use Symfony\Component\Translation\Translator;

$translator = new Translator('fr_FR', cacheDir: __DIR__.'/var/translations', debug: true);
```

--------------------------------

### Using StaticMessage

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/TranslatableMessage.md

Example of using StaticMessage to return a fixed string regardless of translator or locale.

```php
use Symfony\Component\Translation\StaticMessage;

$static = new StaticMessage('(c) 2025 Acme');
echo $static->trans($anyTranslator); // "(c) 2025 Acme"
```

--------------------------------

### Using TargetOperation with MessageCatalogue

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/CatalogueOperations.md

Shows how to use TargetOperation with two MessageCatalogue instances. The example creates a current and remote catalogue, then demonstrates getNewMessages, getObsoleteMessages, and getResult. The comments show the expected outputs.

```php
use Symfony\Component\Translation\Catalogue\TargetOperation;
use Symfony\Component\Translation\MessageCatalogue;

$current = new MessageCatalogue('en', ['messages' => ['a' => 'A', 'gone' => 'G']]);
$remote  = new MessageCatalogue('en', ['messages' => ['a' => 'A', 'b' => 'B']]);

$op = new TargetOperation($current, $remote);
$op->getNewMessages('messages');        // ['b' => 'B']
$op->getObsoleteMessages('messages');   // ['gone' => 'G']
$op->getResult();                       // messages: a, b
```

--------------------------------

### Using LocaleFallbackProvider with computeFallbackLocales

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LocaleFallbackProvider.md

Example usage of LocaleFallbackProvider. Creates a provider with 'en' as a fallback and computes fallbacks for 'fr_FR', which returns ICU parents for 'fr_FR' plus 'en'.

```php
use Symfony\Component\Translation\LocaleFallbackProvider;

$provider = new LocaleFallbackProvider(['en']);
$provider->computeFallbackLocales('fr_FR'); // ICU parents for fr_FR + 'en'
```

--------------------------------

### has, defines, and get methods

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/MessageCatalogue.md

Methods to check for existence or retrieve translations, with varying behavior regarding fallback chains.

```php
public function has(string $id, string $domain = 'messages'): bool
public function defines(string $id, string $domain = 'messages'): bool
public function get(string $id, string $domain = 'messages'): string
```

--------------------------------

### ArrayConverter::expandToTree usage example

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Util.md

Example of using ArrayConverter::expandToTree to convert a flat array with dotted keys into a nested tree. The resulting tree groups keys by their first segment.

```php
use Symfony\Component\Translation\Util\ArrayConverter;

$tree = ArrayConverter::expandToTree(['messages.greeting' => 'Hello', 'messages.farewell' => 'Bye']);
// ['messages' => ['greeting' => 'Hello', 'farewell' => 'Bye']]
```

--------------------------------

### MessageFormatter::format usage example

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Formatters.md

Example usage of MessageFormatter::format with plural selection. The output is 'There are 5 apples' for the given count.

```php
use Symfony\Component\Translation\Formatter\MessageFormatter;

$formatter = new MessageFormatter();
echo $formatter->format('There is one apple|There are %count% apples', 'en', ['%count%' => 5]);
// "There are 5 apples"
```

--------------------------------

### Using TranslationWriter with PoFileDumper

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/ReaderAndWriter.md

Example of using TranslationWriter to write a catalogue to a PO file. The writer creates the target directory if needed and invokes the dumper with the given options.

```php
use Symfony\Component\Translation\Writer\TranslationWriter;
use Symfony\Component\Translation\Dumper\PoFileDumper;
use Symfony\Component\Translation\MessageCatalogue;

$writer = new TranslationWriter();
$writer->addDumper('po', new PoFileDumper());

$catalogue = new MessageCatalogue('fr', ['messages' => ['Hello' => 'Bonjour']]);
$writer->write($catalogue, 'po', ['path' => __DIR__.'/var/translations']);
// writes var/translations/messages.fr.po
```

--------------------------------

### addLoader method signature and usage

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Translator.md

Registers a loader under a format name (e.g. 'array', 'xlf'). The name is referenced later by addResource(). The example shows registering an ArrayLoader for the 'array' format.

```php
public function addLoader(string $format, LoaderInterface $loader): void
```

```php
$translator->addLoader('array', new ArrayLoader());
```

--------------------------------

### getCatalogue usage with exception handling

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/PseudoLocalizationTranslator.md

Example of calling getCatalogue and catching the LogicException when the wrapped translator does not implement TranslatorBagInterface.

```php
try {
    $catalogue = $pseudo->getCatalogue('en');
} catch (\Symfony\Component\Translation\Exception\LogicException $e) {
    // wrapped translator does not implement TranslatorBagInterface
}
```

--------------------------------

### ArrayLoader usage example

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Loaders.md

Example of using ArrayLoader to load a PHP array into a MessageCatalogue. Nested keys are flattened with dots, so 'nested.deep' retrieves the value.

```php
use Symfony\Component\Translation\Loader\ArrayLoader;

$loader = new ArrayLoader();
$catalogue = $loader->load([
    'Hello' => 'Bonjour',
    'nested' => ['deep' => 'value'],
], 'fr');
echo $catalogue->get('nested.deep'); // "value"
```

--------------------------------

### Catching component exceptions with ExceptionInterface

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/errors.md

Example of catching any component exception by using the ExceptionInterface marker. The try block attempts to add a resource with a missing file, and the catch block handles any component exception.

```php
use Symfony\Component\Translation\Exception\ExceptionInterface;

try {
    $translator->addResource('xlf', '/missing.xlf', 'fr');
} catch (ExceptionInterface $e) {
    // NotFoundResourceException, InvalidResourceException, RuntimeExceptions, ...
}
```

--------------------------------

### setConfigCacheFactory

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Translator.md

Installs a custom cache factory for catalogue caching. This method allows overriding the default cache factory behavior when a cache directory is configured.

```APIDOC
## setConfigCacheFactory

### Description
Installs a custom cache factory (from `symfony/config`) used when `$cacheDir` is set. The default is `new ConfigCacheFactory($this->debug)`.

### Method
`setConfigCacheFactory(ConfigCacheFactoryInterface $configCacheFactory): void`

### Parameters
- `$configCacheFactory` (ConfigCacheFactoryInterface) - Required - Factory producing the ConfigCacheInterface for each catalogue path

### Returns
`void`
```

--------------------------------

### UnsupportedSchemeException class definition

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/errors.md

Exception thrown when no factory supports a DSN scheme. Two message variants: provider not installed (for schemes in SCHEME_TO_PACKAGE_MAP) or unsupported scheme. Triggered by TranslationProviderCollectionFactory::fromDsnObject() and NullProviderFactory::create().

```php
class UnsupportedSchemeException extends LogicException
{
    public function __construct(Dsn $dsn, ?string $name = null, array $supported = [])
}
```

--------------------------------

### Load a CSV translation catalogue with CsvFileLoader

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Loaders.md

Creates a CSV file loader, overrides the default delimiter and enclosure with named arguments, and loads a French CSV catalogue. The loader expects rows with exactly two columns that do not start with '#'.

```php
use Symfony\Component\Translation\Loader\CsvFileLoader;

$loader = new CsvFileLoader();
$loader->setCsvControl(delimiter: ',', enclosure: '"');
$catalogue = $loader->load(__DIR__.'/messages.fr.csv', 'fr');
```

--------------------------------

### setConfigCacheFactory method signature

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Translator.md

Installs a custom cache factory from symfony/config used when $cacheDir is set. The default is new ConfigCacheFactory($this->debug).

```php
public function setConfigCacheFactory(ConfigCacheFactoryInterface $configCacheFactory): void
```

--------------------------------

### Call trans with exception handling

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LoggingTranslator.md

Example of calling trans with parameters and catching exceptions. The wrapped translator may throw for invalid locale or bad ICU messages.

```php
try {
    $html = $logging->trans('product.count', ['%count%' => $count]);
} catch (\Throwable $e) {
    // the wrapped translator decides what may throw (e.g. invalid locale, bad ICU message)
    error_log($e->getMessage());
}
```

--------------------------------

### TranslatorBag constructor

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/TranslatorBag.md

Constructor for TranslatorBag. Takes no arguments and starts with an empty bag; catalogues are created lazily by getCatalogue().

```php
public function __construct()
```

--------------------------------

### YamlFileDumper: formatCatalogue with as_tree option

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Dumpers.md

Use this snippet to dump a MessageCatalogue to YAML format using the YamlFileDumper. The example creates a French catalogue with a single message and formats it with the 'as_tree' option, which expands the output into a tree structure. Requires symfony/yaml; otherwise a LogicException is thrown.

```php
use Symfony\Component\Translation\Dumper\YamlFileDumper;
use Symfony\Component\Translation\MessageCatalogue;

$dumper = new YamlFileDumper();
$catalogue = new MessageCatalogue('fr', ['messages' => ['Hello' => 'Bonjour']]);
$yaml = $dumper->formatCatalogue($catalogue, 'messages', ['as_tree' => true]);
```

--------------------------------

### Using TranslationReader with YamlFileLoader

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/ReaderAndWriter.md

Example of using TranslationReader to load YAML translation files for the 'fr' locale from a directory. The reader merges all matching files into the provided catalogue.

```php
use Symfony\Component\Translation\Reader\TranslationReader;
use Symfony\Component\Translation\Loader\YamlFileLoader;
use Symfony\Component\Translation\MessageCatalogue;

$reader = new TranslationReader();
$reader->addLoader('yml', new YamlFileLoader());

$catalogue = new MessageCatalogue('fr');
$reader->read(__DIR__.'/translations', $catalogue); // loads messages.fr.yml, validators.fr.yml, ...
```

--------------------------------

### Using LocaleFallbackProvider::validateLocale

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LocaleFallbackProvider.md

Example usage of validateLocale. Attempts to validate 'fr FR' which contains a space, causing an InvalidArgumentException to be thrown and caught.

```php
use Symfony\Component\Translation\LocaleFallbackProvider;
use Symfony\Component\Translation\Exception\InvalidArgumentException;

try {
    LocaleFallbackProvider::validateLocale('fr FR');
} catch (InvalidArgumentException $e) {
    // invalid characters (space) are rejected
}
```

--------------------------------

### Using DataCollectorTranslator to collect missing messages

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/DataCollectorTranslator.md

Example usage: create a DataCollectorTranslator, translate a missing message, iterate over collected messages to detect missing ones, and reset the collector.

```php
use Symfony\Component\Translation\DataCollectorTranslator;

$collector = new DataCollectorTranslator($translator);
$collector->trans('missing.message');

foreach ($collector->getCollectedMessages() as $m) {
    if (DataCollectorTranslator::MESSAGE_MISSING === $m['state']) {
        // feed a missing-translations report
    }
}
$collector->reset();
```

--------------------------------

### Using diff() and intersect() with TranslatorBag

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/TranslatorBag.md

Example usage of diff() and intersect() on TranslatorBag instances. Creates two bags with English catalogues, then computes the diff (new messages) and intersect (obsolete messages). The comments indicate expected results.

```php
use Symfony\Component\Translation\MessageCatalogue;
use Symfony\Component\Translation\TranslatorBag;

$local = new TranslatorBag();
$local->addCatalogue(new MessageCatalogue('en', ['messages' => ['a' => 'A', 'b' => 'B']]));

$remote = new TranslatorBag();
$remote->addCatalogue(new MessageCatalogue('en', ['messages' => ['a' => 'A']]));

$toCreate = $local->diff($remote);      // contains 'b' => 'B'
$toDelete = $local->intersect($remote); // empty (nothing of $local is missing from $remote)
```

--------------------------------

### XliffUtils validation usage example

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Util.md

Example of using XliffUtils::validateSchema and getErrorsAsString to validate an XLIFF document and throw a RuntimeException on errors.

```php
use Symfony\Component\Translation\Util\XliffUtils;

$dom = new \DOMDocument();
$dom->loadXML($xliffXml);

$errors = XliffUtils::validateSchema($dom);
if ($errors) {
    throw new \RuntimeException(XliffUtils::getErrorsAsString($errors)); // consumer-side handling
}
```

--------------------------------

### IntlFormatter::formatIntl usage example

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Formatters.md

Example usage of IntlFormatter::formatIntl with ICU plural rules. The parameter '%count%' is normalized to 'count' and the output is '2 items'.

```php
use Symfony\Component\Translation\Formatter\IntlFormatter;

$icu = new IntlFormatter();
echo $icu->formatIntl('{count, plural, =0 {none} one {# item} other {# items}}', 'en', ['%count%' => 2]);
// "2 items"  (%count% normalized to count)
```

--------------------------------

### Instantiation with options

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/PseudoLocalizationTranslator.md

Creates a PseudoLocalizationTranslator with options enabling accents, expansion factor 2.0, brackets, HTML parsing, and localizable HTML attributes.

```php
use Symfony\Component\Translation\PseudoLocalizationTranslator;

$pseudo = new PseudoLocalizationTranslator($translator, [
    'accents' => true,
    'expansion_factor' => 2.0,
    'brackets' => true,
    'parse_html' => true,
    'localizable_html_attributes' => ['title'],
]);
```

--------------------------------

### Using Dsn to parse a provider DSN

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Providers.md

Shows how to instantiate a Dsn object with a Lokalise DSN and retrieve the 'project_id' option using getOption and getRequiredOption. The getRequiredOption method throws MissingRequiredOptionException if the key is missing or whitespace-only.

```php
use Symfony\Component\Translation\Provider\Dsn;

$dsn = new Dsn('lokalise://TOKEN@default?project_id=123');
$dsn->getOption('project_id');       // "123"
$dsn->getRequiredOption('project_id'); // "123"
```

--------------------------------

### LoggingTranslator::getFallbackLocales

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LoggingTranslator.md

Gets the fallback locales from the wrapped translator.

```APIDOC
## getFallbackLocales

### Description
Returns the wrapped translator's fallback locales when it is a Translator or exposes the method; otherwise returns an empty array.

### Method
getFallbackLocales

### Returns
array - The fallback locales
```

--------------------------------

### LoggingTranslator::getCatalogues

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LoggingTranslator.md

Gets all message catalogues from the wrapped translator.

```APIDOC
## getCatalogues

### Description
Returns all message catalogues, forwarded to the wrapped translator.

### Method
getCatalogues

### Returns
array - All message catalogues
```

--------------------------------

### LoggingTranslator::getCatalogue

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LoggingTranslator.md

Gets the message catalogue for a given locale.

```APIDOC
## getCatalogue

### Description
Returns the message catalogue for the given locale, forwarded to the wrapped translator.

### Method
getCatalogue

### Parameters
- `$locale` (?string) - Optional - The locale to get the catalogue for

### Returns
MessageCatalogueInterface - The message catalogue
```

--------------------------------

### LoggingTranslator::getLocale

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LoggingTranslator.md

Gets the current locale from the wrapped translator.

```APIDOC
## getLocale

### Description
Returns the current locale from the wrapped translator.

### Method
getLocale

### Returns
string - The current locale
```

--------------------------------

### getResources and addResource methods

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/MessageCatalogue.md

Manages resource bookkeeping for cache-freshness metadata.

```php
public function getResources(): array
public function addResource(ResourceInterface $resource): void
```

--------------------------------

### getLocale

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/PseudoLocalizationTranslator.md

Delegates to the wrapped translator to get the current locale.

```APIDOC
## getLocale

### Description
Returns the current locale from the wrapped translator.

### Signature
```php
public function getLocale(): string
```

### Returns
- **string** - The current locale.
```

--------------------------------

### QtFileLoader::load

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Loaders.md

Loads a Qt translation file into a message catalogue.

```APIDOC
## QtFileLoader::load

### Description
Loads a Qt `.ts` XML file and returns a message catalogue. Requires symfony/config (`XmlUtils`); throws `RuntimeException` if missing. Selects the `<context>` whose `<name>` equals the domain. Throws `InvalidResourceException` for non-local, missing, or unparseable files.

### Method
`load`

### Signature
`public function load(mixed $resource, string $locale, string $domain = 'messages'): MessageCatalogueInterface`

### Parameters
- **resource** (mixed) - Required - The path to the `.ts` file.
- **locale** (string) - Required - The locale for the catalogue.
- **domain** (string) - Optional - The message domain. Defaults to `'messages'`.

### Return Value
`MessageCatalogueInterface` - The loaded message catalogue.

### Exceptions
- `RuntimeException` - Thrown when symfony/config is missing.
- `InvalidResourceException` - Thrown for non-local, missing, or unparseable files.
```

--------------------------------

### Constructor definition

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/MessageCatalogue.md

The constructor initializes the catalogue with a locale and an optional array of messages.

```php
public function __construct(
    private string $locale,
    private array $messages = [],
)
```

--------------------------------

### Translate a message with Translator and ArrayLoader

Source: https://github.com/symfony/translation/blob/8.2/README.md

Create a Translator instance for French (fr_FR), register an ArrayLoader, add a translation resource mapping 'Hello World!' to 'Bonjour !', and translate the message. The output is 'Bonjour !'.

```php
use Symfony\Component\Translation\Translator;
use Symfony\Component\Translation\Loader\ArrayLoader;

$translator = new Translator('fr_FR');
$translator->addLoader('array', new ArrayLoader());
$translator->addResource('array', [
    'Hello World!' => 'Bonjour !',
], 'fr_FR');

echo $translator->trans('Hello World!'); // outputs « Bonjour ! »
```

--------------------------------

### Constructor

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Translator.md

Creates a new Translator instance with the specified locale and optional configuration for formatter, caching, and debug mode.

```APIDOC
## Constructor

### Description
Creates a new Translator instance. The locale must be valid according to LocaleFallbackProvider::validateLocale(), otherwise an InvalidArgumentException is thrown. The formatter is used for message formatting; if it implements IntlFormatterInterface, ICU domains are supported. When cacheDir is set, compiled catalogues are cached as PHP files. In debug mode, cached files are revalidated against resource freshness. The cacheVary array is serialized and hashed into the cache filename for external cache invalidation.

### Method
Constructor

### Endpoint
`new Translator(string $locale, ?MessageFormatterInterface $formatter = null, ?string $cacheDir = null, bool $debug = false, array $cacheVary = [])`

### Parameters
- **$locale** (string) - Required - Initial locale; must pass `LocaleFallbackProvider::validateLocale()` or `InvalidArgumentException` is thrown.
- **$formatter** (?MessageFormatterInterface) - Optional - Default: `null` (a `MessageFormatter` is created) - Formatter used for `trans()`; if it also implements `IntlFormatterInterface`, ICU domains are supported.
- **$cacheDir** (?string) - Optional - Default: `null` - When set, compiled catalogues are written to this directory as PHP files and reused across requests.
- **$debug** (bool) - Optional - Default: `false` - Passed to the default `ConfigCacheFactory`; in debug mode cached files are revalidated against resource freshness.
- **$cacheVary** (array) - Optional - Default: `[]` - Extra data serialized (via `hash('xxh128', serialize($cacheVary))`) into the cached catalogue filename, so cache invalidation can be controlled externally.

### Request Example
```php
use Symfony\Component\Translation\Translator;

$translator = new Translator('fr_FR', cacheDir: __DIR__.'/var/translations', debug: true);
```

### Response
No return value (constructor).
```

--------------------------------

### all method

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/MessageCatalogue.md

Returns all messages for a specific domain or all domains if null is provided.

```php
public function all(?string $domain = null): array
```

--------------------------------

### Run lint:translations for a locale

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/ConsoleCommands.md

Lints all translation catalogues for the French locale. The command renders every message through trans() and reports any that raise \Throwable, grouped by domain.

```bash
php bin/console lint:translations --locale=fr
```

--------------------------------

### Create LoggingTranslator instance

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LoggingTranslator.md

Instantiate LoggingTranslator wrapping a Translator with locale 'en' and a PSR-3 logger. The wrapped translator must implement all required interfaces.

```php
use Symfony\Component\Translation\LoggingTranslator;
use Symfony\Component\Translation\Translator;

$logging = new LoggingTranslator(new Translator('en'), $psrLogger);
```

--------------------------------

### Handling InvalidArgumentException from TranslationWriter

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/ReaderAndWriter.md

Error handling example for TranslationWriter::write() when the format is not registered. Catches InvalidArgumentException thrown for unregistered formats.

```php
try {
    $writer->write($catalogue, 'xliff', ['path' => $target]);
} catch (\Symfony\Component\Translation\Exception\InvalidArgumentException $e) {
    // format 'xliff' never registered via addDumper()
}
```

--------------------------------

### LocaleFallbackProvider::__construct

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LocaleFallbackProvider.md

Constructor for LocaleFallbackProvider that accepts an optional array of fallback locales.

```APIDOC
## Constructor

```php
public function __construct(
    private array $localeFallbacks = [],
)
```

### Parameters
- `$localeFallbacks` (string[]) - Optional - Fallback locales appended *after* the ICU-derived ones; each is validated

### Throws
- `InvalidArgumentException` - Any entry contains invalid locale characters

```

--------------------------------

### MoFileLoader::load

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Loaders.md

Loads a binary GNU gettext MO file into a message catalogue.

```APIDOC
## MoFileLoader::load

### Description
Loads a GNU gettext MO (binary) file and returns a message catalogue. Uses constants `MO_LITTLE_ENDIAN_MAGIC = 0x950412DE`, `MO_BIG_ENDIAN_MAGIC = 0xDE120495`, and `MO_HEADER_SIZE = 28`.

### Method
`load`

### Signature
`public function load(mixed $resource, string $locale, string $domain = 'messages'): MessageCatalogueInterface`

### Parameters
- **resource** (mixed) - Required - The path to the MO file.
- **locale** (string) - Required - The locale for the catalogue.
- **domain** (string) - Optional - The message domain. Defaults to `'messages'`.

### Return Value
`MessageCatalogueInterface` - The loaded message catalogue.
```

--------------------------------

### Constructor

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/PseudoLocalizationTranslator.md

Constructor for PseudoLocalizationTranslator with options for accents, expansion, brackets, and HTML parsing.

```APIDOC
## Constructor

### Description
Creates a new PseudoLocalizationTranslator instance that wraps a translator and applies pseudo-localization transformations to its output.

### Signature
```php
public function __construct(
    private TranslatorInterface $translator,
    array $options = [],
)
```

### Parameters
- **$translator** (TranslatorInterface) - Required - The wrapped translator providing the real translation.
- **$options** (array) - Optional - Configuration options. See options table below.

### Options
- **accents** (bool) - Default: `true` - Replace ASCII characters with accented or visually-similar characters (e.g., `"foo"` → `"ƒöö"`).
- **expansion_factor** (float) - Default: `1.0` - Expand the visible text by this factor with spaces and `~` tildes; must be `>= 1.0` or `\InvalidArgumentException` is thrown.
- **brackets** (bool) - Default: `true` - Wrap the translated string in `[` `]`.
- **parse_html** (bool) - Default: `false` - Parse the translation as HTML so tags are preserved and the visible length is computed correctly. Unclosed tags are silently closed by the parser (e.g., `"foo <div>bar"` → `"foo <div>bar</div>"`). Automatically disabled when `accents` is `false` **and** `expansion_factor` is `1.0`.
- **localizable_html_attributes** (string[]) - Default: `[]` - HTML attributes whose values may be altered (only meaningful with `parse_html: true`).

### Example
```php
use Symfony\Component\Translation\PseudoLocalizationTranslator;

$pseudo = new PseudoLocalizationTranslator($translator, [
    'accents' => true,
    'expansion_factor' => 2.0,
    'brackets' => true,
    'parse_html' => true,
    'localizable_html_attributes' => ['title'],
]);
```

### Throws
- **\InvalidArgumentException** - If `$options['expansion_factor'] < 1.0`.
```

--------------------------------

### PhpAstExtractor::__construct

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Extractors.md

Creates a new PhpAstExtractor instance with the given visitors and optional prefix.

```APIDOC
## PhpAstExtractor::__construct

### Description
Creates a new PhpAstExtractor instance with the given visitors and optional prefix.

### Method
__construct

### Signature
public function __construct(iterable $visitors, string $prefix = '')

### Parameters
- **$visitors** (iterable<AbstractVisitor&NodeVisitor>) - Required - Visitors detecting translation call sites; each is initialized per file.
- **$prefix** (string) - Optional - Prefix prepended to extracted message values. Defaults to ''.

### Return
void
```

--------------------------------

### Constructor signature

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/PseudoLocalizationTranslator.md

The constructor accepts a TranslatorInterface and an optional options array. The options control accent replacement, expansion factor, brackets, and HTML parsing.

```php
public function __construct(
    private TranslatorInterface $translator,
    array $options = [],
)
```

--------------------------------

### LocaleSwitcher::runWithLocale

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LocaleSwitcher.md

Runs a callback with a temporary locale and restores the original locale afterwards.

```APIDOC
## runWithLocale

### Description
Switches to the given locale, invokes the callback, and always switches back to the original locale.

### Method
`runWithLocale(string $locale, callable $callback): mixed`

### Parameters
- `$locale` (string) - Required - The locale to switch to.
- `$callback` (callable(string $locale): T) - Required - The callback to invoke with the new locale.

### Returns
- `mixed` - The return value of the callback.

### Example

```php
$result = $switcher->runWithLocale('de', function (string $locale) use ($translator) {
    return $translator->trans('Hello'); // translated with de
});
// locale is back to the original after this line
```
```

--------------------------------

### StaticMessage::__construct

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/TranslatableMessage.md

Creates a new StaticMessage instance with a fixed string.

```APIDOC
## [CONSTRUCTOR] StaticMessage::__construct

### Description
Creates a new StaticMessage instance with a fixed string.

### Method
Constructor

### Endpoint
`public function __construct(private string $message)`

### Parameters
#### Constructor Parameters
- **$message** (string) - Required - The fixed string

### Request Example
```php
$static = new StaticMessage('(c) 2025 Acme');
```

### Response
#### Success Response
No return value (constructor).

#### Response Example
N/A
```

--------------------------------

### AbstractOperation constructor

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/CatalogueOperations.md

Constructor for AbstractOperation. Requires two catalogues of the same locale; throws LogicException otherwise. The source is the left operand, target the right.

```php
public function __construct(
    protected MessageCatalogueInterface $source,
    protected MessageCatalogueInterface $target,
)
```

--------------------------------

### Translator usage with ArrayLoader and ICU pluralization

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Translator.md

Example of using Translator with an ArrayLoader and a French catalogue. Shows basic interpolation with %name% and ICU pluralization using the 'messages+intl-icu' domain. The output comments show the expected translations.

```php
use Symfony\Component\Translation\Translator;
use Symfony\Component\Translation\Loader\ArrayLoader;

$translator = new Translator('fr_FR');
$translator->addLoader('array', new ArrayLoader());
$translator->addResource('array', [
    'Hello %name%!' => 'Bonjour %name% !',
    'order.count'   => '{count, plural, =0 {aucune commande} one {# commande} other {# commandes}}',
], 'fr_FR');

echo $translator->trans('Hello %name%!', ['%name%' => 'Ada']);      // "Bonjour Ada !"
echo $translator->trans('order.count', ['%count%' => 2], 'messages+intl-icu'); // ICU path
```

--------------------------------

### getResult method

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/CatalogueOperations.md

Processes every domain and returns the result catalogue. The result can outlive the operation and holds the same messages as the 'all' batch.

```php
public function getResult(): MessageCatalogueInterface
```

--------------------------------

### XliffFileLoader

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Loaders.md

Documentation for the XliffFileLoader class, including its constructor and load method.

```APIDOC
## XliffFileLoader::__construct

### Description
Initializes the XLIFF file loader with an optional list of directories for which schema validation is skipped.

### Method
Constructor

### Signature
`public function __construct(array $skipValidationDirs = [])`

### Parameters
- **$skipValidationDirs** (array) - Optional - List of directory prefixes. Resources under these directories will skip XLIFF schema validation.
```

```APIDOC
## XliffFileLoader::load

### Description
Loads an XLIFF resource (file path or XML string) and returns a MessageCatalogue for the given locale and domain.

### Method
load

### Signature
`public function load(mixed $resource, string $locale, string $domain = 'messages'): MessageCatalogue`

### Parameters
- **$resource** (mixed) - Required - File path or XML string. Auto-detected via `isXmlString()`.
- **$locale** (string) - Required - The locale for the catalogue.
- **$domain** (string) - Optional - The message domain (default: 'messages').

### Throws
- `InvalidResourceException` - If the file is not found, not readable, or XML/schema validation fails. The message includes `XliffUtils::getErrorsAsString()` output.

### Behaviour
- Accepts a file path or an XML string.
- Validates against XLIFF 1.2 subset schema, 1.2 transitional schema, or 2.0/2.2 XSDs depending on detected version, unless the resource is under one of `$skipValidationDirs`.
- XLIFF 1.2: extracts `file → body → trans-unit` (source/target, resname, notes → metadata, group handling).
- XLIFF 2.0/2.1/2.2: extracts `unit → segment`/`ignorable`, plural support (`pluralGrouping`, `select`/`selectAlternatives` in 2.1/2.2 via `parsePgsSwitch()`, ICU message reconstruction with `buildIcuMessage()`), `note` elements → metadata, `original`/`source` bookkeeping.
- Metadata is attached with `setMetadata()`; catalogue-level data with `setCatalogueMetadata()`.
```

--------------------------------

### getDomains method

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/CatalogueOperations.md

Returns the union of domains from both catalogues, including +intl-icu variants when ICU messages exist. Ordering matters because the operation iterates this list multiple times.

```php
public function getDomains(): array
```

--------------------------------

### OperationInterface methods

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/CatalogueOperations.md

Defines the contract for binary catalogue operations. Implementations must provide domain listing, message batches (all, new, obsolete), and the result catalogue.

```php
interface OperationInterface
{
    public function getDomains(): array;
    public function getMessages(string $domain): array;
    public function getNewMessages(string $domain): array;
    public function getObsoleteMessages(string $domain): array;
    public function getResult(): MessageCatalogueInterface;
}
```

--------------------------------

### TranslationProviderCollection class definition

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Providers.md

Defines a registry for named translation providers. The constructor accepts an iterable of providers, and the class provides methods to check existence, retrieve a provider, and list keys. The get() method throws an InvalidArgumentException with the message 'Provider "%s" not found. Available: "%s".' for unknown names.

```php
final class TranslationProviderCollection
{
    /** @param array<string, ProviderInterface> $providers */
    public function __construct(iterable $providers)

    public function __toString(): string   // '[name1,name2]'
    public function has(string $name): bool
    public function get(string $name): ProviderInterface
    public function keys(): array
}
```

--------------------------------

### ConstraintVisitor: Configure constraint classes for extraction

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Extractors.md

Shows how to instantiate ConstraintVisitor with a list of constraint class names to detect. The visitor extracts validator 'message' options from 'new *Constraint([...])' expressions and attributes whose class name contains one of the given class names. Messages are added to the 'validators' domain.

```php
use Symfony\Component\Translation\Extractor\Visitor\ConstraintVisitor;

$visitor = new ConstraintVisitor(['NotBlank', 'Length']); // detect these constraint classes
```

--------------------------------

### AbstractProviderFactory base class

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Providers.md

Base factory that implements supports() by checking the DSN scheme against getSupportedSchemes(). getUser() and getPassword() throw IncompleteDsnException with messages 'User is not set.' and 'Password is not set.' when the corresponding DSN part is absent.

```php
abstract class AbstractProviderFactory implements ProviderFactoryInterface
{
    public function supports(Dsn $dsn): bool

    abstract protected function getSupportedSchemes(): array;

    protected function getUser(Dsn $dsn): string
    protected function getPassword(Dsn $dsn): string
}
```

--------------------------------

### NullProvider and NullProviderFactory

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Providers.md

NullProvider is a no-op provider that returns an empty bag and does nothing on write/delete. NullProviderFactory creates it for the 'null' scheme and throws UnsupportedSchemeException otherwise.

```php
class NullProvider implements ProviderInterface
{
    public function __toString(): string            // 'null'
    public function write(TranslatorBagInterface $translatorBag, bool $override = false): void  // no-op
    public function read(array $domains, array $locales): TranslatorBag  // empty bag
    public function delete(TranslatorBagInterface $translatorBag): void  // no-op
}

final class NullProviderFactory extends AbstractProviderFactory
{
    public function create(Dsn $dsn): ProviderInterface
    protected function getSupportedSchemes(): array  // ['null']
}
```

--------------------------------

### runWithLocale docblock

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LocaleSwitcher.md

Docblock for runWithLocale, defining the generic template and callback signature.

```php
/**
 * @template T
 * @param callable(string $locale):T $callback
 * @return T
 */
```

--------------------------------

### PhpFileLoader::load

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Loaders.md

Loads a PHP file that returns an array of messages into a catalogue.

```APIDOC
## PhpFileLoader::load

### Description
Loads a PHP file that returns an array of messages. The file is `require`d and the result must be an array. Loaded files are cached statically and honour `opcache` invalidation when enabled.

### Method
`load`

### Signature
`public function load(mixed $resource, string $locale, string $domain = 'messages'): MessageCatalogueInterface`

### Parameters
- **resource** (mixed) - Required - The path to the PHP file.
- **locale** (string) - Required - The locale for the catalogue.
- **domain** (string) - Optional - The message domain. Defaults to `'messages'`.

### Return Value
`MessageCatalogueInterface` - The loaded message catalogue.
```

--------------------------------

### Catalogue metadata interface methods (CatalogueMetadataAwareInterface)

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/MessageCatalogue.md

Interface methods for catalogue-level metadata, applied to the catalogue/domain as a whole. The XLIFF loader/dumper maps <file>-level note/attr data here, and getCatalogueMetadata('', $domain) is consulted by Catalogue\AbstractOperation and MergeOperation/TargetOperation when merging.

```php
public function getCatalogueMetadata(string $key = '', string $domain = 'messages'): mixed
public function setCatalogueMetadata(string $key, mixed $value, string $domain = 'messages'): void
public function deleteCatalogueMetadata(string $key = '', string $domain = 'messages'): void
```

--------------------------------

### AbstractFileExtractor helpers

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Extractors.md

Base class for file-based extractors. extractFiles() routes iterable resources through canBeExtracted(), existing files to a single SplFileInfo, and directories to extractFromDirectory(). isFile() throws InvalidArgumentException with message 'The "%s" file does not exist.' for non-files.

```php
abstract class AbstractFileExtractor
{
    protected function extractFiles(string|iterable $resource): iterable
    protected function isFile(string $file): bool
    abstract protected function canBeExtracted(string $file): bool;
    abstract protected function extractFromDirectory(string|array $resource): iterable;
}
```

--------------------------------

### LocaleSwitcher constructor

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LocaleSwitcher.md

Constructor signature for LocaleSwitcher. Accepts the initial locale, an iterable of locale-aware services, and an optional RequestContext to keep the _locale parameter in sync.

```php
public function __construct(
    private string $locale,
    private iterable $localeAwareServices,
    private ?RequestContext $requestContext = null,
)
```

--------------------------------

### LocaleFallbackProvider constructor

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/LocaleFallbackProvider.md

Constructor for LocaleFallbackProvider. Accepts an optional array of fallback locales that are appended after ICU-derived ones. Each entry is validated; an InvalidArgumentException is thrown if any entry contains invalid locale characters.

```php
public function __construct(
    private array $localeFallbacks = [],
)
```

--------------------------------

### ExceptionInterface marker interface

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/errors.md

Marker interface implemented by all component exceptions. Catch this to handle any component error uniformly.

```php
interface ExceptionInterface extends \Throwable
{
}
```

--------------------------------

### PoFileLoader::load

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Loaders.md

Loads a GNU gettext PO file, parsing messages and metadata into a catalogue.

```APIDOC
## PoFileLoader::load

### Description
Loads a GNU gettext PO file and returns a message catalogue. Overrides the base `load()` method to parse `msgid`/`msgstr` (including plural variants via `|`), `msgctxt`, comments, flags, sources, and context. All collected metadata is attached to the catalogue via `setMetadata()`. Plural source/target pairs are handled; ICU domains (`+intl-icu`) treat `|` as an ordinary character.

### Method
`load`

### Signature
`public function load(mixed $resource, string $locale, string $domain = 'messages'): MessageCatalogueInterface`

### Parameters
- **resource** (mixed) - Required - The path to the PO file.
- **locale** (string) - Required - The locale for the catalogue.
- **domain** (string) - Optional - The message domain. Defaults to `'messages'`.

### Return Value
`MessageCatalogueInterface` - The loaded message catalogue with metadata.
```

--------------------------------

### TranslationProviderCollectionFactory class definition

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Providers.md

Defines a factory for creating translation provider collections. The constructor takes an iterable of provider factories and an array of enabled locales. fromConfig() expects a config array mapping names to DSN, locales, and domains, falling back to enabled locales for empty locale lists and wrapping each provider in a FilteringProvider. fromDsnObject() iterates factories and returns the first FilteringProvider whose factory supports the DSN, otherwise throws UnsupportedSchemeException.

```php
class TranslationProviderCollectionFactory
{
    /** @param iterable<mixed, ProviderFactoryInterface> $factories */
    public function __construct(
        private iterable $factories,
        private array $enabledLocales,
    )

    public function fromConfig(array $config): TranslationProviderCollection
    public function fromDsnObject(Dsn $dsn, array $locales, array $domains = []): ProviderInterface
}
```

--------------------------------

### LoaderInterface load() method

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/Loaders.md

Defines the contract for all loaders. The load() method must return a MessageCatalogue and may throw NotFoundResourceException or InvalidResourceException.

```php
interface LoaderInterface
{
    /**
     * @throws NotFoundResourceException when the resource cannot be found
     * @throws InvalidResourceException  when the resource cannot be loaded
     */
    public function load(mixed $resource, string $locale, string $domain = 'messages'): MessageCatalogue;
}
```

--------------------------------

### set method

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/MessageCatalogue.md

Sets a translation for a specific ID and domain, acting as an alias for add().

```php
public function set(string $id, string $translation, string $domain = 'messages'): void
```

--------------------------------

### Using IdentityTranslator to translate a message

Source: https://github.com/symfony/translation/blob/8.2/_autodocs/api-reference/IdentityTranslator.md

Shows how to instantiate IdentityTranslator and call trans() to return the message id unchanged, with placeholder interpolation.

```php
use Symfony\Component\Translation\IdentityTranslator;

$identity = new IdentityTranslator();
echo $identity->trans('Hello %name%!', ['%name%' => 'Ada']); // "Hello Ada!"
```
Tokens:
Raw