En este artículo te vamos a explicar cómo puedes localizar al español, o a cualquier otro idioma, un sitio web realizado con Laravel. Para ello vamos a instalar el paquete de idiomas que necesites y decirle a Laravel que lo use de manera predeterminada cuando se solicite una página del proyecto.

Además, aprenderás diversas técnicas para la localización de textos en Laravel, de modo que puedas hacer páginas multi-idioma, aprovechando las funcionalidades que ya te ofrece el framework.

Repositorio de localización de Laravel

Existe un repositorio llamado Laravel-Lang/lang en GitHub.

En este repositorio encontramos las localizaciones a muchos idiomas, incluido por supuesto el español. En concreto nos ofrecerán en este repo todas las traducciones de los textos que ya están presentes en una instalación básica de Laravel, así como los textos de toda la parte de login y autorización de usuarios que podemos instalar en los starter kits oficiales, como Breeze, Fortify, Sanctum, etc.

Sin embargo, los archivos de idioma para localizar la aplicación no los vamos a tomar manualmente de este repositorio, sino que vamos a realizar la instalación de un gestor de traducciones, como se explica en el siguiente punto.

Instalación de paquetes de idioma para localizar las aplicaciones Laravel

Últimamente han cambiado varias veces la forma de proceder para la instalación de los archivos de localización de Laravel así que volvemos a actualizar el artículo.

Voy a colocar aquí la información actualizada y luego podrás encontrar más procedimientos anotados explicando cómo se hacía anteriormente, por si alguien lo necesita para versiones anteriores de los packages de localización para Laravel, o se requieren algunos pasos extra que no esté señalando aquí. Mis disculpas si, con todas estas actualizaciones este artículo se esté volviendo un poco confuso

Instalación de Laravel Lang

Los paquetes actuales de instalación son los siguientes:

Instalamos laravel-lang/common vía composer, solamente como dependencia de desarrollo.

composer require --dev laravel-lang/common

Ahora añadimos el publisher, que es el paquete que se encarga de actualizar las traducciones en la aplicación:

composer require --dev laravel-lang/publisher

Añadir archivos de localización

Añadimos nuevos archivos de localización de Laravel con el comando artisan lang:add. Por ejemplo los paquetes de localización al español se añaden así:

php artisan lang:add es

Actualizamos localizaciones existentes o bien añadimos localizaciones con el comando:

php artisan lang:update

Dependencias para instalar localizaciones de laravel en producción

En producción necesitamos el package laravel-lang/locales, por lo que lo vamos a instalar, esta vez sin el flag --dev.

composer require laravel-lang/locales

Notas de procedimientos anteriores

Aquí puedes encontrar pasos que había que hacer antes, con unos opcionales que permiten publicar archivos de configuración de Laravel Lang, que no siempre vas a necesitar. Quizás no te interese este punto. Entonces puedes ir directamente al apartado "Cambiar la configuración de la aplicación para definir el idioma" más adelante en este artículo.

Para realizar la instalación de paquetes de idioma de laravel-lang, que nos permite traducir fácilmente las aplicaciones Laravel a otros idiomas tenemos que instalar un gestor de traducciones.

Mediante el gestor de traducciones podemos generar en nuestro proyecto los archivos necesarios para localizar la aplicación al idioma que necesitemos. Este procedimiento incluye los siguientes pasos:

Instalación del paquete de idiomas Laravel-lang

Comenzamos instalando vía composer los paquetes de idiomas, el repositorio completo de laravel-lang.

composer require laravel-lang/lang --dev

Como ves, la instalación se hace solo en "modo desarrollo" con --dev. Estos archivos realmente no hacen falta en producción, solo los archivos que generaremos con el "Translation Manager".

Instalación del publisher, el translation manager

Hay varios translation managers disponibles. Este que vamos a instalar es el "oficial" de "laravel-lang". Este software se encarga de producir los archivos de las traducciones y colocarlos en la carpeta adecuada.

composer require laravel-lang/publisher laravel-lang/lang --dev

También se instala en modo desarrollo, como puedes ver con el flag --dev.

Instalar el service provider del publisher

Ahora necesitamos un service provider del publisher, que es el que nos va a crear en nuestra aplicación los comandos necesarios para producir los archivos de las traducciones y colocar esos archivos en las carpetas "lang".

