Skip to main content

i18n em Laravel: guia completo de internacionalização e localização

Do primeiro arquivo de localidade à produção: configure o sistema de tradução do Laravel, trate a pluralização, corrija o erro de fallback JSON e adicione cadeias inteligentes às variantes.

1

Compreender o sistema de tradução do Laravel

Laravel inclui um sistema que aceita dois formatos: listas PHP e JSON. Os arquivos PHP utilizam chaves aninhadas por funcionalidade —auth.failed e validation.required—. Os JSON utilizam a string de origem como chave, o que é mais simples, mas não permite aninhamento.

Terminal
composer create-project laravel/laravel my-app
cd my-app

# Laravel includes i18n out of the box
# No extra packages needed for basic usage
O sistema reside no diretório lang/ —Laravel 9 ou posterior— ou resources/lang/ —Laravel 8 e anterior—. O framework o detecta automaticamente. Se ambos existirem, lang/ tem prioridade.
2

Configurar as configurações regionais

Defina as localidades predefinida e de fallback em config/app.php. A de fallback é utilizada quando falta uma chave na ativa. Configure as localidades compatíveis e adicione middleware para detectar e definir a preferência do usuário.

config/app.php
// config/app.php
return [
    'locale' => 'en',            // Default locale
    'fallback_locale' => 'en',   // Fallback when key is missing
    'faker_locale' => 'en_US',

    // Available locales (for your language switcher)
    'available_locales' => ['en', 'de', 'ja', 'es', 'fr', 'pt-BR'],
];
app/Http/Middleware/SetLocale.php
// app/Http/Middleware/SetLocale.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class SetLocale
{
    public function handle(Request $request, Closure $next)
    {
        $locale = $request->segment(1); // e.g. /de/about

        if (in_array($locale, config('app.available_locales'))) {
            app()->setLocale($locale);
        }

        return $next($request);
    }
}
3

Utilizar funções de tradução

Laravel oferece três formas: a função auxiliar __() —recomendada—, trans() e a diretiva Blade @lang. Todas aceitam a chave e parâmetros opcionais. Utilize __() no código PHP e nos modelos Blade e @lang quando não precisar de escapar HTML.

lang/en/messages.php
// lang/en/messages.php
return [
    'welcome' => 'Welcome to our application',
    'greeting' => 'Hello, :name!',
    'nav' => [
        'home' => 'Home',
        'about' => 'About',
        'settings' => 'Settings',
    ],
];

// lang/de/messages.php
return [
    'welcome' => 'Willkommen in unserer Anwendung',
    'greeting' => 'Hallo, :name!',
    'nav' => [
        'home' => 'Startseite',
        'about' => 'Über uns',
        'settings' => 'Einstellungen',
    ],
];
Prefira __() a trans() em código novo. __() funciona com arquivos PHP e JSON, enquanto trans() só funciona com PHP. A diretiva @lang equivale a {'{ __() }'} nos modelos Blade, com sintaxe ligeiramente mais simples.
4

Tratar a pluralização

Laravel utiliza formas separadas por barras verticais. A mais simples é 'apples' => 'There is one apple|There are many apples'. Para intervalos explícitos, utilize 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. trans_choice() ou Str::plural() seleciona a forma segundo o número.

lang/en.json
// lang/en.json
{
    "Welcome back!": "Welcome back!",
    "You have :count new notifications": "You have :count new notifications",
    "Copyright :year :company": "Copyright :year :company"
}

// lang/de.json
{
    "Welcome back!": "Willkommen zurück!",
    "You have :count new notifications": "Sie haben :count neue Benachrichtigungen",
    "Copyright :year :company": "Copyright :year :company"
}
A pluralização integrada trata corretamente apenas regras simples one/other na maioria dos idiomas. Em regras complexas —árabe com 6 formas, russo com 4 e polonês com 3—, deve definir todas as categorias CLDR necessárias. Sem elas, os usuários veem texto gramaticalmente errado.
5

Adicionar cadeias de fallback regional

O fallback integrado do Laravel só passa da localidade ativa para fallback_locale, sem etapa intermediária. Um usuário pt-BR com uma chave em falta vê inglês em vez de pt-PT. laravel-locale-chain corrige isso ao combinar profundamente traduções de uma cadeia durante o carregamento.

resources/views/example.blade.php
{{-- Simple translation --}}
<h1>{{ __('messages.welcome') }}</h1>

{{-- With variables --}}
<p>{{ __('messages.greeting', ['name' => $user->name]) }}</p>

{{-- Using @lang directive --}}
<h2>@lang('messages.nav.home')</h2>

{{-- JSON translations (use the string itself as key) --}}
<p>{{ __('Welcome back!') }}</p>

{{-- Pluralization --}}
{{ trans_choice('{0} No items|{1} One item|[2,*] :count items', $count) }}

{{-- Inside Blade components --}}
<x-button>{{ __('messages.nav.settings') }}</x-button>
6

Automatizar as traduções

Depois de concluir a configuração de i18n em Laravel, traduza os arquivos de localidade com IA. Indique ao assistente o arquivo de origem ou utilize a CLI do i18n Agent no pipeline de CI/CD. Aceita arquivos PHP e JSON.

config/locale-chain.php
// Install locale chain package
composer require i18n-agent/laravel-locale-chain

// config/locale-chain.php
return [
    'chains' => [
        'pt-BR' => ['pt-BR', 'pt', 'en'],
        'zh-Hant-TW' => ['zh-Hant-TW', 'zh-Hant', 'zh', 'en'],
        'es-419' => ['es-419', 'es', 'en'],
    ],
];

// In AppServiceProvider::boot()
use I18nAgent\LocaleChain\LocaleChainServiceProvider;

// The package automatically deep-merges translations
// across the chain: pt-BR -> pt -> en
Traduza de forma incremental: ao adicionar chaves, traduza apenas as diferenças em vez de voltar a gerar tudo. Assim preserva traduções revisadas por pessoas e evita alterações desnecessárias.

Erros frequentes

Lógica de singular/plural codificada diretamente

Escrever $count == 1 ? 'item' : 'items' em vez de trans_choice() falha em idiomas onde 0 é singular —francês—, existem 3 ou mais formas —russo e polonês— ou 6 —árabe—. Utilize sempre a sintaxe do Laravel e defina todas as formas.

As traduções JSON não recorrem a outra localidade

fallback_locale só funciona em arquivos PHP. As traduções JSON utilizam a string de origem como chave, por isso uma tradução ausente retorna a própria chave —o texto em inglês— em vez de procurar na localidade de fallback. Assim, JSON não tem um verdadeiro fallback. Utilize laravel-locale-chain.

Misturar PHP e JSON sem compreender a prioridade

Quando a mesma chave existe em PHP e JSON, PHP tem prioridade. Isto pode confundir: atualizar o JSON não produz efeito porque o PHP o oculta. Escolha um formato por espaço funcional e mantenha-o.

Experimente já o i18n Agent

Solte aqui seu arquivo de tradução

JSON, YAML, PO, XML, CSV, Markdown, Properties

ou clique para selecionar

Idiomas de destino

Sem cadastroEstimativa imediata

Perguntas frequentes sobre i18n em Laravel