Localización en Laravel: Guía Completa para Aplicaciones PHP Multilingües

Construir aplicaciones multilingües es esencial para alcanzar una audiencia global. Laravel proporciona un sistema de localización robusto que facilita la recuperación de cadenas en varios idiomas. En esta guía, exploraremos las características de localización de Laravel y cómo implementarlas efectivamente en tus aplicaciones.

Entendiendo la Localización en Laravel

Las características de localización de Laravel proporcionan una manera conveniente de recuperar cadenas en varios idiomas, permitiéndote soportar múltiples idiomas fácilmente en tu aplicación. El framework soporta dos enfoques para gestionar cadenas de traducción:

1. Archivos PHP con arrays - Enfoque tradicional usando archivos .php con arrays
2. Archivos JSON - Recomendado para aplicaciones con muchas cadenas traducibles

Configurando los Archivos de Idioma

Estructura de Directorios

Laravel almacena los archivos de idioma en el directorio lang. Puedes crear este directorio ejecutando:

php artisan lang:publish

Esto crea la siguiente estructura:

/lang
    /en
        messages.php
        validation.php
    /es
        messages.php
        validation.php
    en.json
    es.json

Archivos PHP con Arrays

Los archivos PHP con arrays son ideales para organizar traducciones por funcionalidad o dominio:

lang/es/messages.php:

<?php

return [
    'welcome' => '¡Bienvenido a nuestra aplicación!',
    'goodbye' => '¡Adiós, hasta pronto!',
    'user' => [
        'profile' => 'Perfil de Usuario',
        'settings' => 'Configuración de Cuenta',
        'logout' => 'Cerrar Sesión',
    ],
];

lang/en/messages.php:

<?php

return [
    'welcome' => 'Welcome to our application!',
    'goodbye' => 'Goodbye, see you soon!',
    'user' => [
        'profile' => 'User Profile',
        'settings' => 'Account Settings',
        'logout' => 'Log Out',
    ],
];

Archivos JSON

Los archivos JSON son recomendados para aplicaciones con un gran número de cadenas traducibles. Usan la cadena de traducción por defecto como clave:

lang/es.json:

{
    "Welcome to our application!": "¡Bienvenido a nuestra aplicación!",
    "I love programming.": "Me encanta programar.",
    "The :attribute must be a valid email.": "El :attribute debe ser un correo electrónico válido."
}

lang/en.json:

{
    "Welcome to our application!": "Welcome to our application!",
    "I love programming.": "I love programming.",
    "The :attribute must be a valid email.": "The :attribute must be a valid email."
}

Configurando el Locale

Locale por Defecto

Configura el locale por defecto de tu aplicación en config/app.php o mediante la variable de entorno APP_LOCALE:

config/app.php:

'locale' => env('APP_LOCALE', 'es'),
'fallback_locale' => env('APP_FALLBACK_LOCALE', 'en'),

.env:

APP_LOCALE=es
APP_FALLBACK_LOCALE=en

Cambiar Locale en Tiempo de Ejecución

Puedes cambiar el locale dinámicamente para una solicitud individual:

use Illuminate\Support\Facades\App;

Route::get('/saludo/{locale}', function (string $locale) {
    if (!in_array($locale, ['en', 'es', 'fr', 'de'])) {
        abort(400);
    }

    App::setLocale($locale);

    return view('saludo');
});

Obtener el Locale Actual

Verifica el locale actual o determina si coincide con un idioma específico:

use Illuminate\Support\Facades\App;

// Obtener locale actual
$locale = App::currentLocale();

// Verificar si el locale es un idioma específico
if (App::isLocale('es')) {
    // Manejar locale español
}

Recuperando Cadenas de Traducción

Usando el Helper __()

La forma más común de recuperar traducciones:

// Desde archivo PHP (lang/es/messages.php)
echo __('messages.welcome');
// Salida: "¡Bienvenido a nuestra aplicación!"

// Claves anidadas
echo __('messages.user.profile');
// Salida: "Perfil de Usuario"

// Desde archivo JSON (usando cadena por defecto como clave)
echo __('I love programming.');
// Salida: "Me encanta programar."

En Plantillas Blade

Usa la sintaxis {{ }} en tus plantillas Blade:

{{-- Desde archivo PHP --}}
<h1>{{ __('messages.welcome') }}</h1>

{{-- Desde archivo JSON --}}
<p>{{ __('I love programming.') }}</p>

{{-- Con directiva @lang --}}
@lang('messages.goodbye')

Reemplazo de Parámetros

Laravel te permite definir marcadores de posición en tus cadenas de traducción:

Parámetros Básicos

lang/es/messages.php:

<?php

return [
    'welcome' => 'Bienvenido, :name',
    'greeting' => '¡Hola, :Name! Bienvenido a :App.',
];

Uso:

echo __('messages.welcome', ['name' => 'Juan']);
// Salida: "Bienvenido, Juan"

