Internacionalização (i18n) no Laravel

1. Fundamentos da Internacionalização no Laravel

A internacionalização (i18n) é o processo de projetar uma aplicação para suportar múltiplos idiomas e regiões sem necessidade de alterações no código-fonte. No Laravel, esse recurso é nativo e extremamente flexível, permitindo que você adapte sua aplicação para audiências globais com mínimo esforço.

A configuração inicial é feita no arquivo config/app.php, onde definimos o locale padrão e o fallback locale:

// config/app.php
return [
    'locale' => 'en',
    'fallback_locale' => 'en',
    'available_locales' => ['en', 'pt_BR', 'es', 'fr'],
];

A estrutura de diretórios para arquivos de tradução fica em resources/lang/. O Laravel suporta dois formatos principais: arrays PHP e arquivos JSON.

2. Criando e Organizando Arquivos de Tradução

Arquivos por chave (arrays PHP)

Crie diretórios para cada idioma e arquivos PHP com arrays associativos:

// resources/lang/pt_BR/messages.php
return [
    'welcome' => 'Bem-vindo ao nosso sistema',
    'goodbye' => 'Até logo!',
    'login' => 'Entrar',
    'logout' => 'Sair',
];

Arquivos JSON para strings curtas

Para projetos que preferem chaves como strings literais:

// resources/lang/pt_BR.json
{
    "Welcome to our application": "Bem-vindo à nossa aplicação",
    "Hello :name": "Olá :name",
    "Login": "Entrar"
}

Boas práticas de organização

  • Use grupos semânticos: auth.php, validation.php, pagination.php
  • Mantenha consistência nas chaves entre todos os idiomas
  • Evite aninhamento excessivo (máximo 2-3 níveis)
  • Prefira arquivos JSON para projetos pequenos e arrays PHP para projetos grandes

3. Recuperando Strings Traduzidas com Helpers e Facades

Função helper __()

echo __('messages.welcome');
// Saída: Bem-vindo ao nosso sistema

echo __('Welcome to our application');
// Saída (JSON): Bem-vindo à nossa aplicação

Função trans() e Facade Lang

use Illuminate\Support\Facades\Lang;

echo trans('messages.welcome');
echo Lang::get('messages.welcome');

Parâmetros de substituição

// resources/lang/pt_BR/messages.php
return [
    'greeting' => 'Olá, :name! Seja bem-vindo ao :app',
];

// No código
echo __('messages.greeting', ['name' => 'Maria', 'app' => 'Laravel']);
// Saída: Olá, Maria! Seja bem-vindo ao Laravel

4. Pluralização e Gênero com trans_choice

O Laravel oferece trans_choice() para lidar com pluralização:

// resources/lang/pt_BR/messages.php
return [
    'apples' => '{0} Nenhuma maçã|{1} Uma maçã|[2,*] :count maçãs',
];

// Uso
echo trans_choice('messages.apples', 0); // Nenhuma maçã
echo trans_choice('messages.apples', 1); // Uma maçã
echo trans_choice('messages.apples', 10, ['count' => 10]); // 10 maçãs

Customizando regras de pluralização

Para idiomas com regras complexas, registre no AppServiceProvider:

// app/Providers/AppServiceProvider.php
use Illuminate\Support\Pluralizer;

public function boot()
{
    Pluralizer::plural(function ($count, $language) {
        if ($language === 'pt_BR') {
            return match (true) {
                $count == 0 => 0,
                $count == 1 => 1,
                default => 2,
            };
        }
    });
}

5. Detecção e Troca Dinâmica de Idioma

Middleware para definição automática de locale

// app/Http/Middleware/SetLocale.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Support\Facades\App;
use Illuminate\Support\Facades\Session;

class SetLocale
{
    public function handle($request, Closure $next)
    {
        $locale = $request->segment(1);

        if (in_array($locale, config('app.available_locales'))) {
            App::setLocale($locale);
            Session::put('locale', $locale);
        } elseif (Session::has('locale')) {
            App::setLocale(Session::get('locale'));
        }

        return $next($request);
    }
}

Registre no Kernel.php:

// app/Http/Kernel.php
protected $middlewareGroups = [
    'web' => [
        // ...
        \App\Http\Middleware\SetLocale::class,
    ],
];

Armazenando preferência no banco de dados

// User model
public function setLocale($locale)
{
    $this->update(['preferred_locale' => $locale]);
    session(['locale' => $locale]);
    app()->setLocale($locale);
}

6. Tradução em Views, Emails e Validação

Diretiva Blade e sintaxe curta

<!-- Usando diretiva @lang -->
<p>@lang('messages.welcome')</p>

<!-- Usando helper PHP no Blade -->
<p>{{ __('messages.welcome') }}</p>

<!-- Com parâmetros -->
<p>{{ __('messages.greeting', ['name' => $user->name]) }}</p>

Tradução de mensagens de validação

// resources/lang/pt_BR/validation.php
return [
    'required' => 'O campo :attribute é obrigatório.',
    'email' => 'O :attribute deve ser um endereço de e-mail válido.',
    'custom' => [
        'email' => [
            'required' => 'Precisamos do seu endereço de e-mail!',
        ],
    ],
];

Internacionalização de e-mails

use Illuminate\Support\Facades\Mail;

Mail::locale('pt_BR')->to($user->email)->send(new WelcomeMail($user));

// No Mailable
class WelcomeMail extends Mailable
{
    public function build()
    {
        return $this->from(config('mail.from.address'))
                    ->subject(__('messages.welcome_email_subject'))
                    ->view('emails.welcome');
    }
}

7. Ferramentas Avançadas e Pacotes de Terceiros

Pacote mcamara/laravel-localization

composer require mcamara/laravel-localization

Este pacote oferece detecção automática de idioma, URLs amigáveis e suporte a rotas localizadas:

// Exemplo de rota localizada
Route::group([
    'prefix' => LaravelLocalization::setLocale(),
    'middleware' => ['localeSessionRedirect', 'localizationRedirect']
], function () {
    Route::get('/', 'HomeController@index');
});

Cache de traduções

php artisan lang:cache

Este comando compila todos os arquivos de tradução em um único arquivo cache, melhorando significativamente a performance em produção.

Exportação para planilhas

Para gerenciar traduções com equipes não-técnicas, considere pacotes como barryvdh/laravel-translation-manager que permitem exportar/importar traduções em formato CSV ou XLSX.

Conclusão

A internacionalização no Laravel é robusta e flexível, permitindo desde implementações simples com poucos idiomas até sistemas complexos com dezenas de línguas. A combinação de arquivos de tradução, helpers intuitivos, pluralização inteligente e suporte a middleware torna o processo de globalização da sua aplicação uma tarefa agradável e bem documentada.

Lembre-se sempre de planejar a i18n desde o início do projeto, manter os arquivos de tradução organizados e testar exaustivamente cada idioma suportado. Com as ferramentas certas e boas práticas, sua aplicação Laravel estará pronta para conquistar o mundo.

Referências