To translate a Symfony application, install and configure the Translation component, mark messages for translation, add locale-specific translation files, and select a locale for each user request. Symfony looks up each message in that locale’s catalog, uses configured fallbacks for missing entries, and returns the original message if no translation is available.
Set up Symfony Translation
For a Symfony application, install the component with Composer:
composer require symfony/translationThen configure a default locale and, if needed, the directory where your translation resources live. The Symfony guide covers configuration and the available resource formats in its Translations documentation. For standalone PHP projects, the symfony/translation repository demonstrates creating a translator, setting its locale, registering a loader, and adding a resource.
Create message IDs and translation files
A translation resource maps message IDs to translated text for a particular locale. Symfony supports formats including YAML, XLIFF/XML, and PHP arrays; the guide does not designate one format as best for every project. Choose one that fits your translators’ workflow and your application’s conventions, then use the matching loader and filename pattern.
#1 Best Overall
For each message, decide whether the ID should be the original wording, such as Symfony is great, or a semantic key, such as symfony.great. Readable wording can work well in shared bundles; semantic keys are often useful in multilingual applications because copy changes do not require changing the ID in every catalog.
Symfony’s documentation shows locale and domain in translation resource filenames. Follow the naming convention for the format and loader you use; for ICU MessageFormat files, use the distinct +intl-icu suffix described below.
Rank #2
Mark messages for translation and pass variables safely
Use the translator for messages that should be localized. When a message includes changing data, keep the message stable and pass the value separately rather than concatenating it into the ID. For example, use a message such as Hello %name%! and provide the name as a parameter to trans(). Symfony substitutes matching placeholders in the translated text.
Concatenating a value into a message before translation creates a different string for each value, which is unlikely to match a catalog entry. Placeholders let translators reposition the variable where the target language requires it.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsSelect and manage the user’s locale
Symfony uses the current locale to choose the translation catalog. A common way to set it is with the _locale route attribute. You can also configure a default locale and fallback locales; a fallback supplies entries missing from the selected locale. If the message is absent from both the selected catalog and available fallbacks, Symfony returns the original message.
The Symfony guide also describes storing locale on the request and managing it through a user’s session. Changing the locale with LocaleSwitcher affects the current request; it does not automatically carry over to a later request, such as one made after a redirect. Configure persistence separately if the choice should last across requests.
Rank #4
Choose ordinary placeholders or ICU MessageFormat
Ordinary Symfony placeholders are suitable for inserting values into a translated message. They do not, by themselves, select grammatical forms for plural counts or gender. For count-, gender-, and locale-sensitive variants, use ICU MessageFormat, which Symfony implements through PHP’s MessageFormatter.
ICU messages use brace-style placeholders such as {name}, rather than the ordinary %name% form. Store them in a resource whose filename uses the +intl-icu suffix, for example messages+intl-icu.en.yaml. See the PHP MessageFormatter documentation for the formatter’s role.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Check PHP intl requirements for your languages
Symfony’s current documentation says its internationalization polyfills allow translation features without PHP’s intl extension, but those polyfills support English translations only. For translation into other languages, install and enable PHP intl. Check the Symfony documentation for the release you use, since requirements can change between Symfony and PHP versions.
Find missing and unused translations
Run Symfony’s debug:translation command to inspect missing and unused messages. Treat its output as an audit aid rather than a complete inventory: extractors may miss messages outside templates unless they are represented with translatable objects or translator calls, and dynamic template expressions are not detected.
- Review reported missing messages and add them to the appropriate locale resource.
- Investigate unused entries before deleting them; extraction limitations may mean a message is used but not discovered.
- Ensure dynamic or non-template messages are represented in a way the extractor can recognize, or track them through your own translation workflow.
Choose an approach that fits your application
| Decision | Useful when | Trade-off |
|---|---|---|
| Readable message IDs | Shared bundles or catalogs where seeing source wording is helpful. | Changing source copy can also mean changing IDs. |
| Semantic keys | Multilingual applications where message identity should remain stable as wording changes. | Keys need consistent naming and may be less self-explanatory to translators. |
| YAML, XLIFF/XML, or PHP arrays | Choose according to translator workflow, tooling, and project conventions. | Symfony’s guide does not identify one format as universally superior. |
| Ordinary placeholders | Messages that need variable substitution without grammatical selection. | They do not implement plural or gender rules on their own. |
| ICU MessageFormat | Messages requiring plural-, gender-, or locale-sensitive variants. | Uses ICU syntax and the +intl-icu resource naming convention. |
The Symfony Translation guide displayed Symfony 8.1 when consulted on September 30, 2026. Confirm version-specific configuration and requirements against the documentation for the Symfony release installed in your application.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