echo __('messages.greeting', ['name' => 'juan', 'app' => 'Laravel']);
// Salida: "¡Hola, Juan! Bienvenido a Laravel."

Capitalización

Los marcadores de posición manejan automáticamente la capitalización:

// :name - minúsculas
// :Name - primera letra mayúscula
// :NAME - todo mayúsculas

'welcome' => 'Bienvenido, :NAME', // "Bienvenido, JUAN"
'greeting' => 'Hola, :Name',      // "Hola, Juan"

En Plantillas Blade

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

<p>{{ __('messages.greeting', ['name' => auth()->user()->name, 'app' => config('app.name')]) }}</p>

Pluralización

Laravel proporciona un potente soporte de pluralización para manejar diferentes formas de cantidad:

Pluralización Básica

Usa el carácter | para separar formas singulares y plurales:

lang/es/messages.php:

<?php

return [
    'apples' => 'Hay una manzana|Hay muchas manzanas',
    'notifications' => '{0} Sin notificaciones|{1} Una notificación|[2,*] :count notificaciones',
];

Usando trans_choice()

echo trans_choice('messages.apples', 1);
// Salida: "Hay una manzana"

echo trans_choice('messages.apples', 5);
// Salida: "Hay muchas manzanas"

echo trans_choice('messages.notifications', 0);
// Salida: "Sin notificaciones"

echo trans_choice('messages.notifications', 1);
// Salida: "Una notificación"

echo trans_choice('messages.notifications', 10);
// Salida: "10 notificaciones"

Reglas de Pluralización Avanzadas

Define múltiples rangos para pluralización compleja:

'items' => '{0} Sin elementos|[1,5] Algunos elementos|[6,10] Varios elementos|[11,*] Muchos elementos',

Pluralización con Parámetros

Combina pluralización con reemplazo de parámetros:

lang/es/messages.php:

<?php

return [
    'minutes_ago' => '{1} Hace :value minuto|[2,*] Hace :value minutos',
    'cart_items' => '{0} Tu carrito está vacío|{1} Tienes :count artículo en tu carrito|[2,*] Tienes :count artículos en tu carrito',
];

Uso:

echo trans_choice('messages.minutes_ago', 5, ['value' => 5]);
// Salida: "Hace 5 minutos"

echo trans_choice('messages.cart_items', 3);
// Salida: "Tienes 3 artículos en tu carrito"

En Plantillas Blade

<p>{{ trans_choice('messages.notifications', $notificationCount) }}</p>

<p>{{ trans_choice('messages.cart_items', $cartItems->count()) }}</p>

Construyendo un Selector de Idioma

Crea un selector de idioma para tu aplicación:

Configuración de Rutas

routes/web.php:

Route::get('/idioma/{locale}', function (string $locale) {
    if (!in_array($locale, ['en', 'es', 'fr', 'de'])) {
        abort(400);
    }

    session()->put('locale', $locale);

    return redirect()->back();
})->name('language.switch');

Middleware

Crea un middleware para establecer el locale desde la sesión:

app/Http/Middleware/SetLocale.php:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;

class SetLocale
{
    public function handle(Request $request, Closure $next)
    {
        if (session()->has('locale')) {
            App::setLocale(session('locale'));
        }

        return $next($request);
    }
}

Registra en bootstrap/app.php (Laravel 11+):

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \App\Http\Middleware\SetLocale::class,
    ]);
})

Componente Blade

resources/views/components/language-switcher.blade.php:

<div class="language-switcher">
    @foreach(['en' => 'English', 'es' => 'Español', 'fr' => 'Français'] as $locale => $language)
        <a href="{{ route('language.switch', $locale) }}" 
           class="{{ App::currentLocale() === $locale ? 'active' : '' }}">
            {{ $language }}
        </a>
    @endforeach
</div>

Mejores Prácticas

1. Organiza Traducciones por Dominio

Agrupa traducciones relacionadas en archivos separados:

/lang
    /es
        auth.php       # Cadenas de autenticación
        validation.php # Mensajes de validación
        dashboard.php  # UI del dashboard
        emails.php     # Plantillas de email
        api.php        # Respuestas de API

2. Usa Claves Descriptivas

Mal:

'msg1' => 'Bienvenido',
'btn' => 'Enviar',

Bien:

'auth.welcome_message' => 'Bienvenido a tu panel',
'forms.submit_button' => 'Enviar',

3. Proporciona Contexto en Comentarios

<?php

return [
    // Mostrado en la página de login
    'login_title' => 'Inicia Sesión en Tu Cuenta',
    
    // Texto del botón para envío de formulario
    'submit' => 'Enviar',
    
    // Mensaje de error cuando el email es inválido
    'invalid_email' => 'Por favor ingresa una dirección de email válida.',
];

4. Maneja Traducciones Faltantes

La función __() retorna la clave si no existe traducción:

// Si 'messages.unknown_key' no existe
echo __('messages.unknown_key');
// Salida: "messages.unknown_key"

