PHP Laravel (.php): Guía Completa de Archivos de Localización Laravel

¿Qué Son los Archivos de Localización PHP Laravel?

Los archivos de localización PHP Laravel son el formato nativo de traducción para aplicaciones Laravel. Usan arrays PHP para almacenar strings de traducción, organizados por idioma en el directorio lang (o resources/lang en versiones anteriores). Este formato proporciona una estructura simple y legible que se integra perfectamente con los helpers de traducción de Laravel.

El sistema de localización de Laravel soporta strings simples, arrays anidados, pluralización y reemplazo de parámetros, haciéndolo una solución potente para aplicaciones PHP multilingües.

Por Qué AZbox Soporta el Formato PHP Laravel

En AZbox, entendemos que Laravel es uno de los frameworks PHP más populares del mundo. Por eso AZbox soporta completamente la importación y exportación de archivos PHP Laravel, permitiéndote:

• Importar archivos de traducción PHP existentes directamente a tu proyecto AZbox
• Exportar traducciones de vuelta a arrays PHP para tu app Laravel
• Manejar arrays anidados y estructuras complejas
• Soportar pluralización con la sintaxis pipe de Laravel
• Gestionar traducciones con nuestra potente plataforma en la nube
• Colaborar con traductores que no necesitan conocimientos de PHP

Estructura de Directorios Laravel

Estructura Laravel 9+

lang/
├── en/
│   ├── auth.php
│   ├── pagination.php
│   ├── passwords.php
│   ├── validation.php
│   └── messages.php
├── es/
│   ├── auth.php
│   ├── pagination.php
│   ├── passwords.php
│   ├── validation.php
│   └── messages.php
└── fr/
    ├── auth.php
    ├── pagination.php
    ├── passwords.php
    ├── validation.php
    └── messages.php

Laravel 8 y Anteriores

resources/
└── lang/
    ├── en/
    │   ├── auth.php
    │   ├── messages.php
    │   └── validation.php
    ├── es/
    │   ├── auth.php
    │   ├── messages.php
    │   └── validation.php
    └── vendor/
        └── nombre-paquete/
            └── en/
                └── messages.php

Estructura Básica de Archivo de Traducción PHP

Un archivo de traducción Laravel típico:

lang/en/messages.php:

<?php

return [
    'welcome' => 'Welcome to our application!',
    'goodbye' => 'Goodbye, see you soon!',
    
    'buttons' => [
        'save' => 'Save',
        'cancel' => 'Cancel',
        'delete' => 'Delete',
        'edit' => 'Edit',
    ],
    
    'errors' => [
        'not_found' => 'Resource not found.',
        'unauthorized' => 'You are not authorized.',
        'server_error' => 'An unexpected error occurred.',
    ],
];

lang/es/messages.php:

<?php

return [
    'welcome' => '¡Bienvenido a nuestra aplicación!',
    'goodbye' => '¡Adiós, hasta pronto!',
    
    'buttons' => [
        'save' => 'Guardar',
        'cancel' => 'Cancelar',
        'delete' => 'Eliminar',
        'edit' => 'Editar',
    ],
    
    'errors' => [
        'not_found' => 'Recurso no encontrado.',
        'unauthorized' => 'No tienes autorización.',
        'server_error' => 'Ocurrió un error inesperado.',
    ],
];

Reemplazo de Parámetros

Laravel soporta valores dinámicos usando sintaxis :parameter:

lang/es/messages.php:

<?php

return [
    'greeting' => '¡Hola, :name!',
    'welcome_back' => '¡Bienvenido, :name! Último acceso: :date',
    'order_status' => 'Tu pedido #:id está :status.',
    'items_added' => ':count artículos añadidos al carrito por :user.',
    
    // Con múltiples parámetros
    'invoice' => 'Factura #:number para :customer - Total: :currency:amount',
];

Uso en Laravel

// En plantillas Blade
{{ __('messages.greeting', ['name' => 'Juan']) }}
// Salida: "¡Hola, Juan!"

// En PHP
echo __('messages.welcome_back', [
    'name' => $user->name,
    'date' => $lastLogin->format('d M, Y')
]);
// Salida: "¡Bienvenido, Juan! Último acceso: 15 ene, 2024"

