Symfony Internationalization: A Step-by-Step Guide

Symfony is one of the oldest and most mature PHP Web Frameworks, with a solid user base and extensive documentation. Symfony also has first-class i18n (internationalization) support built right in. However, Symfony i18n can a bit daunting in the beginning. No worries, though. We’re here to help.

In this guide we will build a demo app and localize it using the official Symfony Translations module. Additionally, we will walk through translating your own data in the database layer using the Doctrine Behaviors bundle. By the end of this guide you will become a Symfony 6 i18n sensei. Let’s get started.

Bundles used in this guide

We’ll use the following bundles to build our demo (versions in parentheses):

• symfony/translation (v6.2) — Adds support for Translation messages in Symfony.
• annotations (v2.0) — Allows you to use PHP comment annotations in code when declaring routes and paths instead of instead of editing yaml files. We’ll use this for localized routing.
• We will be using twig for view templates, and we need a couple of twig add-on bundles to handle i18n filters and functions:
  • twig (v3.0)
  • twig/string-extra (v3.5)
  • twig/intl-extra (v3.5)
• symfony/webpack-encore-bundle (v1.16) — For adding Tailwind CSS to our project for styling the website.
• knplabs/doctrine-behaviors (v2.6) — This is needed for database translations.

🔗 Resource » The code for this guide will be available on GitHub.

Our demo app

We are building an Indie Games blog that hosts reviews of popular Independent video games. Here is a sneak peak of the final design:

Using the Symfony-CLI, let’s create the site using the following command:

Setting up the blog

We’ll use Composer to install the base bundles that we need for now. We will be installing the rest as we go along:

🗒️ Note » If you’re coding along with us, you might want to install and configure Tailwind CSS at this point. Again, this is only for styling, and it’s an optional step.

Creating our home page controller

Let’s create our home page. Create a HomeController.php file inside the /src/Controller folder, and add the following code to it.

We will also need a home template to render the page. You can create one inside the /templates folder. We will hard-code some mock game reviews until we get the database sorted a bit later.

🗒️ Note » We’ve removed most CSS styles from our code listings for brevity. Get the entire demo code, including CSS, from our GitHub repo.

Let’s also modify the base.html.twig to include header and footer sections:

Our header is just a simple nav bar for now:

You should now be able to start the server and see the page rendering as expected:

Now let’s start setting up our locales and translations.

How do I set up the Symfony Translations bundle?

First, we install the bundle via composer:

Configuration: Active locale

The symfony/translations bundle allows us to specify the active locale on load: when a visitor first navigates to a page, they’ll see the page translated in this language. This is configured in config/packages/translation.yml.

The default_path parameter here is used to configure the location of the translation messages. The framework will expand the variable %kernel.project_dir% (which is defined as the root project path) and look inside the /translations path for any defined translations. You can also specify multiple paths to look for using a paths field that accepts a list of path values.

How do I work with basic translations?

Now that we have the locales configured, we can start marking our strings for translation. We use the translator service to wrap all the strings with the trans method.

We then add the twig trans filter after each message string. Let’s update top section of the blog page as an example:

You shouldn’t see any difference in the site now, but underneath the hood we’ve just internationalized the blog’s front-end. We can provide a translation file (with messages) for each locale, and see these translations at runtime. We’ll do this shortly.

First, let’s see the different ways to use the TranslatorInterface we just saw.

How do I use the TranslatorInterface?

Symfony’s TranslatorInteface gives us a few handy ways to define translation strings, and allows to force a locale for a given message.

Using keywords

We can use any kinds of string as message keys. For best practices it’s better if you use dot (.) separated strings.

The dot (.) syntax allows you to declare messages with nested IDs to avoid repeating yourself:

🗒️ Note » We’ll look at translation message files in more detail in the next section.

Using variables

You can construct a string that mixes string literals and variables:

When using concatenated strings like the example above, the translator will only pick up the part of the string without the variable and use it as a key. It will then prepend a double underscore (_ _) in the value part to signify that this message needs a proper translation.

