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”:


A página de produtos, nos dois idiomas. Os valores monetários 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:
| curl -i -H "Referer: http://localhost:8000/products" http://localhost:8000/language/en
|
| 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
|
| 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.