// Usando helper trans()
trans('messages.order_status', ['id' => '12345', 'status' => 'enviado']);
// Salida: "Tu pedido #12345 está enviado."

Modificadores de Mayúsculas para Parámetros

Laravel soporta modificación de mayúsculas para parámetros:

<?php

return [
    // :Name - Primera letra mayúscula
    'greeting_formal' => 'Estimado/a :Name,',
    
    // :NAME - Todo mayúsculas
    'alert' => 'ATENCIÓN: :NAME',
    
    // :name - Como se proporciona
    'simple' => '¡Hola, :name!',
];

Uso:

__('messages.greeting_formal', ['name' => 'juan']);
// Salida: "Estimado/a Juan,"

__('messages.alert', ['name' => 'advertencia']);
// Salida: "ATENCIÓN: ADVERTENCIA"

Pluralización

Laravel usa sintaxis pipe (|) para pluralización:

lang/es/messages.php:

<?php

return [
    // Simple singular/plural
    'apples' => 'Hay una manzana|Hay muchas manzanas',
    
    // Con marcador de conteo
    'items' => '{0} Sin artículos|{1} Un artículo|[2,*] :count artículos',
    
    // Rangos más específicos
    'comments' => '{0} Sin comentarios|{1} :count comentario|[2,10] :count comentarios|[11,*] Muchos comentarios (:count)',
    
    // Usando números explícitos
    'notifications' => '{0} Sin notificaciones|{1} 1 notificación|{2} 2 notificaciones|[3,*] :count notificaciones',
    
    // Minutos restantes
    'minutes' => '{1} :count minuto restante|[2,*] :count minutos restantes',
];

Uso

// trans_choice() o __() con 'count'
trans_choice('messages.apples', 1);
// Salida: "Hay una manzana"

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

trans_choice('messages.items', 0);
// Salida: "Sin artículos"

trans_choice('messages.items', 1);
// Salida: "Un artículo"

trans_choice('messages.items', 5);
// Salida: "5 artículos"

// Con parámetros adicionales
trans_choice('messages.items', 10, ['count' => 10]);
// Salida: "10 artículos"

Pluralización Compleja para Diferentes Idiomas

lang/ru/messages.php (Ruso):

<?php

return [
    // Ruso tiene reglas plurales complejas
    'items' => '{0} Нет товаров|{1} :count товар|[2,4] :count товара|[5,20] :count товаров|[21,*] :count товар',
];

lang/ar/messages.php (Árabe):

<?php

return [
    // Árabe tiene zero, one, two, few, many, other
    'items' => '{0} لا عناصر|{1} عنصر واحد|{2} عنصران|[3,10] :count عناصر|[11,*] :count عنصر',
];

Arrays Anidados

Organiza traducciones jerárquicamente:

lang/es/dashboard.php:

<?php

return [
    'title' => 'Panel',
    
    'widgets' => [
        'statistics' => [
            'title' => 'Estadísticas',
            'users' => 'Total Usuarios',
            'orders' => 'Total Pedidos',
            'revenue' => 'Ingresos Totales',
        ],
        'activity' => [
            'title' => 'Actividad Reciente',
            'empty' => 'Sin actividad reciente.',
            'view_all' => 'Ver Toda la Actividad',
        ],
        'notifications' => [
            'title' => 'Notificaciones',
            'mark_read' => 'Marcar como Leído',
            'clear_all' => 'Limpiar Todo',
        ],
    ],
    
    'sidebar' => [
        'home' => 'Inicio',
        'profile' => 'Mi Perfil',
        'settings' => 'Configuración',
        'logout' => 'Cerrar Sesión',
    ],
];

Acceder a Claves Anidadas

// Notación de punto para claves anidadas
__('dashboard.widgets.statistics.title');
// Salida: "Estadísticas"

__('dashboard.sidebar.home');
// Salida: "Inicio"

// En Blade
{{ __('dashboard.widgets.activity.empty') }}

Archivos de Traducción Laravel por Defecto

auth.php

<?php

