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
5.1.1. A configuração: config/packages/framework.yaml
- 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]:
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:
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
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
- 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
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
- 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]).
- 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).
- 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.
- 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":


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


A troca de idioma, vista com o [curl]. A opção [-H] fornece o cabeçalho [Referer] que o navegador enviaria:
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.
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]):
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.