php artisan vendor:publish --provider="LaravelLang\Publisher\ServiceProvider"

Lo bueno de los publisher es que automatizan el proceso de copiado de las carpetas de idioma, con lo que podremos crear una o varias carpetas de idioma directamente con comandos de artisan.

Instalación de los archivos del idioma español

Con el siguiente comando vamos a ver cómo se instalan los archivos de idioma español.

php artisan lang:add es

Para cualquier otro idioma, es simplemente cambiar el "es" por el código del idioma que necesites. Por ejemplo, alemán sería "de".

Ahora te dejamos con el resto del artículo que te explicará cosas importantes como la estructura de carpetas de los idiomas y la configuración de la aplicación para indicarle el paquete de localización que debe de usar.

Proceso antiguo para la Instalación de los archivos para localización al español de Laravel

Indicamos en esta nota las instrucciones antiguas para localización de las aplicaciones, por si alguien necesita realizar este procedimiento por algún motivo.

La diferencia principal sobre lo que hemos explicado antes es que este procedimiento es mucho más manual. Antes en el repositorio de las localizaciones de Laravel a los archivos de los distintos idiomas estaban los directamente producidos. Ahora no. Ahora encontramos los archivos php que sirven para generar los archivos de idioma,

Este procedimiento es anterior a la creación del translation manager actual de Laravel. Simplemente se obtenían los archivos de idioma de un repositorio de GitHub, pero era todo bastante manual

Para instalar los archivos que permiten traducir una página al español, o cualquier otro idioma, tenemos dos posibilidades.

Opción 1.- Descarga el repositorio y copiado de los archivos

Puedes simplemente hace la descarga del repositorio de GitHub en tu ordenador, ya sea vía clonado del repo o bien mediante la descarga directa.

Una vez descargado puedes acceder a los archivos de las traducciones de los idiomas que necesites, desde la carpeta correspondiente al idioma que requieras. Por ejemplo, los archivos de la localización al español están en la ruta:

https://github.com/Laravel-Lang/lang/tree/main/locales/es

Si has descargado el zip de GitHub esa ruta corresponderá con la carpeta siguiente:

locales/es

Los archivos de la traducción al español, es decir, toda la carpeta completa llamada "es", la tienes que pegar en la carpeta de tu aplicación donde se guardan los archivos de localización que tienes en la ruta "lang", que cuelga directamente de la raíz del proyecto.

Es decir, una vez copiados los archivos tendrás una nueva carpeta llamada:

lang/es

Una vez copiados los archivos, lang/es vez tendrá dentro todos los archivos que descargaste de la carpeta "locales/es" del repositorio indicado. Al final, tendrás una estructura de directorios más o menos como esta imagen:

Importante: sigue leyendo, porque la ruta final del archivo de localizaciones es.json la tendremos que mover a una carpeta distinta a la que aparece en la imagen anterior. Enseguida te explicamos por qué.

Opción 2.- Hacer un require del repositorio con Composer

Alternativamente puedes descargar este repositorio directamente con Composer.

composer require laravel-lang/lang --dev

Una vez instalado tienes los archivos de traducción en la carpeta vendor/laravel-lang/lang/locales. Por tanto, para las traducciones al español tendremos que copiar la carpeta

vendor/laravel-lang/lang/locales/es

El destino de la carpeta copiada será el que hemos explicado antes, dentro de lang/es, o la carpeta que corresponda según el idioma de localización que hayamos instalado.

Cambiar la configuración de la aplicación para definir el idioma

Una vez hemos instalado los archivos de la localización, para que la aplicación se traduzca tenemos además que hacer un cambio en la configuración de la aplicación.

Para ello editamos el archivo config/app.php y buscamos la declaración "locale", en la que ponemos el código de la localización deseada.

Tendremos que cambiar:

'locale' => 'en',

Por la correspondiente localización instalada. Para español sería:

'locale' => 'es',

Además, existe otra configuración que nos permite indicar cuál será la localización de la cadena, si es que no existe una correspondencia con aquello que se intenta traducir.

'fallback_locale' => 'en',

Aproximaciones para ampliar y personalizar la localización de Laravel

