Ebooks

Symfony translation tutorial

Symfony translation tutorial shows how to to work with different languages in Symfony.

Internationalization and localization is adapting computer software for different languages and cultures.

Symfony translation

For internationalization and localization, Symfony contains the symfony/translation package for these tasks.

The translation files have the following mandatory format: domain.locale.loader. The domain is an optional way to organize messages into groups. The default domain is messages. The locale defines the locale of the translation file; e.g. en, sk, or de. The loader is a way to load and parse the file; e.g. xlf, php, or yaml.

The translated text can be written into different file formats. The Symfony translation component supports lots of translation formats such as XLIFF, PHP, Qt, .po, .mo, JSON, CSV or INI. The recommended format is XLIFF.

The translation files can be placed in three different directories, where the first location has the highest priority: translations/, src/Resources/%bundle name%/translations/, or Resources/translations/.

Symfony translation example

In the following example, we create a simple web application that returns a message according to the locale. We use the default messages domain.

$ composer create-project symfony/skeleton symtrans

With composer, we create a new Symfony skeleton project.

$ cd symtrans

We go to the project directory.

$ composer require symfony/translation    
$ composer require annotations
$ composer require maker

We install three packages: symfony/translation, annotations and maker.

$ composer require server --dev

We install the development web server.

config/packages/translation.yaml
framework:
    default_locale: '%locale%'
    translator:
        paths:
            - '%kernel.project_dir%/translations'
        fallbacks:
            - '%locale%'

In the translation.yaml file, we have a default locale defined. It uses a %locale% parameter, which is set in the services.yaml configuration file.

config/services.yaml
parameters:
    locale: 'en'
...    

By default, we have English default locale.

translations/messages.en.xlf
<?xml version="1.0"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file source-language="en" target-language="en" datatype="plaintext" 
            original="file.ext">
        <body>
            <trans-unit id="text.message">
                <source>text.message</source>
                <target>Today is a beautiful day</target>
            </trans-unit>
        </body>
    </file>
</xliff>

This is an translation file for the English language.

<trans-unit id="text.message">
    <source>text.message</source>
    <target>Today is a beautiful day</target>
</trans-unit>

We have one translation unit. A translation unit is identified by Id.

translations/messages.sk.xlf
<?xml version="1.0"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file source-language="en" target-language="sk" datatype="plaintext" 
            original="file.ext">
        <body>
            <trans-unit id="text.message">
                <source>text.message</source>
                <target>Dnes je krásny deň.</target>
            </trans-unit>
        </body>
    </file>
</xliff>

This is a translation file for the Slovak language.

$ php bin/console clear:cache

Note that we might need to clear the cache.

$ php bin/console make:controller HomeController

We create a HomeController.

src/Controller/HomeController.php
<?php

namespace App\Controller;

use Symfony\Component\Routing\Annotation\Route;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Translation\TranslatorInterface;

class HomeController extends Controller
{
    /**
     * @Route("/", name="home")
     */
    public function index(TranslatorInterface $translator)
    {
        $translated = $translator->trans('text.message',[], null, 'sk');    

        return new Response($translated);
    }
}

The HomeController returns a translated message.

public function index(TranslatorInterface $translator)
{

We inject the TranslatorInterface to get Symfony translation services.

$translated = $translator->trans('text.message',[], null, 'sk');

The tranlator's trans() method translates the given message. The last parameter is the locale. In our case, we have used the Slovak locale, so we expect a message in Slovak.

$ php bin/console server:start

We start the server.

$ curl localhost:8000
Dnes je krásny deň.

We generate a GET request with curl and get a message in Slovak.

Using Twig template

Next we are going to use the Twig template.

$ composer require twig

We install Twig.

HomeController.php
<?php

namespace App\Controller;

use Symfony\Component\Routing\Annotation\Route;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\Translation\TranslatorInterface;

class HomeController extends Controller
{
    /**
     * @Route("/home", name="home")
     */
    public function index(TranslatorInterface $translator)
    {

        $message = $translator->trans('text.message',[], null, 'sk');        

        return $this->render('home/index.html.twig', [
            'message' => $message
        ]);
    }
}

The controller translates the message and renders a Twing template. It sends the template the translated message.

templates/home/index.html.twig
{% extends 'base.html.twig' %}

{% block title %}Home page{% endblock %}

{% block body %}

{% trans %}%message%{% endtrans %}

{% endblock %}

In the template, we display the message with the Twig {% trans %} and {% endtrans %} directives.

templates/base.html.twig
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title>{% block title %}Welcome!{% endblock %}</title>
        {% block stylesheets %}{% endblock %}
    </head>
    <body>
        {% block body %}{% endblock %}
        {% block javascripts %}{% endblock %}
    </body>
</html>

This is the autogenerated base template file.

In this tutorial we have worked with translations in Symfony.

You might also be interested in the following related tutorials: Introduction to Symfony, Symfony form tutorial, Symfony validation tutorial, Symfony upload file tutorial, Symfony service tutorial, Symfony request tutorial, PHP tutorial.