✋ Heads up » Defining translations messages with concatenated strings like this is not recommended. Symfony can’t detect these messages in code properly, so it will be harder to translate properly. Also, languages don’t all share the same grammar; a variable like $visitorCount isn’t always placed in the same position in a translation. So hard-coded interpolation is just bad practice.

🗒️ Note » We cover interpolation in detail after looking at ICU messages later.

Forcing a locale

You can specify a locale directly as the second parameter to trans. This is useful if you want to pin a specific translation for a string but have the rest of the messages render in the current locale:

With this newfound knowledge, let’s start translating our site to German.

How do I work with translation files?

Symfony provides two formats to setup translation files: normal messages and ICU messages. We’ll deal with ICU messages a bit later. Let’s look at normal messages for now.

Extracting translations from code

You can use the following CLI commands to generate translation message files:

This will detect all the usages of the TranslatorInterface in your code and place them into the associated files:

• /translations/messages.en.yml
• /translations/messages.de.yml

The files will contain key-value pairs, where both key and value contain the string we passed to trans(). For example, we have code like this in our home controller:

When you run the translation:extract command, it will detect the trans() call in our code, generating this liine in each of our translation files:

Variables are surrounded by percentage symbols (%).

To create such a message string, you need to add a translation key and then edit the message in the file with the appropriate translation:

🔗 Resource » The Symfony translation bundle covers many formats outside of YAML, including CSV and JSON. See the entire list of supported translation file formats in the official docs.

Go ahead and provide all the required translation strings for each locale.

Now let’s check our German translations by setting up the default locale as de:

Now try to load the site and navigate to the following path

localhost:8000

You should be able to see the translated to German:

You can also force the locale for a given message:

✋ Heads up » Using the Twig {% trans %} is more verbose and does not escape the variables in templates by default. You need to manually escape the translated output using the escape filter otherwise this can expose your visitors to XSS (Cross-site Scripting) attacks.

🔗 Resource » You can find all information about escaping rules and filters in the relevant Twig documentation.

Manually escaping html content works by using the raw filter. This is useful when your translation message contains HTML tags:

✋ Heads up » Again, be careful with the raw filter: Make sure that you trust the HTML in the incoming translation message or you expose your visitors to XSS attacks.

How do I work with ICU messages?

ICU (International Components for Unicode) is a set of widely used message formats in translation software and i18n libraries. It provides services and standards to format localized messages. This includes basic messages, pluralization, numbers, dates, and much, much more.

🤿 Go Deeper » Our Missing Guide to the ICU Message Format covers the ins and outs.

To include ICU MessageFormat translations in our blog we need to make a couple of updates to our project. First you need to change the file extension of the message files to have a +intl-icu suffix:

• messages.en.yaml → messages+intl-icu.en.yaml
• messages.de.yaml → messages+intl-icu.de.yaml

