Skip to content

5. Internacionalização

Uma aplicação internacionalizada exibe seu texto 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, mas chaves ([MENU.HOME]), e um dicionário para cada idioma associa um texto a cada chave. O idioma selecionado é armazenado em um cookie.

[Laravel] tem seu próprio sistema de tradução, que já encontramos no exemplo 09 para as mensagens de validação. Ele aceita dois tipos de dicionários, armazenados na pasta [lang]: arquivos [PHP], um por tema e por idioma ([lang/fr/validation.php]), que retornam um array de chaves; e arquivos JSON, um por idioma ([lang/fr.json]), em que cada chave é uma string arbitrária. Usamos o segundo formato: exceto pela sintaxe dos parâmetros, são os mesmos dicionários das versões [ASP.NET Core MVC], [NestJS], [Spring MVC] e [Flask] do estudo de caso, e seu formato pode ser lido e escrito sem nenhuma ferramenta especial. A formatação de datas e valores monetários permanece a mesma do exemplo 16.

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

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. Os dicionários

O arquivo [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."
}

Um dicionário JSON é um objeto em que cada par associa uma chave a seu texto. As chaves são agrupadas por tema com base em seu prefixo: o texto de menu “Accueil” tem a chave [MENU.HOME]. Um texto pode conter placeholders, escritos como [:name], que são substituídos durante a tradução. (Os dicionários das outras versões do estudo de caso aninham os objetos JSON — [{"MENU": {"HOME": "Accueil"}}] — e escrevem os parâmetros como [{name}]; os do [Laravel] são “planos” e usam a sintaxe [:name].) O arquivo [lang/en.json] tem exatamente as mesmas chaves:

{
    "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."
}

