Skip to content

5. Internacionalización

Una aplicación internacionalizada muestra su texto en el idioma del usuario. El caso de estudio está en francés e inglés. El principio es simple: las vistas ya no contienen texto, sino claves ([MENU.HOME]), y un diccionario para cada idioma asocia un texto a cada clave. El idioma seleccionado se almacena en una cookie.

[Symfony] incluye un componente de traducción, el Translator, que ya encontramos en el Ejemplo 09 para los mensajes de validación. Sus diccionarios se almacenan en la carpeta [translations], con un archivo por dominio e idioma: [validators.en.yaml] (el dominio de los mensajes de validación, Ejemplo 09), [messages.en.yaml] (el dominio predeterminado, el de nuestros textos). El formato YAML admite claves anidadas: así, los diccionarios de las versiones [ASP.NET Core MVC], [NestJS], [Spring MVC], [Flask] y [Laravel] del caso de estudio, salvo por la sintaxis. Para la sintaxis de los propios mensajes, elegimos el formato ICU (International Components for Unicode), un estándar que la extensión [intl] de [PHP] puede interpretar y que, por ejemplo, permite flexionar el texto en plural. El formato de fechas y montos sigue siendo el mismo que en el Ejemplo 16.

5.1. Ejemplo 22: una aplicación bilingüe

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. La configuración: config/packages/framework.yaml

# config/packages/framework.yaml: la configuración del FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # el idioma predeterminado, y los idiomas admitidos por la aplicación
    default_locale: en
    enabled_locales: ['en', 'fr']
    # el servicio de TRADUCCIÓN; sus diccionarios están en la carpeta translations/.
    # Una clave ausente del diccionario francés se busca en el diccionario inglés
    translator:
        default_path: '%kernel.project_dir%/translations'
        fallbacks: ['en']
  • Línea 5: el idioma predeterminado de la aplicación, que se usa para las solicitudes que no especifican un idioma (Ejemplo 09);
  • línea 6: los idiomas admitidos por la aplicación. Esta lista la usa [Symfony] (el profiler, la generación de rutas localizadas, etc.); nuestro propio código también tiene su propia lista, en el listener [SetLanguage];
  • líneas 9–11: el servicio de traducción. [fallbacks] especifica el o los idiomas de respaldo: si una clave falta en el diccionario del idioma solicitado, se busca en el diccionario en inglés. Una clave que falta en todos los diccionarios se muestra tal cual: de este modo, cualquier omisión es visible de inmediato en la pantalla.

5.1.2. Los diccionarios

El archivo [translations/messages+intl-icu.fr.yaml]:

# translations/messages+intl-icu.fr.yaml: el diccionario francés.
# messages: el dominio predeterminado; +intl-icu: los mensajes siguen la sintaxis ICU
# ({name}: un parámetro; {n, plural, ...}: un mensaje que depende de un 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.'