Obviamente, además de los textos básicos de una aplicación Laravel recién instalada, cuando estés realizando una página multi-idioma irás introduciendo nuevos textos que también tendrás que localizar. Llegado ese punto existen dos aproximaciones posibles para definir las cadenas localizadas en aplicaciones Laravel, que podemos usar de la manera que se adapte mejor a nuestras necesidades.

Archivo de palabras en formato JSON

La más sencilla sería usando un archivo de palabras sueltas en formato JSON. Este archivo de palabras contiene todas las cadenas que se deberían traducir y se coloca en la raíz de la carpeta "lang".

El nombre del archivo json será compuesto por la cadena de la localización, algo como "es", con extensión "json". Por ejemplo, para español tendremos el archivo es.json.

En los archivos que habíamos copiado anteriormente, veremos que en la carpeta "es" había un archivo llamado "es.json". Ese archivo contiene todas las cadenas de las traducciones, pero tendremos que moverlo a la carpeta "lang". Por tanto, los archivos de las localizaciones en la carpeta "lang" nos quedarán finalmente como vemos en esta imagen:

En ese archivo están todas las cadenas sueltas que se deben traducir, en pares clave/valor. La clave es la cadena a localizar y el valor es la cadena localizada. Por ejemplo, cada vez que veamos en la aplicación un código como este:

__('Email')

Se buscará en el archivo JSON una clave llamada "Email" y se presentará en la vista su correspondiente valor.

{
  //…
  "Email": "Correo electrónico",
  //…
}

Si no se encuentra una correspondencia de esa clave, se buscará entonces en un archivo en la carpeta lang/es, tal como vamos a explicar a continuación. Si tampoco se encuentra nada allí, entonces se mostrará el mismo mensaje enviado al helper.

Localizaciones en archivos sueltos

Adicionalmente, podríamos tener las localizaciones en archivos sueltos en la carpeta lang/es o similares. Pero no es tan práctico porque si hay muchas cadenas a localizar tendríamos que manejar muchos archivos.

Por ejemplo, podríamos tener un archivo lang/es/email.php con el contenido "Correo electrónico" escrito tal cual. Entonces se usaría si esa cadena no está en el JSON que hemos mencionado anteriormente.

Mensajes de aplicación

A menudo, los mensajes que la aplicación envía por diversos motivos se encuentran también en archivos sueltos de la localización bajo la carpeta correspondiente.

Por ejemplo, los intentos de login fallidos se envían desde el controlador localizados con cadenas que están en un archivo llamado lang/es/auth.php.

En ese archivo tenemos un array asociativo, también clave/valor, donde las claves corresponden con el mensaje que se debe enviar.

Por ejemplo, si vemos un código como este:

__('auth.password')

Se mostrará el mensaje que hay en el archivo lang/es/auth.php con la clave "password".

También hay un helper para localización llamado trans(). Funciona de manera similar al helper __(). Por ejemplo, si encontramos este código:

trans('pagination.next')

Buscará la traducción en el archivo lang/es/pagination.php que hay en el array con la clave "next".

Archivo validation.php para los mensajes de validación de Laravel

Hay otro archivo relevante para las validaciones, que mantiene todos los mensajes de validación. Ese archivo lo puedes usar para traducir los mensajes de validación de Laravel, pero también para traducir los nombres de los campos validados.

Por ejemplo, al construir un formulario si estamos validando un campo input llamado "name" no queremos que nos diga algo como "el campo name es requerido". Entonces tienes que suministrar en validation.php todas las cadenas de nombres de campos que estés usando en una clave llamada "attributes".

Esto lo tienes explicado con ejemplos y mayor detalle en la FAQ: ¿Cómo traducir los nombres de los campos (input name) en las validaciones Laravel?

Conclusión

En principio esto es todo lo que necesitas saber para mantener las traducciones de tus aplicaciones Laravel y localizar los textos al español, u otros idiomas. Afortunadamente, no necesitas hacer tú mismo los archivos de localización, ya que están disponibles en el repositorio que hemos compartido. Se trata simplemente de copiarlos en la carpeta "lang".

En adelante, a medida que vayas desarrollando tu aplicación, tendrás que ampliar los textos de los archivos de localización, con las técnicas y alternativas que hemos explicado.

Hemos visto cómo localizar tu página Laravel a un idioma en concreto, pero por supuesto, puedes configurar diversas localizaciones para construir también páginas multiidioma en Laravel, pero eso ya sería materia para estudio en otro artículo.