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.

[Laravel] tiene su propio sistema de traducción, que ya vimos en el ejemplo 09 para los mensajes de validación. Acepta dos tipos de diccionarios, almacenados en la carpeta [lang]: archivos [PHP], uno por tema y por idioma ([lang/fr/validation.php]), que devuelven un arreglo de claves; y archivos JSON, uno por idioma ([lang/fr.json]), donde cada clave es una cadena arbitraria. Utilizamos el segundo formato: salvo por la sintaxis de los parámetros, son los mismos diccionarios que los de las versiones [ASP.NET Core MVC], [NestJS], [Spring MVC] y [Flask] del caso de estudio, y su formato se puede leer y escribir sin herramientas especiales. El formato de fechas e importes sigue siendo el mismo que en el ejemplo 16.

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

22-i18n/
├── app/
│   ├── Helpers/
│   │   └── Formats.php
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── LanguageController.php
│   │   │   └── PagesController.php
│   │   └── Middleware/
│   │       └── SetLanguage.php
│   └── Models/
│       └── Product.php
├── lang/
│   ├── en.json
│   └── fr.json
├── resources/
│   └── views/
│       ├── fragments/
│       │   └── navbar.blade.php
│       ├── layout.blade.php
│       └── pages/
│           ├── home.blade.php
│           └── products.blade.php
└── ...

5.1.1. Los diccionarios

El archivo [lang/fr.json]:

{
    "MENU.HOME": "Accueil",
    "MENU.PRODUCTS": "Produits",
    "HOME.TITLE": "Bienvenue",
    "HOME.HELLO": "Bonjour :name !",
    "HOME.DATE": "Nous sommes le :date.",
    "PRODUCTS.TITLE": "Nos produits",
    "PRODUCTS.NAME": "Produit",
    "PRODUCTS.PRICE": "Prix",
    "PRODUCTS.COUNT": ":n produit(s) au catalogue."
}

Un diccionario JSON es un objeto en el que cada par asocia una clave con su texto. Las claves se agrupan por tema según su prefijo: el texto de menú “Accueil” tiene la clave [MENU.HOME]. Un texto puede contener marcadores de posición, escritos como [:name], que se reemplazan durante la traducción. (Los diccionarios de las otras versiones del caso de estudio anidan los objetos JSON — [{"MENU": {"HOME": "Accueil"}}] — y escriben los parámetros como [{name}]; los de [Laravel] son “planos” y utilizan la sintaxis [:name].) El archivo [lang/en.json] tiene exactamente las mismas claves:

{
    "MENU.HOME": "Home",
    "MENU.PRODUCTS": "Products",
    "HOME.TITLE": "Welcome",
    "HOME.HELLO": "Hello :name!",
    "HOME.DATE": "Today is :date.",
    "PRODUCTS.TITLE": "Our products",
    "PRODUCTS.NAME": "Product",
    "PRODUCTS.PRICE": "Price",
    "PRODUCTS.COUNT": ":n product(s) in the catalogue."
}