return [
    'failed' => 'Estas credenciales no coinciden con nuestros registros.',
    'password' => 'La contraseña proporcionada es incorrecta.',
    'throttle' => 'Demasiados intentos de inicio de sesión. Por favor intente de nuevo en :seconds segundos.',
];

pagination.php

<?php

return [
    'previous' => '&laquo; Anterior',
    'next' => 'Siguiente &raquo;',
];

passwords.php

<?php

return [
    'reset' => 'Tu contraseña ha sido restablecida.',
    'sent' => 'Hemos enviado el enlace de restablecimiento a tu correo.',
    'throttled' => 'Por favor espera antes de intentar de nuevo.',
    'token' => 'Este token de restablecimiento de contraseña es inválido.',
    'user' => 'No encontramos un usuario con esa dirección de correo.',
];

validation.php

<?php

return [
    'accepted' => 'El campo :attribute debe ser aceptado.',
    'active_url' => 'El campo :attribute debe ser una URL válida.',
    'after' => 'El campo :attribute debe ser una fecha posterior a :date.',
    'alpha' => 'El campo :attribute solo debe contener letras.',
    'between' => [
        'array' => 'El campo :attribute debe tener entre :min y :max elementos.',
        'file' => 'El campo :attribute debe pesar entre :min y :max kilobytes.',
        'numeric' => 'El campo :attribute debe estar entre :min y :max.',
        'string' => 'El campo :attribute debe tener entre :min y :max caracteres.',
    ],
    'email' => 'El campo :attribute debe ser una dirección de correo válida.',
    'required' => 'El campo :attribute es obligatorio.',
    
    // Mensajes de validación personalizados
    'custom' => [
        'email' => [
            'required' => 'Necesitamos tu dirección de correo.',
            'email' => 'Tu dirección de correo es inválida.',
        ],
    ],
    
    // Nombres de atributos personalizados
    'attributes' => [
        'email' => 'correo electrónico',
        'password' => 'contraseña',
        'password_confirmation' => 'confirmación de contraseña',
    ],
];

Archivos de Traducción JSON

Laravel también soporta archivos JSON para traducciones clave-valor simples:

lang/en.json:

{
    "Welcome": "Welcome",
    "Hello, :name!": "Hello, :name!",
    "You have :count notifications": "You have :count notifications"
}

lang/es.json:

{
    "Welcome": "Bienvenido",
    "Hello, :name!": "¡Hola, :name!",
    "You have :count notifications": "Tienes :count notificaciones"
}

Uso

// Las traducciones JSON usan la string real como clave
__('Welcome');
__('Hello, :name!', ['name' => 'Juan']);

Importar Archivos PHP Laravel a AZbox

Paso 1: Prepara tus Archivos

Asegúrate de que tus archivos PHP son válidos:

1. Sintaxis PHP válida con <?php y return []
2. Codificación UTF-8
3. Estructura consistente entre idiomas

Paso 2: Importar vía Panel de AZbox

1. Inicia sesión en tu panel de AZbox
2. Navega a tu proyecto
3. Ve a la sección Importar/Exportar
4. Selecciona Importar y elige PHP Laravel (.php)
5. Sube tus archivos de traducción PHP
6. Configura las opciones de importación:
   • Selecciona idioma fuente
   • Mapea nombres de archivo a namespaces
   • Maneja arrays anidados (aplanar o preservar)
7. Previsualiza y confirma la importación

Paso 3: Mapeo de Claves

AZbox convierte arrays PHP a claves:

// Esta estructura PHP:
return [
    'welcome' => 'Bienvenido',
    'buttons' => [
        'save' => 'Guardar',
    ],
];

// Se convierte en estas claves:
// messages.welcome
// messages.buttons.save

Exportar Archivos PHP Laravel desde AZbox

Opciones de Exportación

Opción	Descripción
Formato	Array PHP o JSON
Anidamiento	Preservar estructura anidada
Archivo por namespace	Archivos separados por cada namespace
Sintaxis array corta	Usar [] en lugar de array()

Pasos de Exportación

1. Ve a Importar/Exportar en tu proyecto
2. Selecciona Exportar y elige PHP Laravel (.php)
3. Configura las opciones de exportación
4. Descarga los archivos PHP generados
5. Colócalos en tu directorio lang/

