Домашняя страница LaravelDocs Laravel Docs
  1. Profundizando
  2. Localización

Introducción

Nota De forma predeterminada, el esqueleto de la aplicación Laravel no incluye el directorio lang. Si desea personalizar los archivos de idioma de Laravel, puede publicarlos mediante el comando Artisan lang:publish.

Las funciones de localización de Laravel proporcionan una forma conveniente de recuperar cadenas en varios idiomas, lo que le permite admitir fácilmente varios idiomas en su aplicación.

Laravel proporciona dos formas de gestionar cadenas de traducción. En primer lugar, las cadenas de idioma se pueden almacenar en archivos dentro del directorio lang de la aplicación. Dentro de este directorio, puede haber subdirectorios para cada idioma admitido por la aplicación. Este es el enfoque que Laravel utiliza para gestionar cadenas de traducción de funciones integradas de Laravel, como los mensajes de error de validación:

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

O, las cadenas de traducción se pueden definir dentro de archivos JSON que se colocan dentro del directorio lang. Al tomar este enfoque, cada idioma admitido por su aplicación tendría un archivo JSON correspondiente dentro de este directorio. Este enfoque se recomienda para aplicaciones que tienen un gran número de cadenas traducibles:

/lang
    en.json
    es.json

Discutiremos cada enfoque para gestionar cadenas de traducción dentro de esta documentación.

Publicación de Archivos de Idioma

De forma predeterminada, el esqueleto de la aplicación Laravel no incluye el directorio lang. Si desea personalizar los archivos de idioma de Laravel o crear los suyos propios, debería generar el directorio lang mediante el comando Artisan lang:publish. El comando lang:publish creará el directorio lang en su aplicación y publicará el conjunto predeterminado de archivos de idioma utilizados por Laravel:

php artisan lang:publish

Configuración de la Configuración Regional

El idioma predeterminado para su aplicación se almacena en la opción de configuración locale del archivo de configuración config/app.php. Puede modificar este valor según las necesidades de su aplicación.

Puede modificar el idioma predeterminado para una única solicitud HTTP en tiempo de ejecución mediante el método setLocale proporcionado por la fachada App:

use Illuminate\Support\Facades\App;
 
Route::get('/greeting/{locale}', function (string $locale) {
    if (! in_array($locale, ['en', 'es', 'fr'])) {
        abort(400);
    }
 
    App::setLocale($locale);
 
    // ...
});

Puede configurar un "idioma de reserva", que se utilizará cuando el idioma activo no contenga una cadena de traducción específica. Al igual que el idioma predeterminado, el idioma de reserva también se configura en el archivo de configuración config/app.php:

'fallback_locale' => 'en',

Determinar la Configuración Regional Actual

Puede utilizar los métodos currentLocale e isLocale en la fachada App para determinar el idioma actual o verificar si el idioma es un valor dado:

use Illuminate\Support\Facades\App;
 
$locale = App::currentLocale();
 
if (App::isLocale('en')) {
    // ...
}

Lenguaje de Pluralización

Puede indicar al "pluralizador" de Laravel, que se utiliza en Eloquent y otras partes del framework para convertir cadenas singulares en cadenas plurales, que utilice un idioma distinto al inglés. Esto se puede lograr invocando el método useLanguage dentro del método boot de uno de los proveedores de servicios de su aplicación. Los idiomas actualmente admitidos por el pluralizador son: french, norwegian-bokmal, portuguese, spanish y turkish:

use Illuminate\Support\Pluralizer;
 