Si falta una clave en el diccionario JSON del idioma actual, se busca en los archivos [PHP] de la carpeta de ese idioma ([lang/fr/*.php], ejemplo 09) y luego en los del idioma de respaldo ([APP_FALLBACK_LOCALE], inglés de forma predeterminada). No existe un diccionario de respaldo (JSON): una clave ausente del diccionario (JSON) del idioma actual y de estos archivos se muestra tal cual. De este modo, cualquier omisión resulta visible de inmediato en pantalla.

5.1.2. El idioma de cada solicitud: app/Http/Middleware/SetLanguage.php

<?php
// app/Http/Middleware/SetLanguage.php: el idioma de cada solicitud

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Symfony\Component\HttpFoundation\Response;

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 handle(Request $request, Closure $next): Response
    {
        $language = $request->cookie(self::COOKIE);
        App::setLocale(in_array($language, self::LANGUAGES, true) ? $language : self::LANGUAGES[0]);
        return $next($request);
    }
}
  • líneas 14–16: los idiomas admitidos y el nombre de la cookie: constantes de clase públicas, accesibles desde otras clases ([SetLanguage::LANGUAGES]);
  • líneas 21–22: antes de cada acción, el idioma de la solicitud: el idioma especificado en la cookie [language] si existe y es admitido; de lo contrario, inglés. [$request->cookie(name)] devuelve el valor de una cookie enviada por el navegador, o [null]. [in_array], con [true] como tercer parámetro, compara también los tipos ([===]). [App::setLocale] (ejemplo 16) establece el idioma de la aplicación para la solicitud: es el idioma utilizado para las traducciones y el formato.

5.1.3. La configuración: bootstrap/app.php

<?php
// bootstrap/app.php: la aplicación del ejemplo 22

use App\Http\Middleware\SetLanguage;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Support\Facades\Blade;

(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        // la ruta que sirve Bootstrap (véase el ejemplo 15)
        then: fn () => require __DIR__.'/../../common/bootstrap.php')
    ->withMiddleware(function (Middleware $middleware): void {
        // la cookie [language] no está cifrada: no contiene nada secreto, y
        // el servidor acepta solo los idiomas admitidos
        $middleware->encryptCookies(except: [SetLanguage::COOKIE]);
        // el idioma de cada solicitud: el de la cookie [language], inglés en caso contrario
        $middleware->web(append: SetLanguage::class);
    })
    ->withExceptions()
    ->booted(function () {
        // en las vistas: @money($price) (véase el ejemplo 16)
        Blade::directive('money', fn (string $expression) =>
            "<?php echo e(\\App\\Helpers\\Formats::money($expression)); ?>");
    })
    ->create();
  • Línea 19: de forma predeterminada, [Laravel] cifra todas las cookies que establece y descifra las que recibe (este es el papel del middleware [EncryptCookies] del grupo [web]; véase el ejemplo 20): el usuario no puede leer ni crear una cookie cifrada. La cookie [language] no contiene información secreta, y el servidor solo acepta los idiomas admitidos: la excluimos del cifrado, lo que nos permite verla (y crearla) con [curl]. El ejemplo siguiente volverá sobre este cifrado;
  • línea 21: el middleware de idioma, al final del grupo [web] (ejemplo 16): se ejecuta después de [EncryptCookies] y, por lo tanto, lee cookies que ya han sido descifradas;
  • líneas 26–27: la directiva [@money] del ejemplo 16.

La clase [App\Helpers\Formats] es la del ejemplo 16, con una diferencia: la fecha se formatea en el formato “largo” de cada idioma:

<?php
// app/Helpers/Formats.php: fechas y montos, formateados en el idioma de la solicitud (véase el ejemplo 16)

namespace App\Helpers;

use Brick\Math\BigDecimal;
use Carbon\CarbonInterface;
use Illuminate\Support\Facades\App;
use Illuminate\Support\Number;

class Formats
{
    // un monto en euros
    public static function money(BigDecimal $amount): string
    {
        return Number::currency($amount->toFloat(), in: 'EUR', locale: App::getLocale());
    }

    // una fecha con palabras completas. El formato "dddd LL": el día de la semana y luego la
    // fecha en el formato "largo" del idioma: "mercredi 23 septembre 2026" en francés,
    // "Wednesday September 23, 2026" en inglés
    public static function longDate(CarbonInterface $day): string
    {
        return $day->locale(App::getLocale())->isoFormat('dddd LL');
    }
}
  • Línea 24: [LL] es un formato localizado: cada idioma tiene el suyo ([23 septembre 2026] en francés, [September 23, 2026] en inglés), mientras que [D MMMM YYYY] impondría el orden francés a todos los idiomas. [dddd] agrega el día de la semana.

5.1.4. Selección del idioma: app/Http/Controllers/LanguageController.php

<?php
// app/Http/Controllers/LanguageController.php: la elección del idioma

namespace App\Http\Controllers;

use App\Http\Middleware\SetLanguage;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class LanguageController
{
    // GET /language/fr: almacena la elección en una cookie y luego regresa a la página anterior
    public function change(Request $request, string $code): RedirectResponse
    {
        abort_unless(in_array($code, SetLanguage::LANGUAGES, true), 404);
        // la cookie: un año de vida (en minutos), ilegible para el JavaScript de la
        // página (httpOnly), nunca enviada con una solicitud POST proveniente de otro sitio (sameSite)
        return redirect(self::originPage($request))
            ->withCookie(cookie(SetLanguage::COOKIE, $code, 365 * 24 * 60, httpOnly: true, sameSite: 'lax'));
    }

    // 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 (falla de "redirección abierta", open redirect)
    private static function originPage(Request $request): string
    {
        // parse_url divide una URL en sus componentes (ruta, parámetros...)
        $url = parse_url($request->header('Referer', ''));
        $path = $url['path'] ?? '';
        // "//site.com/..." sería entendida por el navegador como una dirección
        // de 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 15: un código de idioma desconocido: 404;
  • líneas 18–19: la acción responde con una redirección a la página de la que venía el usuario; este vuelve a esa página en el nuevo idioma. La respuesta incluye una cookie, que el navegador enviará de vuelta con cada solicitud: la función [cookie] la crea y el método [withCookie] la agrega a la respuesta. Sus parámetros: el nombre, el valor, la duración en minutos (un año) y dos parámetros con nombre: [httpOnly: true] la hace invisible para el [JavaScript] de la página; [sameSite: 'lax'] impide que el navegador la envíe con una solicitud POST originada en otro sitio;
  • líneas 25–36: la página de origen la especifica el encabezado [Referer] de la solicitud (la grafía incorrecta, con una sola [r], es la que se usa en el estándar HTTP), que el navegador rellena 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 *open redirect*: 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, almacenándolos en un arreglo asociativo), y rechazamos cualquier ruta que comience con [//], que el navegador interpretaría como la dirección de otro sitio. [Laravel] también ofrece [redirect()->back()] (o [back()]), que redirige a la página anterior almacenada en la sesión (ejemplo 20), y no al encabezado [Referer]: lo utilizaremos en el caso de estudio.

5.1.5. Acciones: app/Http/Controllers/PagesController.php

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

namespace App\Http\Controllers;

use App\Models\Product;
use Brick\Math\BigDecimal;
use Carbon\CarbonImmutable;
use Illuminate\View\View;

class PagesController
{
    public function home(): View
    {
        return view('pages.home', ['name' => 'Marie',
            'today' => CarbonImmutable::create(2026, 9, 23)]);
    }

    public function products(): View
    {
        return view('pages.products', ['products' => [
            new Product('Keyboard', BigDecimal::of('25')),
            new Product('Mouse', BigDecimal::of('12.5')),
            new Product('Screen', BigDecimal::of('1149')),
        ]]);
    }
}

Las acciones son independientes del idioma: proporcionan datos sin procesar (un nombre, una fecha, importes). La traducción y el formato los manejan las vistas.

5.1.6. Traducción en las vistas

<!doctype html>
{{-- app()->getLocale(): el idioma de la solicitud, "en" o "fr" --}}
<html lang="{{ app()->getLocale() }}">
<head>
  <meta charset="utf-8">
  {{-- el título: la sección [title] de la página, ya traducida --}}
  <title>@yield('title')</title>
  <link rel="stylesheet" href="{{ route('bootstrap', 'css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3">
    @include('fragments.navbar')
    <main>
      @yield('content')
    </main>
  </div>
</body>
</html>
  • línea 3: el atributo [lang] de la página especifica su idioma a los navegadores, los motores de búsqueda y los lectores de pantalla;
  • línea 7: el título de la página lo proporciona la propia página, ya traducido (sección [title]).
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    {{-- __('KEY'): la traducción de una clave, en el idioma de la solicitud --}}
    <a class="nav-link" href="/">{{ __('MENU.HOME') }}</a>
    <a class="nav-link" href="/products">{{ __('MENU.PRODUCTS') }}</a>
  </div>
  {{-- the current language is highlighted --}}
  <div class="btn-group btn-group-sm">
    @foreach (['fr', 'en'] as $code)
      <a @class(['btn', 'btn-primary' => app()->isLocale($code), 'btn-outline-primary' => ! app()->isLocale($code)])
         href="/language/{{ $code }}">{{ strtoupper($code) }}</a>
    @endforeach
  </div>
</nav>
  • líneas 4–5: la función [__] (con dos guiones bajos) devuelve la traducción de una clave en el 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): [app()->isLocale($code)] verifica el idioma de la solicitud.
@extends('layout')
@section('title', __('HOME.TITLE'))

@section('content')
  <h1>{{ __('HOME.TITLE') }}</h1>
  {{-- un parámetro: el segundo parámetro de __, un arreglo --}}
  <p>{{ __('HOME.HELLO', ['name' => $name]) }}</p>
  {{-- la fecha, formateada primero y luego pasada como el parámetro [date] --}}
  <p>{{ __('HOME.DATE', ['date' => App\Helpers\Formats::longDate($today)]) }}</p>
@endsection
  • Línea 2: la sección [title], traducida, para la plantilla;
  • línea 7: los parámetros de un texto se proporcionan en un arreglo asociativo, el segundo parámetro de [__]; [:name] se reemplaza por el valor de la clave [name];
  • línea 9: la fecha, formateada en el idioma de la solicitud mediante el método [longDate] y luego pasada como parámetro. Aquí no se puede utilizar una directiva ([@longDate]): escribe directamente en la página y no devuelve un valor.
@extends('layout')
@section('title', __('PRODUCTS.TITLE'))

@section('content')
  <h1>{{ __('PRODUCTS.TITLE') }}</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>{{ __('PRODUCTS.NAME') }}</th><th class="text-end">{{ __('PRODUCTS.PRICE') }}</th></tr></thead>
    <tbody>
      @foreach ($products as $product)
        <tr>
          <td>{{ $product->name }}</td>
          <td class="text-end">@money($product->price)</td>
        </tr>
      @endforeach
    </tbody>
  </table>
  <p>{{ __('PRODUCTS.COUNT', ['n' => count($products)]) }}</p>
@endsection
  • Línea 17: un parámetro calculado. Los nombres de los productos, en cambio, no se traducen: son datos que, en una aplicación real, provendrían de una base de datos.

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 importes 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
HTTP/1.1 302 Found
Location: http://localhost:8000/products
Set-Cookie: language=en; expires=Sun, 26 Sep 2027 16:18:24 GMT; Max-Age=31536000; path=/; httponly; samesite=lax
...

La redirección lo lleva de vuelta a la página de origen, y la cookie se establece por un año, en texto plano. 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: http://localhost:8000/trap
...
HTTP/1.1 302 Found
Location: http://localhost:8000
...

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]); como el inglés es el idioma predeterminado, la página es la misma que sin la cookie:

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

Otra forma de seleccionar el idioma habría sido leer el encabezado [Accept-Language] del navegador (ejemplo 12). Ambas suelen combinarse: el idioma del navegador en la primera visita, seguido del idioma que el usuario ha seleccionado. Este caso de estudio se centra en la cookie, con el inglés como idioma predeterminado.