El nombre del archivo consta de tres partes: el dominio ([messages], el dominio predeterminado), el sufijo [+intl-icu], que indica mensajes en formato ICU, y el idioma ([fr]). Las claves se agrupan por tema mediante la estructura de anidamiento de YAML: el elemento de menú “Accueil” tiene la clave [MENU.HOME], con los niveles separados por un punto. Un texto puede contener parámetros, escritos como [{name}], que se reemplazan durante la traducción.

  • Línea 9: los apóstrofos delimitan una cadena YAML; son necesarios cuando el texto contiene caracteres que YAML interpreta (llaves, dos puntos, etc.);
  • Línea 15: un mensaje en plural. [{n, plural, ...}] selecciona una forma según el valor del parámetro [n]: [=0] para exactamente 0, [one] para el singular, [other] para el plural; [#] se reemplaza por el número. Las reglas del plural dependen del idioma, e ICU las conoce: en francés, 0 y 1 son singular, mientras que en inglés, 0 es plural (“0 products”). Esto mejora el “product(s)” utilizado en las versiones anteriores del caso de estudio.

El archivo [translations/messages+intl-icu.en.yaml] tiene exactamente las mismas claves:

# translations/messages+intl-icu.en.yaml: el diccionario inglés; mismas claves
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.'

Sin el sufijo [+intl-icu], los parámetros se escribirían como [%name%], y el plural usaría una sintaxis propia de [Symfony] ([{0} Aucun produit|{1} Un produit|]1, Inf[ %n% produits]). El formato ICU es el que recomienda actualmente la documentación de [Symfony].

5.1.3. El idioma de cada solicitud: src/EventListener/SetLanguage.php

<?php
// src/EventListener/SetLanguage.php: el idioma de cada solicitud

namespace App\EventListener;

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

// prioridad 20: después del enrutamiento, antes de los listeners de Symfony que usan el idioma (véase el ejemplo 16)
#[AsEventListener(event: KernelEvents::REQUEST, priority: 20)]
class SetLanguage
{
    // los idiomas admitidos; el primero es el idioma predeterminado
    public const LANGUAGES = ['en', 'fr'];

    public const COOKIE = 'language';

    // el idioma de la cookie [language] si es admitido, inglés en caso contrario
    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 es el listener [SetLanguage] del Ejemplo 16, que esta vez obtiene el idioma de una cookie:

  • línea 11: el listener del evento [kernel.request], con prioridad 20: después del enrutamiento, pero antes de los listeners de [Symfony] que utilizan el idioma de la solicitud (Ejemplo 16);
  • líneas 15–17: los idiomas admitidos y el nombre de la cookie: constantes de clase públicas, accesibles desde otras clases ([SetLanguage::LANGUAGES]);
  • líneas 22–24: el idioma de la solicitud: el de la cookie [language] si existe y es admitido; de lo contrario, inglés. [$request->cookies] es el conjunto de cookies enviadas por el navegador (ejemplo 05); [get] devuelve el valor de una cookie o [null]. [in_array], con [true] como tercer parámetro, compara también los tipos ([===]). [setLocale] establece el idioma de la solicitud: es el idioma que utilizan el traductor, nuestros filtros de formato y el filtro [format_currency] de [Twig].

A diferencia de [Laravel], [Symfony] no cifra las cookies: la cookie [language] se transmite en texto plano. Esto no es un problema: no contiene información confidencial y el servidor solo acepta los idiomas admitidos. El siguiente ejemplo vuelve sobre la cuestión de cuánta confianza puede depositarse en una cookie.

5.1.4. Selección del idioma: src/Controller/LanguageController.php

<?php
// src/Controller/LanguageController.php: la elección del 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: guarda la elección en una cookie y luego regresa a la página anterior.
    // requirements: un idioma distinto de en o fr no coincide con la ruta (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));
        // la cookie: un año de vida, ilegible para el JavaScript de la página (httpOnly),
        // nunca enviada con una solicitud POST proveniente de otro sitio (sameSite lax)
        $response->headers->setCookie(Cookie::create(SetLanguage::COOKIE, $code)
            ->withExpires(new \DateTimeImmutable('+1 year'))
            ->withHttpOnly(true)
            ->withSameSite(Cookie::SAMESITE_LAX));
        return $response;
    }

    // la página de la que venimos (encabezado Referer), de la cual conservamos solo la ruta:
    // redirigir a una dirección completa proveniente de la solicitud permitiría
    // enviar al usuario a otro sitio (vulnerabilidad de "open redirect")
    private static function originPage(Request $request): string
    {
        // parse_url divide una URL en sus componentes (ruta, parámetros...)
        $url = parse_url($request->headers->get('Referer', ''));
        $path = $url['path'] ?? '';
        // "//site.com/..." sería entendida por el navegador como una dirección
        // en OTRO sitio: también se rechaza
        if (! str_starts_with($path, '/') || str_starts_with($path, '//')) {
            return '/';
        }
        return isset($url['query']) ? "$path?{$url['query']}" : $path;
    }
}
  • línea 17: la ruta [/language/{code}]. La opción [requirements] (ejemplo 02) limita el parámetro a los dos idiomas admitidos: [/language/de] no corresponde a ninguna ruta y devuelve un error 404;
  • línea 20: la acción responde con una redirección a la página de la que provino el usuario: el usuario regresa a su página en el nuevo idioma;
  • Líneas 23–26: la respuesta contiene una cookie, que el navegador reenviará con cada solicitud. La clase [Cookie] de [Symfony] la describe: [Cookie::create(name, value)] la crea, y cada método de [with...] devuelve una copia modificada (un objeto inmutable; véase el Ejemplo 03): [withExpires], la fecha de expiración (en un año); [withHttpOnly(true)] la hace invisible para el [JavaScript] de la página; [withSameSite(Cookie::SAMESITE_LAX)] impide que el navegador la envíe con una solicitud POST proveniente de otro sitio. ([httpOnly] y [lax] son, dicho sea de paso, los valores predeterminados de [Cookie::create].) [$response->headers->setCookie] la agrega a la respuesta como un encabezado [Set-Cookie];
  • líneas 33–44: la página de origen se especifica mediante el encabezado [Referer] de la solicitud (la versión con error ortográfico, con una sola [r], es la que se usa en el estándar HTTP), que el navegador completa con la URL de la página que contenía el enlace. Pero este encabezado proviene del cliente, que puede poner en él lo que quiera. Redirigir a ciegas a esta dirección convertiría nuestra aplicación en una redirección abierta: un enlace malicioso con el nombre de nuestro dominio podría enviar al usuario a un sitio malicioso. Por lo tanto, conservamos solo la ruta y los parámetros de la URL (la función [parse_url] de [PHP] la descompone en sus componentes en un arreglo asociativo) y rechazamos cualquier ruta que comience con [//], que el navegador interpretaría como la dirección de otro sitio.

5.1.5. Acciones: src/Controller/PagesController.php

<?php
// src/Controller/PagesController.php: las acciones no saben nada del idioma:
// proporcionan datos, las vistas los traducen y los formatean

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),
        ]]);
    }
}