Formato de Exportación

AZbox genera archivos PHP limpios:

<?php

return [
    'welcome' => 'Bienvenido',
    'goodbye' => 'Adiós',
    
    'buttons' => [
        'save' => 'Guardar',
        'cancel' => 'Cancelar',
    ],
];

Usar Traducciones en Laravel

Plantillas Blade

{{-- Traducción simple --}}
<h1>{{ __('messages.welcome') }}</h1>

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

{{-- Pluralización --}}
<span>{{ trans_choice('messages.items', $count) }}</span>

{{-- Usando directiva @lang --}}
@lang('messages.welcome')

{{-- Con choice --}}
{{ trans_choice('messages.notifications', $notifications->count()) }}

Controladores

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class DashboardController extends Controller
{
    public function index()
    {
        return view('dashboard', [
            'title' => __('dashboard.title'),
            'welcomeMessage' => __('messages.welcome_back', [
                'name' => auth()->user()->name
            ]),
        ]);
    }
    
    public function store(Request $request)
    {
        // Mensaje flash traducido
        return redirect()->back()->with(
            'success',
            __('messages.saved_successfully')
        );
    }
}

Mensajes de Validación

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreUserRequest extends FormRequest
{
    public function rules()
    {
        return [
            'email' => 'required|email',
            'password' => 'required|min:8',
        ];
    }
    
    public function messages()
    {
        return [
            'email.required' => __('validation.custom.email.required'),
            'email.email' => __('validation.custom.email.email'),
        ];
    }
}

Respuestas API

<?php

namespace App\Http\Controllers\Api;

class UserController extends Controller
{
    public function show($id)
    {
        $user = User::find($id);
        
        if (!$user) {
            return response()->json([
                'message' => __('errors.not_found'),
            ], 404);
        }
        
        return response()->json([
            'message' => __('messages.success'),
            'data' => $user,
        ]);
    }
}

Notificaciones

<?php

namespace App\Notifications;

use Illuminate\Notifications\Notification;
use Illuminate\Notifications\Messages\MailMessage;

class OrderShipped extends Notification
{
    public function toMail($notifiable)
    {
        return (new MailMessage)
            ->subject(__('notifications.order_shipped.subject'))
            ->greeting(__('notifications.greeting', ['name' => $notifiable->name]))
            ->line(__('notifications.order_shipped.line1', ['id' => $this->order->id]))
            ->action(__('notifications.order_shipped.action'), url('/orders/' . $this->order->id))
            ->line(__('notifications.order_shipped.line2'));
    }
}

Mejores Prácticas para Localización Laravel

1. Organiza por Funcionalidad

lang/es/
├── auth.php           # Autenticación
├── dashboard.php      # Específico del panel
├── emails.php         # Plantillas de email
├── errors.php         # Mensajes de error
├── messages.php       # Mensajes generales
├── navigation.php     # Etiquetas de navegación
├── notifications.php  # Textos de notificación
└── validation.php     # Mensajes de validación

2. Usa Claves Descriptivas

Mal:

return [
    'msg1' => 'Bienvenido',
    'btn' => 'Guardar',
    'e1' => 'Error',
];

Bien:

return [
    'welcome_message' => 'Bienvenido',
    'button_save' => 'Guardar',
    'error_generic' => 'Ha ocurrido un error',
];

3. Agrupa Traducciones Relacionadas

<?php

return [
    'user' => [
        'profile' => [
            'title' => 'Perfil de Usuario',
            'edit' => 'Editar Perfil',
            'update_success' => 'Perfil actualizado correctamente.',
        ],
        'settings' => [
            'title' => 'Configuración de Usuario',
            'notifications' => 'Preferencias de Notificación',
            'privacy' => 'Configuración de Privacidad',
        ],
    ],
];

