Skip to content

5. Internacionalização

Uma aplicação internacionalizada exibe seus textos no idioma do usuário. O estudo de caso está em francês e inglês. O princípio é simples: as views não contêm mais texto, e sim chaves ([MENU.HOME]), e um dicionário para cada idioma associa um texto a cada chave. O idioma selecionado é armazenado em um cookie.

O [Symfony] inclui um componente de tradução, o Translator, que já encontramos no Exemplo 09 para as mensagens de validação. Seus dicionários ficam na pasta [translations], com um arquivo por domínio e por idioma: [validators.en.yaml] (o domínio das mensagens de validação, Exemplo 09), [messages.en.yaml] (o domínio padrão, o dos nossos textos). O formato YAML permite chaves aninhadas: é assim que os dicionários das versões [ASP.NET Core MVC], [NestJS], [Spring MVC], [Flask] e [Laravel] do estudo de caso, exceto pela sintaxe. Para a sintaxe das próprias mensagens, escolhemos o formato ICU (International Components for Unicode), um padrão que a extensão [intl] do [PHP] sabe interpretar e que, por exemplo, permite flexionar o texto no plural. A formatação de datas e valores continua a mesma do Exemplo 16.

5.1. Exemplo 22: Uma aplicação bilíngue

22-i18n/
├── config/
│   └── packages/
│       └── framework.yaml
├── src/
│   ├── Controller/
│   │   ├── LanguageController.php
│   │   └── PagesController.php
│   ├── EventListener/
│   │   └── SetLanguage.php
│   ├── Model/
│   │   └── Product.php
│   └── Twig/
│       └── FormatsExtension.php
├── templates/
│   ├── fragments/
│   │   └── navbar.html.twig
│   ├── layout.html.twig
│   └── pages/
│       ├── home.html.twig
│       └── products.html.twig
├── translations/
│   ├── messages+intl-icu.en.yaml
│   └── messages+intl-icu.fr.yaml
└── ...

5.1.1. A configuração: config/packages/framework.yaml

# config/packages/framework.yaml: a configuração do FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # o idioma padrão e os idiomas suportados pela aplicação
    default_locale: en
    enabled_locales: ['en', 'fr']
    # o serviço de TRADUÇÃO; seus dicionários ficam na pasta translations/.
    # Uma chave ausente do dicionário francês é procurada no dicionário inglês
    translator:
        default_path: '%kernel.project_dir%/translations'
        fallbacks: ['en']
  • Linha 5: o idioma padrão da aplicação, usado para as requisições que não especificam um idioma (Exemplo 09);
  • linha 6: os idiomas aceitos pela aplicação. Essa lista é usada pelo [Symfony] (o profiler, a geração de rotas localizadas etc.); nosso próprio código também tem sua própria lista, no listener [SetLanguage];
  • linhas 9–11: o serviço de tradução. [fallbacks] especifica o(s) idioma(s) de fallback: se uma chave não existir no dicionário do idioma solicitado, ela é procurada no dicionário em inglês. Uma chave ausente de todos os dicionários é exibida tal como está: assim, qualquer omissão fica imediatamente visível na tela.

5.1.2. Os dicionários

O arquivo [translations/messages+intl-icu.fr.yaml]:

# translations/messages+intl-icu.fr.yaml: o dicionário francês.
# messages: o domínio padrão; +intl-icu: as mensagens seguem a sintaxe ICU
# ({name}: um parâmetro; {n, plural, ...}: uma mensagem que depende de um número)
MENU:
    HOME: Accueil
    PRODUCTS: Produits
HOME:
    TITLE: Bienvenue
    HELLO: 'Bonjour {name} !'
    DATE: 'Nous sommes le {date}.'
PRODUCTS:
    TITLE: Nos produits
    NAME: Produit
    PRICE: Prix
    COUNT: '{n, plural, =0 {Aucun produit} one {# produit} other {# produits}} au catalogue.'

