Laravel Localization

Tempo de leitura: 4 minutos

A Localização (Localization – L10n) no Laravel é o processo de adaptar sua aplicação para diferentes idiomas e convenções regionais, proporcionando uma experiência de usuário personalizada e globalizada. O Laravel simplifica a gestão de traduções, suportando strings básicas, substituição de placeholders e regras complexas de pluralização.

1. ⚙️ Estrutura e Configuração de Idiomas

O Laravel armazena todas as traduções em arquivos de linguagem, geralmente como arrays PHP ou JSON.

A. Diretórios de Idiomas

Por padrão, as traduções residem no diretório lang/. Cada idioma suportado (locale) deve ter seu próprio subdiretório.

lang/en/: Arquivos de tradução em Inglês.
lang/pt-BR/: Arquivos de tradução em Português Brasileiro.

O Laravel usa esses diretórios para buscar a string correta com base no locale ativo.

B. Configurando o Locale Padrão

O idioma padrão é definido no arquivo config/app.php:

PHP

// config/app.php
'locale' => 'pt-BR', // Idioma padrão da aplicação

C. Alterando o Locale em Tempo de Execução

Você pode mudar o idioma ativo para a requisição atual, tipicamente em um Middleware ou no Controller.

PHP

use Illuminate\Support\Facades\App;

// Altera o locale para 'en'
App::setLocale('en');

// Opcional: Obtém o locale atual
$currentLocale = App::currentLocale();

2. 📝 Criando e Acessando Traduções

O Laravel suporta dois formatos de arquivos para tradução: Arquivos de Array PHP e Arquivos JSON.

A. Arquivos de Array PHP (Chaves Aninhadas)

As traduções são armazenadas em arquivos dentro do diretório do idioma (ex: lang/pt-BR/messages.php).

PHP

// lang/pt-BR/messages.php
return [
    'welcome' => 'Bem-vindo ao nosso site!',
    'greeting' => 'Olá, :name!', // :name é um placeholder
];

Acessando a Tradução (__ ou trans):

A função helper __('chave.aninhada') (ou trans()) busca a string correspondente:

PHP

// 1. Acesso simples
$welcome = __('messages.welcome'); // Retorna 'Bem-vindo ao nosso site!'

// 2. Com substituição de placeholder
$greeting = __('messages.greeting', ['name' => $user->name]); 
// Retorna 'Olá, João!'

B. Arquivos JSON (Chave = String Original)

O formato JSON é ideal para strings mais longas e frontend. O arquivo é nomeado apenas pelo código do idioma (ex: lang/pt-BR.json).

JSON

// lang/pt-BR.json
{
    "Welcome to our website!": "Bem-vindo ao nosso site!",
    "The page you requested was not found.": "A página solicitada não foi encontrada."
}

Acessando a Tradução JSON:

Você usa a própria string original em inglês como chave, e o Laravel retorna a tradução correspondente no locale ativo.

PHP

$translated = __('Welcome to our website!');

3. 🍎 Pluralização de Linguagem

Lidar com plurais é complexo, pois as regras variam de idioma para idioma (ex: inglês tem 2 formas; russo, 4). O Laravel usa as regras do padrão CLDR (Unicode Common Locale Data Repository) para gerenciar isso via trans_choice.

A. Definição da Regra

As regras de pluralização são definidas no arquivo de tradução usando a sintaxe de pluralização do Gettext, separando as formas com o caractere pipe (|).

PHP

// lang/en/messages.php
'apples' => '{0} No apples|{1} One apple|{2} Two apples|[3,*] :count apples',
// Alternativamente, a sintaxe compacta:
// 'apples' => '{count} apple|{count} apples'

B. Uso de `trans_choice`

A função trans_choice() busca a regra e aplica a forma correta com base no número ($count).

PHP

$count = 5;
$text = trans_choice('messages.apples', $count, ['count' => $count]);
// Retorna: "5 apples" (Se o locale for 'en')

4. 🗂️ Publicando Arquivos de Idioma do Laravel Core

O Laravel core (validação, paginação, autenticação) possui strings padrão. Para traduzir essas strings ou personalizá-las, você publica os arquivos padrão.

Bash

# Publica os arquivos de idioma do Laravel core para personalização
php artisan lang:publish

Este comando criará diretórios lang/{locale}/ contendo arquivos como validation.php, auth.php, etc., que você pode editar.

5. 🛣️ Localização em Rotas

Para permitir que o usuário defina o idioma via URL (ex: /pt-BR/posts), você pode capturar o locale como um parâmetro de rota e definir o idioma globalmente.

PHP

Route::group(['middleware' => 'web'], function () {
    Route::get('{locale}/{path?}', function ($locale, $path = null) {
        if (in_array($locale, ['en', 'pt-BR', 'es'])) {
            App::setLocale($locale);
        } else {
            return redirect()->to(App::currentLocale() . '/' . $path);
        }
        // Continua o roteamento para a aplicação principal
        return app('router')->handle(request());
    })->where('path', '.*')->name('localize');
});

✅ Conclusão Laravel Localization

Laravel Localization: A localização é um recurso fundamental para atingir um público global. O Laravel oferece um sistema de tradução robusto, suportando arquivos de array PHP e JSON, além da funcionalidade essencial de pluralização via trans_choice. Ao utilizar o helper __ ou trans em sua aplicação e gerenciar o locale com App::setLocale(), você garante que o conteúdo seja adaptado corretamente ao idioma do seu usuário.

Mas antes de dominar o Laravel, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no Laravel, você precisará dominar as seguintes tecnologias: