Skip to main content

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

Do primeiro ficheiro regional à produção: configure o sistema de tradução do Laravel, trate a pluralização, corrija o erro de recurso 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 ficheiros PHP utilizam chaves aninhadas por funcionalidade —auth.failed e validation.required—. Os JSON utilizam a cadeia 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 deteta-o automaticamente. Se ambos existirem, lang/ tem prioridade.
2

Configurar as definições regionais

Defina as regiões predefinida e de recurso em config/app.php. A de recurso é utilizada quando falta uma chave na ativa. Configure as regiões compatíveis e adicione middleware para detetar e definir a preferência do utilizador.

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 ficheiros 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 polaco com 3—, tem de definir todas as categorias CLDR necessárias. Sem elas, os utilizadores veem texto gramaticalmente errado.
5

Adicionar cadeias de recurso regional

O recurso integrado do Laravel só passa da região ativa para fallback_locale, sem etapa intermédia. Um utilizador pt-BR com uma chave em falta vê inglês em vez de pt-PT. laravel-locale-chain corrige isto 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 ficheiros regionais com IA. Indique ao assistente o ficheiro de origem ou utilize a CLI do i18n Agent no pipeline de CI/CD. Aceita ficheiros 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 revistas 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 polaco— ou 6 —árabe—. Utilize sempre a sintaxe do Laravel e defina todas as formas.

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

fallback_locale só funciona em ficheiros PHP. As traduções JSON utilizam a cadeia de origem como chave, pelo que uma tradução em falta devolve a própria chave —texto inglês— em vez de procurar na região de recurso. Assim, JSON não tem um verdadeiro recurso. 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

Largue aqui o seu ficheiro de tradução

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

ou clique para selecionar

Idiomas de destino

Sem registoEstimativa imediata

Perguntas frequentes sobre i18n em Laravel