4. Añade Comentarios para Contexto

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Líneas de Idioma de Autenticación
    |--------------------------------------------------------------------------
    |
    | Las siguientes líneas de idioma se usan durante la autenticación para
    | varios mensajes que necesitamos mostrar al usuario.
    |
    */
    
    'failed' => 'Estas credenciales no coinciden con nuestros registros.',
    'throttle' => 'Demasiados intentos. Por favor intente de nuevo en :seconds segundos.',
    
    // Etiquetas del formulario de login
    'email_label' => 'Correo Electrónico',
    'password_label' => 'Contraseña',
    'remember_me' => 'Recordarme',
    
    // Botones de login (máx 20 caracteres)
    'login_button' => 'Iniciar Sesión',
    'register_button' => 'Crear Cuenta',
];

5. Mantén las Traducciones Sincronizadas

Asegúrate de que todos los archivos de idioma tienen las mismas claves:

lang/en/messages.php:

return [
    'welcome' => 'Welcome',
    'goodbye' => 'Goodbye',
];

lang/es/messages.php:

return [
    'welcome' => 'Bienvenido',
    'goodbye' => 'Adiós',
];

6. Usa Locale de Fallback

config/app.php:

'locale' => 'es',
'fallback_locale' => 'en',

Problemas Comunes y Soluciones

Problema: Clave de Traducción No Encontrada

Problema: Devuelve la clave en lugar de la traducción.

Solución:

• Verifica la ruta y nombre del archivo
• Verifica que la clave existe en el array
• Limpia caché de config: php artisan config:clear
• Busca erratas en claves anidadas

Problema: Parámetro No Reemplazado

Problema: :name aparece literalmente.

Solución:

// Incorrecto - faltan parámetros
__('messages.greeting');

// Correcto
__('messages.greeting', ['name' => 'Juan']);

Problema: Pluralización No Funciona

Problema: Se muestra la forma plural incorrecta.

Solución:

// Usa trans_choice() para pluralización
trans_choice('messages.items', $count, ['count' => $count]);

// O __() con count en el array
__('messages.items', ['count' => $count], $count);

Problema: Caché No Se Actualiza

Problema: Todavía se muestran traducciones antiguas.

Solución:

php artisan cache:clear
php artisan config:clear
php artisan view:clear

Problema: Error de Sintaxis PHP

Problema: Laravel lanza error de sintaxis.

Solución:

• Verifica punto y coma faltantes
• Verifica que las comillas están correctamente escapadas
• Asegura que la sintaxis del array es correcta
• Valida sintaxis PHP antes de desplegar

Funcionalidades PHP Laravel de AZbox

Cuando usas PHP Laravel con AZbox, te beneficias de:

• Parseo de arrays PHP - Maneja correctamente todas las estructuras de array
• Soporte de claves anidadas - Preserva organización jerárquica
• Resaltado de parámetros - Marcadores visuales para :parameters
• Soporte de pluralización - Maneja sintaxis pipe de Laravel
• Preservación de comentarios - Mantiene tus comentarios PHPDoc
• Soporte JSON - También maneja archivos lang/*.json
• Reglas de validación - Gestiona validation.php específicamente
• Manejo de namespaces - Organiza por archivo (auth, messages, etc.)
• Memoria de traducción - Aprovecha traducciones anteriores
• Actualizaciones over-the-air - Actualiza sin redesplegar

Integración con Paquetes Laravel

Laravel Breeze / Jetstream

AZbox soporta traducciones del scaffolding de autenticación:

lang/es/
├── auth.php
├── passwords.php
└── validation.php

Filament Admin Panel

lang/es/
└── filament.php

Laravel Nova

lang/es/
└── nova.php

Conclusión

Los archivos de localización PHP Laravel proporcionan un formato nativo y potente para gestionar traducciones en aplicaciones Laravel. Con el soporte completo de Laravel de AZbox, puedes:

1. Importar archivos PHP existentes preservando todos los arrays y estructura
2. Manejar traducciones complejas incluyendo anidamiento y pluralización
3. Exportar archivos PHP limpios listos para tu proyecto Laravel
4. Soportar convenciones Laravel incluyendo patrones de validation.php
5. Colaborar con traductores sin requerir conocimientos de PHP

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

Comienza tu Prueba Gratuita | Ver Precios

---

AZbox proporciona soporte completo para archivos de localización PHP Laravel, convirtiéndolo en la plataforma ideal para desarrolladores Laravel. Importa, gestiona y exporta tus traducciones con facilidad.