A internacionalização (i18n) é essencial para aplicações que precisam atender usuários de diferentes regiões e idiomas. O Laravel oferece um suporte robusto para gerenciar múltiplos idiomas, facilitando a tradução de textos e a adaptação da interface do usuário.
Neste tutorial, vamos explorar como implementar a internacionalização em um projeto Laravel, incluindo a criação de seletores de idioma e as melhores práticas para organizar arquivos de tradução.
Índice
Introdução à Internacionalização no Laravel
A internacionalização permite que sua aplicação suporte múltiplos idiomas sem a necessidade de duplicar código ou views. O Laravel facilita esse processo fornecendo ferramentas para gerenciar arquivos de tradução e funções para recuperar as traduções corretas com base no idioma ativo.
Configuração Inicial
Definindo o Idioma Padrão
No arquivo config/app.php, você pode definir o idioma padrão da sua aplicação:
'locale' => 'pt_BR',Certifique-se de que este idioma corresponde a uma pasta dentro de resources/lang.
Estrutura de Pastas de Tradução
A estrutura de pastas para arquivos de tradução fica em resources/lang. Cada idioma tem sua própria pasta:
resources/lang
├── en
│ └── messages.php
├── es
│ └── messages.php
└── pt_BR
└── messages.phpCriando Arquivos de Tradução
Arquivos de Tradução Simples
Crie arquivos PHP que retornam um array de mensagens.
Exemplo: resources/lang/en/messages.php
<?php
return [
'welcome' => 'Welcome to our website!',
'login' => 'Login',
'register' => 'Register',
];Exemplo: resources/lang/pt_BR/messages.php
<?php
return [
'welcome' => 'Bem-vindo ao nosso site!',
'login' => 'Entrar',
'register' => 'Cadastrar',
];Arquivos de Tradução por Grupos
Você pode organizar as traduções em grupos temáticos.
Exemplo: resources/lang/en/auth.php
<?php
return [
'failed' => 'These credentials do not match our records.',
'password' => 'The provided password is incorrect.',
];Utilizando as Funções de Tradução
Função __()
Use a função global __() para traduzir as mensagens.
Exemplo:
echo __('messages.welcome');Helper @lang no Blade
No Blade, use o helper @lang ou a função __().
Exemplo:
<p>@lang('messages.welcome')</p>
<!-- Ou -->
<p>{{ __('messages.welcome') }}</p>Implementando o Seletor de Idiomas
Criando Rotas para Alterar o Idioma
Adicione uma rota para alterar o idioma em routes/web.php:
use App\Http\Controllers\LanguageController;
Route::get('lang/{locale}', [LanguageController::class, 'switchLang'])->name('lang.switch');Criando o Controller
Crie o controller para gerenciar a mudança de idioma:
php artisan make:controller LanguageControllerEm app/Http/Controllers/LanguageController.php:
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Illuminate\Support\Facades\Session;
class LanguageController extends Controller
{
public function switchLang($locale)
{
// Verifica se o idioma está disponível
if (array_key_exists($locale, config('app.available_locales'))) {
Session::put('locale', $locale);
}
return redirect()->back();
}
}Atualizando o Middleware
Para que a aplicação utilize o idioma selecionado, atualize o middleware app/Http/Middleware/SetLocale.php:
<?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 = Session::get('locale', config('app.locale'));
App::setLocale($locale);
return $next($request);
}
}Registre o middleware em app/Http/Kernel.php:
protected $middlewareGroups = [
'web' => [
// ...
\App\Http\Middleware\SetLocale::class,
],
];Adicionando o Seletor na View
No seu layout Blade, adicione o seletor de idiomas:
<ul>
@foreach (config('app.available_locales') as $locale => $language)
<li>
<a href="{{ route('lang.switch', $locale) }}">{{ $language }}</a>
</li>
@endforeach
</ul>No arquivo config/app.php, defina os idiomas disponíveis:
'available_locales' => [
'en' => 'English',
'pt_BR' => 'Português (Brasil)',
'es' => 'Español',
],Persistindo a Preferência de Idioma
Usando Sessão
No exemplo acima, usamos a sessão para armazenar o idioma escolhido. Isso é adequado para usuários autenticados e não autenticados.
Usando Cookie
Para persistir o idioma por mais tempo, você pode usar cookies.
No método switchLang do LanguageController:
public function switchLang($locale)
{
if (array_key_exists($locale, config('app.available_locales'))) {
// Define o cookie por 1 ano
return redirect()->back()->withCookie(cookie('locale', $locale, 525600));
}
return redirect()->back();
}No middleware SetLocale:
public function handle($request, Closure $next)
{
$locale = $request->cookie('locale', config('app.locale'));
App::setLocale($locale);
return $next($request);
}Melhores Práticas para Organizar Arquivos de Tradução
Estruturação por Módulos
Organize os arquivos de tradução por módulos ou funcionalidades da aplicação.
Exemplo:
resources/lang
├── en
│ ├── auth.php
│ ├── pagination.php
│ ├── validation.php
│ └── messages.phpUtilizando Placeholders e Pluralização
Placeholders
Use placeholders para inserir valores dinâmicos.
Exemplo em messages.php:
'welcome_user' => 'Welcome, :name!',Uso:
{{ __('messages.welcome_user', ['name' => $user->name]) }}Pluralização
Para mensagens que variam no singular e plural, use a sintaxe |.
Exemplo:
'apples' => 'There is one apple|There are many apples',Uso:
{{ trans_choice('messages.apples', $count) }}Testando a Implementação
- Verifique as Traduções: Certifique-se de que todas as chaves de tradução estão corretas.
- Teste o Seletor de Idiomas: Mude entre os idiomas e verifique se o conteúdo é atualizado.
- Valide a Persistência: Feche e reabra o navegador para garantir que a preferência é mantida.
Conclusão
Implementar múltiplos idiomas em sua aplicação Laravel melhora a experiência do usuário e amplia o alcance do seu projeto. Com o suporte integrado do Laravel para internacionalização, você pode gerenciar facilmente as traduções e adaptar sua aplicação a diferentes públicos.
Lembre-se de seguir as melhores práticas na organização dos arquivos de tradução e de testar cuidadosamente para garantir que todas as partes da aplicação estão corretamente traduzidas.
Recursos Adicionais
- Documentação Oficial do Laravel – Localização: laravel.com/docs/localization
- Pacotes Úteis:
- Laravel Localization – Gerencia rotas e URLs traduzidas.
- Laravel Translation Manager – Interface para gerenciar traduções.
- Artigos e Tutoriais:
- Como Traduzir Rotas no Laravel
- Gerenciando Traduções com JSON no Laravel