Localización PHP: Guía Completa de i18n Basada en Arrays (2026)

Respuesta Rápida

Para localizar una aplicación PHP, usa archivos de traducción basados en arrays. Almacena traducciones en arrays PHP (/lang/es/messages.php), crea una función helper de traducción y úsala en toda tu app. Para frameworks: Laravel tiene el helper integrado __('clave'), Symfony usa el componente Translation, WordPress usa __('texto', 'dominio'). Este enfoque es simple, rápido y funciona con cualquier versión de PHP.

---

Por Qué Importa la Localización PHP

PHP impulsa el 77% de los sitios web (W3Techs, 2026). Desde WordPress hasta Laravel, las aplicaciones PHP sirven audiencias globales.

El desafío: PHP no tiene i18n integrado como los frameworks JavaScript. Necesitas implementarlo tú mismo o usar la solución de un framework.

La solución: Las traducciones basadas en arrays son el estándar PHP. Simple, eficiente y agnóstico al framework.

---

Configuración Básica: PHP Simple

Paso 1: Crear Archivos de Traducción

Estructura de directorios:

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

lang/es/messages.php:

PHPCopy
1<?php
2
3return [
4    'welcome' => 'Bienvenido a nuestra aplicación',
5    'goodbye' => '¡Adiós, :name!',
6    'items_count' => '{0} Sin artículos|{1} Un artículo|[2,*] :count artículos',
7    
8    // Arrays anidados para organización
9    'auth' => [
10        'login' => 'Iniciar sesión',
11        'logout' => 'Cerrar sesión',
12        'register' => 'Registrarse',
13        'failed' => 'Estas credenciales no coinciden con nuestros registros.',
14    ],
15    
16    'nav' => [
17        'home' => 'Inicio',
18        'about' => 'Sobre Nosotros',
19        'contact' => 'Contacto',
20    ],
21];

---

Localización Laravel

Laravel tiene localización integrada. Es el mismo enfoque basado en arrays, pero con más características.

Configuración

1. Crear archivos de traducción:

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

2. Configurar locale predeterminado:

PHPCopy
1// config/app.php
2
3'locale' => 'es',
4'fallback_locale' => 'en',
5'available_locales' => ['es', 'en', 'fr', 'de'],

3. Usar en vistas:

PHPCopy
1<!-- Plantilla Blade -->
2<h1>{{ __('messages.welcome') }}</h1>
3<p>{{ __('messages.goodbye', ['name' => $user->name]) }}</p>
4
5<!-- Pluralización -->
6<p>{{ trans_choice('messages.items_count', $count) }}</p>
7
8<!-- Sintaxis corta (Laravel 9+) -->
9<h1>@lang('messages.welcome')</h1>

4. Usar en controladores:

PHPCopy
1<?php
2
3namespace AppHttpControllers;
4
5class HomeController extends Controller
6{
7    public function index()
8    {
9        // Obtener traducción
10        $message = __('messages.welcome');
11        
12        // Con reemplazos
13        $greeting = __('messages.goodbye', ['name' => 'Juan']);
14        
15        // Pluralización
16        $items = trans_choice('messages.items_count', 5);
17        
18        return view('home', compact('message', 'greeting', 'items'));
19    }
20}

5. Cambiar locale dinámicamente:

PHPCopy
1<?php
2
3// En middleware o controlador
4App::setLocale('es');
5
6// Obtener locale actual
7$locale = App::getLocale();
8
9// Verificar si locale está disponible
10if (in_array($locale, config('app.available_locales'))) {
11    App::setLocale($locale);
12}

---

Componente de Traducción Symfony

Symfony tiene un componente Translation potente que funciona independiente o con el framework.

Instalación (Independiente)

TerminalCopy
composer require symfony/translation

Configuración

PHPCopy
1<?php
2
3use SymfonyComponentTranslationTranslator;
4use SymfonyComponentTranslationLoaderPhpFileLoader;
5
6$translator = new Translator('es');
7$translator->setFallbackLocales(['en']);
8
9// Agregar loader para archivos PHP
10$translator->addLoader('php', new PhpFileLoader());
11
12// Cargar archivos de traducción
13$translator->addResource('php', __DIR__ . '/lang/es/messages.php', 'es', 'messages');
14$translator->addResource('php', __DIR__ . '/lang/en/messages.php', 'en', 'messages');
15
16// Usar traducciones
17echo $translator->trans('welcome', [], 'messages'); // "Bienvenido a nuestra aplicación"
18
19// Con reemplazos
20echo $translator->trans('goodbye', ['%name%' => 'Juan'], 'messages'); // "¡Adiós, Juan!"

---