/**
 * Inicializa cualquier servicio de la aplicación.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');
 
    // ...
}

Advertencia Si personaliza el idioma del pluralizador, debería definir explícitamente los nombres de tabla de su modelo Eloquent.

Definición de Cadenas de Traducción

Uso de Claves Cortas

Normalmente, las cadenas de traducción se almacenan en archivos dentro del directorio lang. Dentro de este directorio, debería haber un subdirectorio para cada idioma admitido por su aplicación. Este es el enfoque que Laravel utiliza para gestionar las cadenas de traducción de funciones integradas de Laravel, como los mensajes de error de validación:

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

Todos los archivos de idioma devuelven un array de cadenas clave. Por ejemplo:

<?php
 
// lang/en/messages.php
 
return [
    'welcome' => 'Welcome to our application!',
];

Advertencia Para los idiomas que difieren por territorio, debería nombrar los directorios de idiomas según el estándar ISO 15897. Por ejemplo, debería usar "en_GB" para el inglés británico en lugar de "en-gb".

Uso de Cadenas de Traducción como Claves

Para aplicaciones con un gran número de cadenas traducibles, definir cada cadena con una "clave corta" puede resultar confuso al hacer referencia a las claves en sus vistas y es engorroso inventar constantemente claves para cada cadena de traducción admitida por su aplicación.

Por esta razón, Laravel también proporciona soporte para definir cadenas de traducción utilizando la traducción "predeterminada" de la cadena como clave. Los archivos de idioma que usan cadenas de traducción como claves se almacenan como archivos JSON en el directorio lang. Por ejemplo, si su aplicación tiene una traducción al español, debería crear un archivo lang/es.json:

{
    "I love programming.": "Me encanta programar."
}

Conflictos de Claves / Archivos

No debe definir claves de cadenas de traducción que entren en conflicto con otros nombres de archivos de traducción. Por ejemplo, traducir __('Action') para la configuración regional "NL" mientras exista un archivo nl/action.php pero no exista un archivo nl.json resultará en que el traductor devuelva todo el contenido de nl/action.php.

Recuperación de Cadenas de Traducción

Puede recuperar cadenas de traducción de sus archivos de idioma utilizando la función de ayuda __. Si está utilizando "claves cortas" para definir sus cadenas de traducción, debe pasar el archivo que contiene la clave y la clave misma a la función __ utilizando la sintaxis "punto". Por ejemplo, recuperemos la cadena de traducción welcome del archivo de idioma lang/es/messages.php:

echo __('messages.welcome');

Si la cadena de traducción especificada no existe, la función __ devolverá la clave de la cadena de traducción. Entonces, usando el ejemplo anterior, la función __ devolvería messages.welcome si la cadena de traducción no existe.

Si está utilizando sus cadenas de traducción predeterminadas como claves de traducción, debe pasar la traducción predeterminada de su cadena a la función __;

echo __('I love programming.');

Nuevamente, si la cadena de traducción no existe, la función __ devolverá la clave de la cadena de traducción que se le dio.

Si está utilizando el motor de plantillas Blade, puede usar la sintaxis de eco {{ }} para mostrar la cadena de traducción:

{{ __('messages.welcome') }}

Reemplazo de Parámetros en Cadenas de Traducción

Si lo desea, puede definir marcadores de posición en sus cadenas de traducción. Todos los marcadores de posición llevan un prefijo :. Por ejemplo, puede definir un mensaje de bienvenida con un marcador de posición para el nombre:

'welcome' => 'Welcome, :name',

Para reemplazar los marcadores de posición al recuperar una cadena de traducción, puede pasar un array de reemplazos como segundo argumento a la función __:

echo __('messages.welcome', ['name' => 'dayle']);

Si su marcador de posición contiene todas las letras en mayúsculas, o solo tiene su primera letra en mayúscula, el valor traducido se capitalizará en consecuencia:

'welcome' => 'Welcome, :NAME', // Welcome, DAYLE
'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle

Formato de Reemplazo de Objetos

Si intenta proporcionar un objeto como marcador de posición de traducción, se invocará el método __toString del objeto. El método __toString es uno de los "métodos mágicos" integrados de PHP. Sin embargo, a veces es posible que no tenga control sobre el método __toString de una clase determinada, como cuando la clase con la que está interactuando pertenece a una biblioteca de terceros.

En estos casos, Laravel le permite registrar un controlador de formato personalizado para ese tipo particular de objeto. Para lograr esto, debe invocar el método stringable del traductor. El método stringable acepta un cierre, que debe indicar el tipo de objeto que es responsable de formatear. Por lo general, el método stringable debería invocarse dentro del método boot de la clase AppServiceProvider de su aplicación:

use Illuminate\Support\Facades\Lang;
use Money\Money;
 
/**
 * Inicializa cualquier servicio de la aplicación.
 */
public function boot(): void
{
    Lang::stringable(function (Money $money) {
        return $money->formatTo('en_GB');
    });
}

Pluralización

La pluralización es un problema complejo, ya que diferentes idiomas tienen una variedad de reglas complejas para la pluralización; sin embargo, Laravel puede ayudarlo a traducir cadenas de manera diferente según las reglas de pluralización que defina. Usando el carácter |, puede distinguir las formas singular y plural de una cadena:

'apples' => 'There is one apple|There are many apples',

Por supuesto, la pluralización también es compatible cuando se utilizan cadenas de traducción como claves de traducción:

{
    "There is one apple|There are many apples": "Hay una manzana|Hay muchas manzanas"
}

Incluso puede crear reglas de pluralización más complejas que especifiquen cadenas de traducción para varios rangos de valores:

'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many',

Después de definir una cadena de traducción que tiene opciones de pluralización, puede usar la función trans_choice para recuperar la línea para un determinado "conteo". En este ejemplo, dado que el conteo es mayor que uno, se devuelve la forma en plural de la cadena de traducción:

echo trans_choice('messages.apples', 10);

También puede definir atributos de marcadores de posición en cadenas de pluralización. Estos marcadores de posición se pueden reemplazar pasando un array como tercer argumento a la función trans_choice:

'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago',
 
echo trans_choice('time.minutes_ago', 5, ['value' => 5]);

Si desea mostrar el valor entero que se pasó a la función trans_choice, puede usar el marcador de posición incorporado :count:

'apples' => '{0} There are none|{1} There is one|[2,*] There are :count',

Sobreescritura de Archivos de Idioma de Paquetes

Algunos paquetes pueden incluir sus propios archivos de idioma. En lugar de cambiar los archivos principales del paquete para ajustar estas líneas, puede anularlos colocando archivos en el directorio lang/vendor/{package}/{locale}.

Entonces, por ejemplo, si necesita anular las cadenas de traducción en inglés en messages.php para un paquete llamado skyrim/hearthfire, debe colocar un archivo de idioma en: lang/vendor/hearthfire/en/messages.php. Dentro de este archivo, solo debe definir las cadenas de traducción que desea anular. Cualquier cadena de traducción que no anule seguirá cargándose desde los archivos de idioma originales del paquete.