O nome do arquivo é composto de três partes: o domínio ([messages], o domínio padrão), o sufixo [+intl-icu], que indica mensagens no formato ICU, e o idioma ([fr]). As chaves são agrupadas por tema por meio do aninhamento do YAML: o item de menu “Accueil” tem a chave [MENU.HOME], com os níveis separados por um ponto. Um texto pode conter parâmetros, escritos como [{name}], que são substituídos durante a tradução.

  • Linha 9: os apóstrofos delimitam uma string YAML; eles são necessários quando o texto contém caracteres que o YAML interpreta (chaves, dois-pontos etc.);
  • Linha 15: uma mensagem no plural. [{n, plural, ...}] seleciona uma forma conforme o valor do parâmetro [n]: [=0] para exatamente 0, [one] para o singular, [other] para o plural; [#] é substituído pelo número. As regras de plural dependem do idioma, e o ICU as conhece: em francês, 0 e 1 são singular, ao passo que em inglês 0 é plural (“0 products”). Isso é um avanço em relação ao “product(s)” usado nas versões anteriores do estudo de caso.

O arquivo [translations/messages+intl-icu.en.yaml] tem exatamente as mesmas chaves:

# translations/messages+intl-icu.en.yaml: o dicionário inglês; mesmas chaves
MENU:
    HOME: Home
    PRODUCTS: Products
HOME:
    TITLE: Welcome
    HELLO: 'Hello {name}!'
    DATE: 'Today is {date}.'
PRODUCTS:
    TITLE: Our products
    NAME: Product
    PRICE: Price
    COUNT: '{n, plural, =0 {No products} one {# product} other {# products}} in the catalogue.'

Sem o sufixo [+intl-icu], os parâmetros seriam escritos como [%name%], e o plural usaria uma sintaxe específica do [Symfony] ([{0} Aucun produit|{1} Un produit|]1, Inf[ %n% produits]). O formato ICU é o atualmente recomendado pela documentação do [Symfony].

5.1.3. O idioma de cada requisição: src/EventListener/SetLanguage.php

<?php
// src/EventListener/SetLanguage.php: o idioma de cada requisição

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;

// priority 20: depois do roteamento, antes dos listeners do Symfony que usam o idioma (veja o exemplo 16)
#[AsEventListener(event: KernelEvents::REQUEST, priority: 20)]
class SetLanguage
{
    // os idiomas suportados; o primeiro é o idioma padrão
    public const LANGUAGES = ['en', 'fr'];

    public const COOKIE = 'language';

    // o idioma do cookie [language] se for suportado, inglês caso contrário
    public function __invoke(RequestEvent $event): void
    {
        $request = $event->getRequest();
        $language = $request->cookies->get(self::COOKIE);
        $request->setLocale(in_array($language, self::LANGUAGES, true) ? $language : self::LANGUAGES[0]);
    }
}

Este é o listener [SetLanguage] do Exemplo 16, que desta vez obtém o idioma de um cookie:

  • linha 11: o listener do evento [kernel.request], com prioridade 20: depois do roteamento, mas antes dos listeners do [Symfony] que usam o idioma da requisição (Exemplo 16);
  • linhas 15–17: os idiomas aceitos e o nome do cookie: constantes de classe públicas, acessíveis a partir de outras classes ([SetLanguage::LANGUAGES]);
  • linhas 22–24: o idioma da requisição: o idioma do [language] cookie, se existir e for aceito; caso contrário, o inglês. [$request->cookies] é o conjunto de cookies enviados pelo navegador (exemplo 05); [get] devolve o valor de um cookie ou [null]. [in_array], com [true] como terceiro parâmetro, compara também os tipos ([===]). [setLocale] define o idioma da requisição: é o idioma usado pelo tradutor, por nossos filtros de formatação e pelo filtro [format_currency] do [Twig].

Diferentemente do [Laravel], o [Symfony] não criptografa os cookies: o cookie [language] é transmitido em texto simples. Isso não é um problema: ele não contém nenhuma informação confidencial, e o servidor aceita apenas idiomas suportados. O exemplo seguinte retoma a questão de quanta confiança se pode depositar em um cookie.

5.1.4. Seleção do idioma: src/Controller/LanguageController.php

<?php
// src/Controller/LanguageController.php: a escolha do idioma

namespace App\Controller;

use App\EventListener\SetLanguage;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;

class LanguageController extends AbstractController
{
    // GET /language/fr: armazena a escolha em um cookie e depois volta à página anterior.
    // requirements: um idioma diferente de en ou fr não corresponde à rota (404)
    #[Route('/language/{code}', name: 'language', requirements: ['code' => 'en|fr'], methods: ['GET'])]
    public function change(Request $request, string $code): RedirectResponse
    {
        $response = $this->redirect(self::originPage($request));
        // o cookie: um ano de vida, ilegível pelo JavaScript da página (httpOnly),
        // nunca enviado com uma requisição POST vinda de outro site (sameSite lax)
        $response->headers->setCookie(Cookie::create(SetLanguage::COOKIE, $code)
            ->withExpires(new \DateTimeImmutable('+1 year'))
            ->withHttpOnly(true)
            ->withSameSite(Cookie::SAMESITE_LAX));
        return $response;
    }

    // a página de onde viemos (cabeçalho Referer), da qual guardamos apenas o caminho:
    // redirecionar para um endereço completo vindo da requisição permitiria
    // enviar o usuário a outro site (falha de "open redirect")
    private static function originPage(Request $request): string
    {
        // parse_url divide uma URL em seus componentes (caminho, parâmetros...)
        $url = parse_url($request->headers->get('Referer', ''));
        $path = $url['path'] ?? '';
        // "//site.com/..." seria entendido pelo navegador como um endereço
        // em OUTRO site: recusado também
        if (! str_starts_with($path, '/') || str_starts_with($path, '//')) {
            return '/';
        }
        return isset($url['query']) ? "$path?{$url['query']}" : $path;
    }
}
  • linha 17: a rota [/language/{code}]. A opção [requirements] (exemplo 02) limita o parâmetro aos dois idiomas aceitos: [/language/de] não corresponde a nenhuma rota e devolve um erro 404;
  • linha 20: a ação responde com um redirecionamento para a página de onde o usuário veio: o usuário volta à sua página, já no novo idioma;
  • Linhas 23–26: a resposta contém um cookie, que o navegador reenviará a cada requisição. A classe [Cookie] do [Symfony] o descreve: [Cookie::create(name, value)] o cria, e cada método de [with...] devolve uma cópia modificada (um objeto imutável; veja o Exemplo 03): [withExpires], a data de expiração (em um ano); [withHttpOnly(true)] o torna invisível para o [JavaScript] da página; [withSameSite(Cookie::SAMESITE_LAX)] impede que o navegador o envie com uma requisição POST de outro site. ([httpOnly] e [lax] são, aliás, os valores padrão de [Cookie::create].) [$response->headers->setCookie] o adiciona à resposta como um cabeçalho [Set-Cookie];
  • linhas 33–44: a página de origem é indicada pelo cabeçalho [Referer] da requisição (a grafia incorreta, com um único [r], é a usada no padrão HTTP), que o navegador preenche com a URL da página que continha o link. Mas esse cabeçalho vem do cliente, que pode colocar qualquer coisa nele. Redirecionar cegamente para esse endereço transformaria nossa aplicação em um redirecionamento aberto: um link malicioso com o nome do nosso domínio poderia enviar o usuário a um site malicioso. Por isso, mantemos apenas o caminho e os parâmetros da URL (a função [parse_url] do [PHP] a decompõe em seus componentes em um array associativo) e rejeitamos qualquer caminho que comece por [//], que o navegador interpretaria como o endereço de outro site.

5.1.5. Ações: src/Controller/PagesController.php

<?php
// src/Controller/PagesController.php: as actions nada sabem sobre o idioma:
// elas fornecem dados, as views os traduzem e os formatam

namespace App\Controller;

use App\Model\Product;
use DateTimeImmutable;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(methods: ['GET'])]
class PagesController extends AbstractController
{
    #[Route('/', name: 'home')]
    public function home(): Response
    {
        return $this->render('pages/home.html.twig', ['name' => 'Marie',
            'today' => new DateTimeImmutable('2026-09-23')]);
    }

    #[Route('/products', name: 'products')]
    public function products(): Response
    {
        return $this->render('pages/products.html.twig', ['products' => [
            new Product('Keyboard', 2500),
            new Product('Mouse', 1250),
            new Product('Screen', 114900),
        ]]);
    }
}

As ações são agnósticas quanto ao idioma: fornecem dados brutos (um nome, uma data, valores em centavos). A tradução e a formatação ficam a cargo das views. A classe [Product] tem um nome e um preço em centavos; a extensão [FormatsExtension] é a do Exemplo 16: seu filtro [long_date] escreve uma data no formato “completo” do idioma da requisição (“Wednesday, September 23, 2026”, “mercredi 23 septembre 2026”), e seu filtro [money] escreve um valor monetário.

5.1.6. Traduzir nas views

<!doctype html>
{# app.request.locale: o idioma da requisição, "en" ou "fr" #}
<html lang="{{ app.request.locale }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {# o título: o bloco [title] da página, já traduzido #}
  <title>{% block title %}{% endblock %}</title>
  <link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3">
    {% include 'fragments/navbar.html.twig' %}
    <main>
      {% block content %}{% endblock %}
    </main>
  </div>
</body>
</html>
  • linha 3: o atributo [lang] da página indica seu idioma a navegadores, mecanismos de busca e leitores de tela; [app.request.locale] é o idioma da requisição;
  • linha 8: o título da página é fornecido pela própria página, já traduzido (bloco [title]).
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    {# 'KEY'|trans: a tradução de uma chave, no idioma da requisição #}
    <a class="nav-link" href="{{ path('home') }}">{{ 'MENU.HOME'|trans }}</a>
    <a class="nav-link" href="{{ path('products') }}">{{ 'MENU.PRODUCTS'|trans }}</a>
  </div>
  {# o idioma atual é destacado #}
  <div class="btn-group btn-group-sm">
    {% for code in ['fr', 'en'] %}
      <a class="btn {{ app.request.locale == code ? 'btn-primary' : 'btn-outline-primary' }}"
         href="{{ path('language', {code: code}) }}">{{ code|upper }}</a>
    {% endfor %}
  </div>
</nav>
  • linhas 4–5: o filtro [trans] traduz uma chave para o idioma da requisição;
  • linhas 9–12: um botão por idioma, que aciona a ação [/language/{code}]. O idioma atual é destacado ([btn-primary], botão cheio).
{% extends 'layout.html.twig' %}
{% block title %}{{ 'HOME.TITLE'|trans }}{% endblock %}

{% block content %}
  <h1>{{ 'HOME.TITLE'|trans }}</h1>
  {# um parâmetro: o parâmetro do filtro trans, um array associativo #}
  <p>{{ 'HOME.HELLO'|trans({name: name}) }}</p>
  {# a data, formatada primeiro (filtro long_date, veja o exemplo 16), depois passada como parâmetro [date] #}
  <p>{{ 'HOME.DATE'|trans({date: today|long_date}) }}</p>
{% endblock %}
  • linha 2: o bloco [title] traduzido para o template;
  • linha 7: os parâmetros de um texto são fornecidos em um array associativo, um parâmetro do filtro [trans]; [{name}] é substituído pelo valor da chave [name];
  • linha 9: a data, formatada no idioma da requisição pelo filtro [long_date] e depois passada como parâmetro.
{% extends 'layout.html.twig' %}
{% block title %}{{ 'PRODUCTS.TITLE'|trans }}{% endblock %}

{% block content %}
  <h1>{{ 'PRODUCTS.TITLE'|trans }}</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>{{ 'PRODUCTS.NAME'|trans }}</th><th class="text-end">{{ 'PRODUCTS.PRICE'|trans }}</th></tr></thead>
    <tbody>
      {% for product in products %}
        <tr>
          <td>{{ product.name }}</td>
          {# o filtro money do exemplo 16: o formato depende do idioma #}
          <td class="text-end">{{ product.priceCents|money }}</td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  {# a mensagem de plural: o ICU escolhe a forma de acordo com o parâmetro n #}
  <p>{{ 'PRODUCTS.COUNT'|trans({n: products|length}) }}</p>
{% endblock %}
  • linha 13: o filtro [money], cujo resultado depende do idioma;
  • linha 19: o parâmetro [n] para a forma plural da mensagem: o número de produtos ([length], exemplo 14). Os nomes dos produtos em si não são traduzidos: são dados que, em uma aplicação real, viriam de um banco de dados.

Fora das views, o tradutor é um serviço do tipo [TranslatorInterface], que uma ação ou um serviço pode receber por injeção: [$translator->trans('HOME.HELLO', ['name' => 'Marie'])].

5.1.7. Execução

A página inicial, em inglês (o idioma padrão) e depois em francês, após clicar no botão "FR":

Image

Image

A página de produtos, nos dois idiomas. Os valores seguem as convenções de cada idioma:

Image

Image

A troca de idioma, vista com o [curl]. A opção [-H] fornece o cabeçalho [Referer] que o navegador enviaria:

curl -i -H "Referer: http://localhost:8000/products" http://localhost:8000/language/en
1
2
3
4
5
HTTP/1.1 302 Found
...
Location: /products
...
Set-Cookie: language=en; expires=Mon, 27 Sep 2027 09:47:37 GMT; Max-Age=31536000; path=/; httponly; samesite=lax

O redirecionamento leva de volta à página de origem (o [Symfony] escreve uma URL relativa, que o navegador completa), e o cookie é definido por um ano. Um [Referer] que aponte para outro site não redireciona para lá: apenas seu caminho é mantido.

curl -i -H "Referer: https://pirate.example/trap" http://localhost:8000/language/en
curl -i -H "Referer: http://localhost:8000//pirate.example/x" http://localhost:8000/language/fr
1
2
3
4
5
6
HTTP/1.1 302 Found
Location: /trap
...
HTTP/1.1 302 Found
Location: /
...

A página [/trap] não existe em nosso site: o usuário receberá um erro 404, mas permanecerá em nosso site. Por fim, a página inicial, solicitada com o cookie [language=en] (opção [-b] do [curl]):

curl -b "language=en" http://localhost:8000/
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Welcome</title>
...
        <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/products">Products</a>
...
    <p>Hello Marie!</p>
    <p>Today is Wednesday, September 23, 2026.</p>
...

Outra maneira de escolher o idioma seria ler o cabeçalho [Accept-Language] do navegador (exemplo 12; [$request->getPreferredLanguage(['fr', 'en'])] seleciona o melhor idioma dentre os aceitos). As duas costumam ser combinadas: o idioma do navegador na primeira visita, seguido do idioma que o usuário selecionou. Um terceiro método, muito usado com o [Symfony], coloca o idioma na URL ([/en/products]): um parâmetro de rota especial, [{_locale}], define então o próprio idioma da requisição. Este estudo de caso se concentra no cookie, com o inglês como idioma padrão.