Localización WordPress

WordPress usa gettext, pero también puedes usar traducciones basadas en arrays.

Forma Tradicional de WordPress (Gettext)

1. Marcar cadenas para traducción:

PHPCopy
1<?php
2
3// En tema o plugin
4echo __('Bienvenido a nuestro sitio', 'mi-tema');
5echo _e('Hola Mundo', 'mi-tema'); // Echo directo
6
7// Con variables
8printf(__('Hola, %s!', 'mi-tema'), $nombre);
9
10// Pluralización
11echo _n('%s artículo', '%s artículos', $count, 'mi-tema');

2. Generar archivo .pot:

TerminalCopy
1# Usando WP-CLI
2wp i18n make-pot . languages/mi-tema.pot
3
4# O usar Poedit para escanear archivos

---

Formato de Fechas y Números

Usando Extensión PHP Intl

PHPCopy
1<?php
2
3$locale = 'es_ES';
4
5// Formato de fecha
6$formatter = new IntlDateFormatter(
7    $locale,
8    IntlDateFormatter::LONG,
9    IntlDateFormatter::NONE
10);
11echo $formatter->format(new DateTime()); // "7 de febrero de 2026"
12
13// Formato de número
14$numberFormatter = new NumberFormatter($locale, NumberFormatter::DECIMAL);
15echo $numberFormatter->format(1234.56); // "1.234,56"
16
17// Formato de moneda
18$currencyFormatter = new NumberFormatter($locale, NumberFormatter::CURRENCY);
19echo $currencyFormatter->formatCurrency(1234.56, 'EUR'); // "1.234,56 €"

---

Mejores Prácticas

1. Organizar Archivos de Traducción

/lang
  /es
    messages.php       # Cadenas generales de UI
    validation.php     # Mensajes de validación de formularios
    auth.php          # Mensajes de autenticación
    emails.php        # Plantillas de email
    errors.php        # Mensajes de error

2. Usar Arrays Anidados

PHPCopy
1<?php
2
3return [
4    'auth' => [
5        'login' => 'Iniciar sesión',
6        'logout' => 'Cerrar sesión',
7        'register' => 'Registrarse',
8    ],
9    'nav' => [
10        'home' => 'Inicio',
11        'about' => 'Acerca de',
12    ],
13];
14
15// Uso: __('messages.auth.login')

3. Nunca Concatenar Traducciones

PHPCopy
1<?php
2
3// ❌ Malo: El orden de palabras difiere en idiomas
4echo __('messages.welcome') . ' ' . $nombre . '!';
5
6// ✅ Bueno: Usar marcadores de posición
7echo __('messages.welcome_user', ['name' => $nombre]);

---

Integración con IntlPull

Configuración

TerminalCopy
composer require intlpullhq/php-sdk

Flujo de Trabajo Automatizado

TerminalCopy
1# Extraer cadenas del código
2php artisan intlpull:extract
3
4# Subir a IntlPull
5php artisan intlpull:upload
6
7# Traducir con IA
8php artisan intlpull:translate
9
10# Descargar traducciones
11php artisan intlpull:download
12
13# Desplegar
14php artisan config:cache

---

Preguntas Frecuentes

¿Debo usar gettext o arrays PHP?

Usa arrays PHP para la mayoría de proyectos. Son más simples, rápidos y no requieren extensiones PHP. Usa gettext solo si necesitas compatibilidad con herramientas existentes o tienes traductores que prefieren archivos .po.

¿Cómo manejo la pluralización en PHP?

Usa trans_choice() de Laravel o trans() de Symfony con formato de mensaje ICU. Para PHP simple, implementa un analizador simple que maneje sintaxis {0}, {1}, y [2,*] como se muestra en esta guía.

¿Puedo usar JSON en lugar de arrays PHP?

Sí, pero los arrays PHP son más rápidos. JSON requiere análisis en cada solicitud. Los arrays PHP son compilados por OPcache. Usa JSON solo si necesitas compartir traducciones con JavaScript.

---

Conclusión

La localización PHP es sencilla con traducciones basadas en arrays.

Resumen rápido:

1. Crear archivos /lang/{locale}/messages.php
2. Retornar arrays con claves de traducción
3. Usar función helper __('clave')
4. Manejar pluralización con trans_choice()
5. Formatear fechas/números con extensión Intl

Para apps de producción:

• Usa Laravel o Symfony para características integradas
• Integra con IntlPull para flujo de trabajo automatizado
• Cachea traducciones para rendimiento
• Sigue mejores prácticas (arrays anidados, marcadores, contexto)

Prueba IntlPull Gratis | Ver Documentación PHP | Paquete Laravel