Se uma chave estiver ausente do dicionário JSON do idioma atual, ela é procurada nos arquivos [PHP] da pasta desse idioma ([lang/fr/*.php], exemplo 09) e, em seguida, nos do idioma de fallback ([APP_FALLBACK_LOCALE], inglês por padrão). Não há dicionário (JSON) de reserva: uma chave ausente do dicionário (JSON) do idioma atual e desses arquivos é exibida tal como está. Assim, qualquer omissão fica imediatamente visível na tela.

5.1.2. O idioma de cada requisição: app/Http/Middleware/SetLanguage.php

<?php
// app/Http/Middleware/SetLanguage.php: o idioma de cada requisição

namespace App\Http\Middleware;

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

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 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);
    }
}
  • linhas 14–16: os idiomas suportados e o nome do cookie: constantes de classe públicas, acessíveis de outras classes ([SetLanguage::LANGUAGES]);
  • linhas 21–22: antes de cada ação, o idioma da requisição: o idioma especificado no cookie [language] se ele existir e for suportado; caso contrário, inglês. [$request->cookie(name)] retorna o valor de um cookie enviado pelo navegador, ou [null]. [in_array], com [true] como terceiro parâmetro, também compara os tipos ([===]). [App::setLocale] (exemplo 16) define o idioma da aplicação para a requisição: é o idioma usado para as traduções e a formatação.

5.1.3. A configuração: bootstrap/app.php

<?php
// bootstrap/app.php: a aplicação do exemplo 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',
        // a rota que serve o Bootstrap (veja o exemplo 15)
        then: fn () => require __DIR__.'/../../common/bootstrap.php')
    ->withMiddleware(function (Middleware $middleware): void {
        // o cookie [language] não é criptografado: ele não contém nada secreto, e
        // o servidor aceita apenas os idiomas suportados
        $middleware->encryptCookies(except: [SetLanguage::COOKIE]);
        // o idioma de cada requisição: o do cookie [language], inglês caso contrário
        $middleware->web(append: SetLanguage::class);
    })
    ->withExceptions()
    ->booted(function () {
        // nas views: @money($price) (veja o exemplo 16)
        Blade::directive('money', fn (string $expression) =>
            "<?php echo e(\\App\\Helpers\\Formats::money($expression)); ?>");
    })
    ->create();
  • Linha 19: por padrão, o [Laravel] criptografa todos os cookies que define e descriptografa os que recebe (esse é o papel do middleware [EncryptCookies] do grupo [web]; veja o exemplo 20): o usuário não pode ler nem criar um cookie criptografado. O cookie [language] não contém nenhuma informação secreta, e o servidor aceita apenas idiomas suportados: nós o excluímos da criptografia, o que nos permite visualizá-lo (e criá-lo) usando o [curl]. O exemplo seguinte voltará a essa criptografia;
  • linha 21: o middleware de idioma, no final do grupo [web] (exemplo 16): ele é executado depois de [EncryptCookies] e, portanto, lê cookies que já foram descriptografados;
  • linhas 26–27: a diretiva [@money] do exemplo 16.

A classe [App\Helpers\Formats] é a do exemplo 16, com uma diferença: a data é formatada no formato “longo” de cada idioma:

<?php
// app/Helpers/Formats.php: datas e valores, formatados no idioma da requisição (veja o exemplo 16)

namespace App\Helpers;

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

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

    // uma data por extenso. O formato "dddd LL": o dia da semana, depois a
    // data no formato "longo" do idioma: "mercredi 23 septembre 2026" em francês,
    // "Wednesday September 23, 2026" em inglês
    public static function longDate(CarbonInterface $day): string
    {
        return $day->locale(App::getLocale())->isoFormat('dddd LL');
    }
}
  • Linha 24: [LL] é um formato localizado: cada idioma tem o seu ([23 septembre 2026] em francês, [September 23, 2026] em inglês), ao passo que [D MMMM YYYY] imporia a ordem francesa a todos os idiomas. [dddd] acrescenta o dia da semana.

5.1.4. Seleção do idioma: app/Http/Controllers/LanguageController.php

<?php
// app/Http/Controllers/LanguageController.php: a escolha do idioma

namespace App\Http\Controllers;

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

class LanguageController
{
    // GET /language/fr: armazena a escolha em um cookie e depois volta à página anterior
    public function change(Request $request, string $code): RedirectResponse
    {
        abort_unless(in_array($code, SetLanguage::LANGUAGES, true), 404);
        // o cookie: um ano de vida (em minutos), ilegível pelo JavaScript da
        // página (httpOnly), nunca enviado com uma requisição POST vinda de outro site (sameSite)
        return redirect(self::originPage($request))
            ->withCookie(cookie(SetLanguage::COOKIE, $code, 365 * 24 * 60, httpOnly: true, sameSite: 'lax'));
    }

    // a página de onde viemos (cabeçalho Referer), da qual mantemos 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->header('Referer', ''));
        $path = $url['path'] ?? '';
        // "//site.com/..." seria entendido pelo navegador como um endereço
        // em OUTRO site: também recusado
        if (! str_starts_with($path, '/') || str_starts_with($path, '//')) {
            return '/';
        }
        return isset($url['query']) ? "$path?{$url['query']}" : $path;
    }
}
  • linha 15: um código de idioma desconhecido: 404;
  • linhas 18–19: a ação responde com um redirecionamento para a página de onde o usuário veio; o usuário é levado de volta a essa página no novo idioma. A resposta inclui um cookie, que o navegador devolverá a cada requisição: a função [cookie] o cria, e o método [withCookie] o adiciona à resposta. Seus parâmetros: o nome, o valor, a duração em minutos (um ano) e dois parâmetros nomeados: [httpOnly: true] o torna invisível para o [JavaScript] da página; [sameSite: 'lax'] impede que o navegador o envie com uma requisição POST originada de outro site;
  • linhas 25–36: a página de origem é especificada 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 *open redirect*: 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, armazenando-os em um array associativo) e rejeitamos qualquer caminho que comece com [//], que o navegador interpretaria como o endereço de outro site. [Laravel] também fornece [redirect()->back()] (ou [back()]), que redireciona para a página anterior armazenada na sessão (exemplo 20), e não para o cabeçalho [Referer]: usaremos isso no estudo de caso.

5.1.5. Ações: app/Http/Controllers/PagesController.php

<?php
// app/Http/Controllers/PagesController.php: as actions não sabem nada sobre o idioma:
// elas fornecem dados, as views os traduzem e os formatam

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

As ações são independentes do idioma: elas fornecem dados brutos (um nome, uma data, valores monetários). A tradução e a formatação ficam por conta das views.

5.1.6. Traduzir nas views

<!doctype html>
{{-- app()->getLocale(): the language of the request, "en" or "fr" --}}
<html lang="{{ app()->getLocale() }}">
<head>
  <meta charset="utf-8">
  {{-- the title: the [title] section of the page, already translated --}}
  <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>
  • linha 3: o atributo [lang] da página especifica seu idioma para navegadores, mecanismos de busca e leitores de tela;
  • linha 7: o título da página é fornecido pela própria página, já traduzido (seção [title]).
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    {{-- __('KEY'): the translation of a key, in the language of the request --}}
    <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>
  • linhas 4–5: a função [__] (com dois sublinhados) retorna a tradução de uma chave no idioma da requisição;
  • Linhas 9–12: um botão por idioma, que dispara a ação [/language/{code}]. O idioma atual é destacado ([btn-primary], botão sólido): [app()->isLocale($code)] verifica o idioma da requisição.
@extends('layout')
@section('title', __('HOME.TITLE'))

@section('content')
  <h1>{{ __('HOME.TITLE') }}</h1>
  {{-- a parameter: the second parameter of __, an array --}}
  <p>{{ __('HOME.HELLO', ['name' => $name]) }}</p>
  {{-- the date, formatted first, then passed as the [date] parameter --}}
  <p>{{ __('HOME.DATE', ['date' => App\Helpers\Formats::longDate($today)]) }}</p>
@endsection
  • Linha 2: a seção [title], traduzida, para o template;
  • linha 7: os parâmetros de um texto são fornecidos em um array associativo, o segundo parâmetro de [__]; [:name] é substituído pelo valor da chave [name];
  • linha 9: a data, formatada no idioma da requisição com o método [longDate] e depois passada como parâmetro. Uma diretiva ([@longDate]) não pode ser usada aqui: ela escreve diretamente na página e não retorna um 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
  • Linha 17: um parâmetro calculado. Os nomes dos produtos, porém, não são traduzidos: são dados que, em uma aplicação real, viriam de um banco de dados.

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 monetários 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
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
...

O redirecionamento leva de volta à página de origem, e o cookie é definido por um ano, em texto simples. Um [Referer] que aponta 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: http://localhost:8000/trap
...
HTTP/1.1 302 Found
Location: http://localhost:8000
...

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]); como o inglês é o idioma padrão, a página é a mesma que sem o 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>
...

Outra maneira de selecionar o idioma teria sido ler o cabeçalho [Accept-Language] do navegador (exemplo 12). Os dois costumam ser combinados: o idioma do navegador na primeira visita, seguido do idioma que o usuário selecionou. Este estudo de caso concentra-se no cookie, com o inglês como padrão.