// Proporciona un valor por defecto
echo __('messages.unknown_key') !== 'messages.unknown_key' 
    ? __('messages.unknown_key') 
    : 'Texto por defecto';

5. Usa JSON para Cadenas de Usuario

Para aplicaciones grandes, los archivos JSON son más fáciles de gestionar:

{
    "Welcome back, :name!": "¡Bienvenido de nuevo, :name!",
    "You have :count new messages.": "Tienes :count mensajes nuevos.",
    "Your order has been shipped.": "Tu pedido ha sido enviado."
}

Gestionando Traducciones con Azbox

Aunque la localización integrada de Laravel es poderosa, gestionar traducciones entre múltiples idiomas y miembros del equipo puede volverse complejo. Azbox proporciona una plataforma centralizada para optimizar tu flujo de trabajo de localización en Laravel:

Beneficios de Usar Azbox con Laravel

• Gestión Centralizada: Gestiona todas las traducciones en un solo lugar
• Colaboración en Equipo: Trabaja con traductores sin compartir acceso al código
• Importar/Exportar: Importa archivos PHP de Laravel existentes y exporta actualizaciones
• Memoria de Traducción: Reutiliza traducciones entre proyectos
• Aseguramiento de Calidad: Verificaciones automatizadas de traducciones faltantes e inconsistencias

Exportando Traducciones de Laravel a Azbox

1. Exporta tus archivos lang/*.php como JSON o súbelos directamente
2. Azbox preserva tu estructura de claves y soporta arrays anidados
3. Los traductores trabajan en una interfaz amigable
4. Exporta de vuelta a formato PHP de Laravel cuando esté listo

Integración con el Flujo de Trabajo

# Exportar traducciones a Azbox
php artisan translations:export --format=azbox

# Importar traducciones desde Azbox
php artisan translations:import --from=azbox

Patrones Comunes

Formateo de Fecha y Hora

// lang/es/dates.php
return [
    'formats' => [
        'short' => 'd M, Y',
        'long' => 'd \d\e F \d\e Y',
        'datetime' => 'd M, Y H:i',
    ],
];

// Uso
$date = now()->format(__('dates.formats.long'));

Formateo de Moneda

// lang/es/currency.php
return [
    'format' => ':amount €',
    'thousand_separator' => '.',
    'decimal_separator' => ',',
];

// lang/en/currency.php  
return [
    'format' => '$:amount',
    'thousand_separator' => ',',
    'decimal_separator' => '.',
];

Mensajes de Validación

Laravel incluye mensajes de validación localizados. Personalízalos:

lang/es/validation.php:

return [
    'required' => 'El campo :attribute es obligatorio.',
    'email' => 'El :attribute debe ser una dirección de correo válida.',
    'custom' => [
        'email' => [
            'required' => 'Necesitamos tu dirección de correo para continuar.',
        ],
    ],
    'attributes' => [
        'email' => 'correo electrónico',
        'password' => 'contraseña',
    ],
];

Probando Traducciones

Tests de Funcionalidad

public function test_pagina_bienvenida_muestra_traduccion_correcta()
{
    $response = $this->get('/');
    $response->assertSee(__('messages.welcome'));
}

public function test_locale_espanol_muestra_texto_en_espanol()
{
    App::setLocale('es');
    
    $response = $this->get('/');
    $response->assertSee('¡Bienvenido a nuestra aplicación!');
}

Verificar Traducciones Faltantes

Crea un comando para auditar traducciones:

// app/Console/Commands/AuditTranslations.php
public function handle()
{
    $englishKeys = $this->getKeys('en');
    $spanishKeys = $this->getKeys('es');
    
    $missing = array_diff($englishKeys, $spanishKeys);
    
    foreach ($missing as $key) {
        $this->warn("Traducción al español faltante: {$key}");
    }
}

Conclusión

El sistema de localización de Laravel proporciona una base poderosa para construir aplicaciones multilingües. Siguiendo los patrones y mejores prácticas descritos en esta guía, puedes:

• Estructurar traducciones efectivamente usando arrays PHP o archivos JSON
• Manejar escenarios complejos con reemplazo de parámetros y pluralización
• Construir selectores de idioma amigables para el usuario
• Mantener la calidad de traducción en toda tu aplicación

Para equipos que gestionan traducciones en múltiples proyectos e idiomas, Azbox ofrece una plataforma centralizada que se integra perfectamente con el sistema de localización de Laravel.

Comienza con Azbox

¿Listo para optimizar tu flujo de trabajo de localización en Laravel?

1. Regístrate en Azbox - Comienza con una prueba gratuita
2. Importa tus traducciones - Sube tus archivos PHP de Laravel existentes
3. Colabora con traductores - Invita miembros del equipo a trabajar en traducciones
4. Exporta de vuelta a Laravel - Descarga archivos PHP actualizados para tu proyecto

Explora la plataforma de localización de AZbox y simplifica tu flujo de trabajo de traducción:

Ver Planes y Precios de AZbox

Conoce el soporte de formato de archivos PHP Laravel