Then you need to change all the variables to be surrounded by brackets ({) instead of percentage symbols (%):

There are %visitors% visitors online → There are {visitors} visitors online

🗒️ Note » Once you have configured the filenames to use ICU, the translation:extract command will automatically extract string into ICU messages.

That’s about it for refactoring. Now let’s explore the power ICU provides.

How do I add dynamic values to translation messages?

With ICU, we can inject dynamic values at runtime using the {variable} syntax in our message strings. We will have to provide a matching value using the second parameter to trans():

Let’s define these messages in English:

And in German:

Then, using the translator interface, pass the variables as a key-value parameters.

Then the output in English will be:

And German:

You can also use dynamic values in twig templates. You can’t use the trans tag, however. You will need to use the full form of the interpolated message with the brackets:

✋ Heads up » If you use variable interpolations in both twig templates and in the TranslatorInterface the latter will always override the former whether you use ICU or normal message formats.

How do I work with plural messages?

ICU is excellent at handling plurals. Let’s add a German plural message to show number of visitors in our site:

Notice that we define the count variable, visitors, followed by the plural directive. We then specify each of our locale’s plural forms. German has two: one and other. It’s like having a switch statement to match visitors with use cases.

We can also use =<number> lines to provide a message for explicit counts. We’re using =0 to define a message when visitors has a value of zero. This will override the regular other form in this case.

✋ Heads up » The other plural form is required. If you do not provide one, you will get an error like the following:

🔗 Resource » You can find all plural form keywords, like one and other, for your supported locales in the official Unicode CLDR Language Plural Rules chart.

With the message above, we get a different plural form output depending on the value of visitors:

You can also have variables within plural forms:

🗒️ Note » In addition to the plural directive there is a select directive. select is suitable for gender rules and any other selection based on non-numeric choices. We cover this in detail in our ICU guide.

Complex plurals

German and English each have two plural forms, one (”We’ve had 1 visitor”) and other (”We’ve had 12 visitors”). Other languages have more forms. Russian has four, Arabic six. The good news is that ICU messages can handle complex plural forms with ease. Let’s look at an example in Arabic:

How do I localize dates?

The ICU message format can localize dates using a variety of options:

The format for rendering date format for a country is defined within brackets. The today parameter specifies the name, the date specifies that it is a date type and the long specifies that it should be printed in full form: January 12, 1952 3:30:32pm.

Twig also comes with special filters that format localized dates. To make full use of them you need to install some extra packages first:

The format_datetime accepts different kinds of parameters. The first one is the format of the date part and the second one is the format of the time part. Each of the parameters can be none, short, full or a custom dateFormat string. The last example showcases the usage of a custom pattern parameter for the whole datetime string instead of its date and time parts.

🔗 Resource »  Learn more about the configuration parameters of format_datetime in the official docs.

How do I localize numbers?

Localized numbers and currency formatting is performed via the number directive in ICU:

The syntax for this is similar to plurals. You use brackets to declare a formatted number parameter. In this case the price is the parameter name, the number declares that it should be formated as a number and the ::currency/USD tag declares that is should be formated as a USD currency.

Using Twig templates, you can use format_number filter that allows formating of numbers. By default, the filter uses the current locale if you do not provide a locale parameter:

🔗 Resource » Learn more about the different configuration parameters of format_number in the official docs.

For currency, Twig offers a special filter, format_currency:

🔗 Resource » Learn more about the configuration parameters of format_currency in the official docs.

How do I get or set the active locale?

We can get or set the locale inside a controller or a service by injecting and using Symfony’s LocaleSwitcher:

How do I configure fallback locales?

Fallback locales are a list of locales that the server will try to use if a requested locale is not supported, or if translations in the active locale are missing. Let’s add fallbacks in our config file:

Here we added two lines for fallbacks corresponding to the English (en) and German (de) language tags. Let’s explore how this works in action.

Say we removed the home.subtitle message from the German translations. You will see the following screen when you visit the Home page with active locale as German:

Here the home.subtitle will fallback to the English translation since it’s the one available but the rest of the messages will translate fine.

Symfony’s translation bundle will also automatically resolve locale fallback based on the specificity of the requested locale. Say we’re detecting the locale from the visitor’s browser (more on that later). Let’s assume our visitor has set her preferred browser locale to German (Germany) ie. de-DE. With the above configuration, Symfony will fall back to the parent locale of de-DE, which is de.

🗒️ Note » At the end of the fallback cascade, if Symfony can’t find a suitable locale, it always falls back to our default locale (en in our case).

🔗 Resource » We’re specifying our locales using their ISO 639-1 codes (en, de). You can find a list of all these codes on Wikipedia.

How do I support right-to-left languages?

It’s important to remember to support right-to-left (RTL) languages like Arabic and Hebrew. We can leverage browser features to make a web page render RTL content. The first step is to add dir="rtl" to the <html> tag for RTL locales. We can modify the base.html.twig template to add this value whenever we switch to that locale:

We get the active locale through app.request.attributes.get('_locale'). The code above will product <html dir='rtl'> when the active locale is Arabic. For every other locale, we’ll get <html dir='ltr'>.

For brevity, we won’t go through the steps of adding Arabic to our app here. Feel free to follow the previous configuration, extraction, and translation steps to do so. Assuming all that’s done, setting our default_locale to ar would yield the home page rendered right-to-left:

🤿 Go Deeper » The above if statement inside the twig template does not scale well. If you have multiple RTL languages in your app, you might want to create a custom Twig extension that encapsulates your conditional logic.

How do I create localized routes?

Until now we’ve been viewing a particular locale by setting our default_locale setting to that language tag.

We would like visitors to be able to navigate to a page and automatically detect the user locale based on their browser language preferences or the current url parameters.

We have a variety of options to customise the routing behaviour based on the selected locale. We take a deeper look at each one of them.

First, let’s look at basic localized routing in Symfony.

What is a localized route?

A localized route is a route that defines a different URL per each translation locale. For example we can associate a route with a particular locale:

You can generate a localized route in twig using the path function passing the _locale as a parameter:

Using a locale prefix

A common way to generate localized routes is to prefix each route with a locale code. We can use the special _locale parameter in our route annotations to accomplish this. During runtime, the framework will automatically set the active locale to the value of _locale:

For example:

http://localhost:8000/en/reviews → switches locale to English. http://localhost:8000/de/reviews → switches locale to German.

🗒️ Note » It is recommended to follow a consistent scheme for locale paths so that the users can bookmark links for future navigation. Having for example the _locale parameter in a different place, e.g. /blog/{_locale}/, is possible but not consistent.

Using a different path per locale

You can provide an array of paths when using the Route annotation, allowing you to set a different path for each locale, all resolving to the same controller action:

Here if the active locale is German, the navigation will point to /de/rezensionen. If it’s English, it will point to /en/reviews.

🗒️ Note » You might be wondering how the active locale is determined here. We’ll tackle this in the locale determination section a bit later.

If you want to leave the default locale out of the url, just use an empty string:

Here the path to /reviews will use the default locale (English) and the path to de will use the German locale.

Forcing a locale in a URL

You can generate url for a fixed locale by passing along the _locale parameter:

In twig templates, when you use the path function, it will automatically pick up the active locale from app.request:

Forcing a localized home route

We can create a redirect route that ensures that navigating to / always redirects to /en:

🤿 Go deeper » There’s a lot more you can do with localized routes, including limiting the locales that a given route supports.

How do I automatically determine the user’s locale?

We can instruct the Symfony framework to choose the active locale based on the user’s browser language preferences and our app’s supported locales. With each request, the browser will provide an Accept-Language header, matching a weighted set of locale user preferences. Symfony will use the header and try to match the most suitable locale.

Symfony includes this feature by default. You just need to enable it by adding the following lines in your framework.yaml config:

✋ Heads up » If using the Language negotiation feature, make sure that you do not annotate the routes with the {_locale} parameter. The {_locale} parameter will always override an Accept-Language header. If you want to support both features you will need to implement a custom Event Listener.

When set_locale_from_accept_language is true the request locale is automatically set based on the Accept-Language value and based on the enabled_locales list.

The set_content_language_from_locale sets the value of the Content-Language HTTP response header based on the request locale. You should have both set_locale_from_accept_language and set_content_language_from_locale options enabled if using this feature so that the framework will send the correct headers to clients.

To test automatic locale detection, you need to configure your browser’s preferred language list. Make sure the language you want your app to resolve to is at the top of the list. Here is my Chrome configuration, for example, which can be found at Settings → Languages:

Then you need a route with no {_locale} parameter to allow Symfony to automatically resolve the locale:

When you navigate to /, Symfony will render the page in German, since the locale is preferred by the user per the Accept-Language header:

How do I create a language switcher?

We often want a way for users to manually switch the active locale. This is surprisingly easy to do in Symfony. Adding the following HTML code inside the header.html.twig will show the current language and a list of available locales for the user to choose from:

That’s it! Now our visitors can use the drop-down to select the language of their choice.

How do I localize my data?

The last important step left in our blog translations is the actual reviews content. We would like to have an Admin or Publisher write game reviews using a dashboard. Of course, we’ll want to store this content in a database. So how do we allow for different translations of this content?

Let’s quickly setup a database . You will need to spin up a PostgreSQL server so that you can apply database migrations on it. Luckily for us, the project folder has a docker-compose.yaml which we can run with Docker Compose:

This will create a PostgreSQL container with the following configuration:

• host: localhost
• port: 5432
• database: app
• password: !ChangeMe!

Next use the make:entity console command to generate some boilerplate code for the Review entity:

This will create the following Review and ReviewRepository files:

At this point you can add extra fields in the Review Entity. We want to have two extra fields for updated and created datetime events so go ahead and add those now:

Next we’ll use a well known bundle called DoctrineBehaviors from KnpLabs that adds a few interesting traits to our entities; one of these is the TranslatableTrait. This trait allows our models to create easily associate translations with an entity. Let’s see how we can use it for our example project.

First things first, you need to install it:

🔗 Resource » Review the different options to configure the Translatable trait in the docs.

Next, we need to make the Review entity implement Doctrine TranslatableInterface and use the TranslatableTrait from the bundle:

Then you will need to create another Entity that provides the Translatable fields. This entity should implement the TranslationInterface and use the TranslationTrait (⚠️ not TranslatableTrait). Follow the same process by using the make:entity command to generate the boilerplate files for you:

Delete the ReviewTranslationRepository.php since we are not going to use it.

Then add the TranslationInterface and the translatable fields in the ReviewTranslation entity. We need two fields: title of type string and content of type text.

This should look like this:

Note that by default there is no real association between the ReviewTranslation and Review entities. Instead the bundle relies on merging new translations to the specified model by using the mergeNewTranslations method on that model. When we add a locale translation to the Review entity we need to subsequently call mergeNewTranslations so that it will create entries in the ReviewTranslation with the primary key of Review.

Run the following from the command line to create database tables:

Then run the following command to create all the necessary migrations for the table schemas.

Now run the migrations to apply them in the database.

Check your database. You should be able to see two tables created, one for the Review and one for the ReviewTranslation:

Updating translatable models

When creating or updating the Review entity, you need to use the translate method provided by DoctrineBehavior’s TranslatableInterface. Here is an example interaction for saving a model in the database in a Controller form Action handler:

Here we are using a ReviewType class which contains the form data for the Review Entity. We will show how it looks like in a moment.

Now check your database. You should be able to see both a new row in the review table and associated translation rows in review_translation.

Using the above flow you should be able to translate the rest of the site content with the Game Reviews for all supported locales.

Finally we can populate the list of reviews when switching to the selected locale:

Then update the associated Twig template:

How do I accept form data for a localized model?

To create the form type for Review that accepts a specific locale translation data, you need to create a custom form named ReviewType. This is how it will look like in code:

Here we create a custom form with the required Review Entity fields (title and content) and a special locale field that allows the user to choose a language.

Then the user will have to fill the form select the locale to provide translations and submit the POST request.

The controller will take the form data and save the model translations using the previous guide on how to update the Translatable Models.

🤿 Go Deeper » Learn how to create advanced Form Types and how to process forms.

Similar forms for the update actions should be provided for any other entity that you want to provide database translations.

Take Symfony localization to the next level

We hope you enjoyed building this Symfony i18n project with us. If you’re ready to level up your app translation process, check out the Phrase Localization Suite.

With its dedicated software localization solution, Phrase Strings, you can manage translation strings for your web or mobile app more easily and efficiently than ever.

With a robust API to automate translation workflows and integrations with GitHub, GitLab, Bitbucket, and other popular software platforms, Phrase Strings can do the heavy lifting for you to stay focused on your code.

Phrase Strings comes with a full-featured strings editor where translators can pick up the content for translation you had pushed. As soon as they’re done with translation, you can pull the translated content back into your project automatically.

As your software grows and you want to scale, our integrated suite lets you connect Phrase Strings with a cutting-edge translation management system (TMS) to fully leverage traditional CAT tools and AI-powered machine translation capabilities.

Check out all Phrase features for developers and see for yourself how they can streamline your software localization workflows from the get-go.