Las acciones son independientes del idioma: proporcionan datos sin procesar (un nombre, una fecha, montos en centavos). La traducción y el formato corren por cuenta de las vistas. La clase [Product] tiene un nombre y un precio en centavos; la extensión [FormatsExtension] es la del Ejemplo 16: su filtro [long_date] escribe una fecha en el formato “completo” del idioma de la solicitud (“Wednesday, September 23, 2026”, “mercredi 23 septembre 2026”), y su filtro [money] escribe un monto.

5.1.6. Traducir en las vistas

<!doctype html>
{# app.request.locale: el idioma de la solicitud, "en" o "fr" #}
<html lang="{{ app.request.locale }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {# el título: el bloque [title] de la página, ya traducido #}
  <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>
  • línea 3: el atributo [lang] de la página indica su idioma a los navegadores, los motores de búsqueda y los lectores de pantalla; [app.request.locale] es el idioma de la solicitud;
  • línea 8: el título de la página lo proporciona la propia página, ya traducido (bloque [title]).
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    {# 'KEY'|trans: la traducción de una clave, en el idioma de la solicitud #}
    <a class="nav-link" href="{{ path('home') }}">{{ 'MENU.HOME'|trans }}</a>
    <a class="nav-link" href="{{ path('products') }}">{{ 'MENU.PRODUCTS'|trans }}</a>
  </div>
  {# el idioma actual aparece resaltado #}
  <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>
  • líneas 4–5: el filtro [trans] traduce una clave al idioma de la solicitud;
  • líneas 9–12: un botón por idioma, que desencadena la acción [/language/{code}]. El idioma actual aparece resaltado ([btn-primary], botón sólido).
{% extends 'layout.html.twig' %}
{% block title %}{{ 'HOME.TITLE'|trans }}{% endblock %}

{% block content %}
  <h1>{{ 'HOME.TITLE'|trans }}</h1>
  {# un parámetro: el parámetro del filtro trans, un arreglo asociativo #}
  <p>{{ 'HOME.HELLO'|trans({name: name}) }}</p>
  {# la fecha, formateada primero (filtro long_date, ver el ejemplo 16), luego pasada como parámetro [date] #}
  <p>{{ 'HOME.DATE'|trans({date: today|long_date}) }}</p>
{% endblock %}
  • línea 2: el bloque [title] traducido para la plantilla;
  • línea 7: los parámetros de un texto se proporcionan en un arreglo asociativo, un parámetro del filtro [trans]; [{name}] se reemplaza por el valor de la clave [name];
  • línea 9: la fecha, formateada en el idioma de la solicitud por el filtro [long_date] y luego pasada 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>
          {# el filtro money del ejemplo 16: el formato depende del idioma #}
          <td class="text-end">{{ product.priceCents|money }}</td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  {# el mensaje en plural: ICU elige la forma según el parámetro n #}
  <p>{{ 'PRODUCTS.COUNT'|trans({n: products|length}) }}</p>
{% endblock %}
  • línea 13: el filtro [money], cuyo resultado depende del idioma;
  • línea 19: el parámetro [n] para la forma plural del mensaje: el número de productos ([length], ejemplo 14). Los nombres de los productos no se traducen: son datos que, en una aplicación real, provendrían de una base de datos.

Fuera de las vistas, el traductor es un servicio de tipo [TranslatorInterface], que una acción o un servicio puede recibir por inyección: [$translator->trans('HOME.HELLO', ['name' => 'Marie'])].

5.1.7. Ejecución

La página de inicio, en inglés (el idioma predeterminado) y luego en francés tras hacer clic en el botón "FR":

Image

Image

La página de productos, en ambos idiomas. Los montos siguen las convenciones de cada idioma:

Image

Image

El cambio de idioma, visto con [curl]. La opción [-H] proporciona el encabezado [Referer] que enviaría el navegador:

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

La redirección lo lleva de vuelta a la página de origen ([Symfony] escribe una URL relativa, que el navegador completa) y la cookie se establece por un año. Un [Referer] que apunta a otro sitio no lo redirige allí: solo se conserva su ruta.

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: /
...

La página [/trap] no existe en nuestro sitio: el usuario recibirá un error 404, pero permanecerá en nuestro sitio. Por último, la página de inicio, solicitada con la cookie [language=en] (opción [-b] de [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>
...

Otra forma de elegir el idioma habría sido leer el encabezado [Accept-Language] del navegador (ejemplo 12; [$request->getPreferredLanguage(['fr', 'en'])] selecciona el mejor idioma entre los admitidos). Con frecuencia se combinan ambas: el idioma del navegador en la primera visita, seguido del idioma que el usuario haya seleccionado. Un tercer método, de uso común con [Symfony], coloca el idioma en la URL ([/en/products]): un parámetro de ruta especial, [{_locale}], establece entonces por sí mismo el idioma de la solicitud. Este caso de estudio se centra en la cookie, con el inglés como idioma predeterminado.