Localización

• Introducción
  • Publicar los archivos de idioma
  • Configurar la configuración regional
  • Lenguaje de pluralización
• Definir cadenas de traducción
  • Usar claves cortas
  • Usar cadenas de traducción como claves
• Recuperar cadenas de traducción
  • Reemplazar parámetros en cadenas de traducción
  • Pluralización
• Sobrescribir archivos de idioma de paquetes

#Introducción

Las funciones de localización de Laravel proporcionan una forma conveniente de obtener cadenas en varios idiomas, permitiéndole soportar fácilmente múltiples idiomas dentro de su aplicación.

Laravel ofrece dos formas de gestionar las cadenas de traducción. Primero, las cadenas de idioma pueden almacenarse en archivos dentro del directorio lang de la aplicación. Dentro de este directorio, puede haber subdirectorios para cada idioma soportado por la aplicación. Este es el enfoque que Laravel utiliza para gestionar las cadenas de traducción de características integradas como los mensajes de error de validación:

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

O bien, las cadenas de traducción pueden definirse dentro de archivos JSON que se colocan en el directorio lang. Al usar este enfoque, cada idioma soportado por su aplicación tendría un archivo JSON correspondiente dentro de este directorio. Este método es recomendado para aplicaciones que tienen un gran número de cadenas traducibles:

/lang
    en.json
    es.json

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

#Publicar los archivos de idioma

Por defecto, 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, debe 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 que utiliza Laravel:

php artisan lang:publish

#Configurar la configuración regional

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

Puede modificar el idioma predeterminado para una única solicitud HTTP en tiempo de ejecución usando el método setLocale proporcionado por el facade 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 respaldo", que se usará cuando el idioma activo no contenga una cadena de traducción dada. Al igual que el idioma predeterminado, el idioma de respaldo también se configura en el archivo config/app.php:

'fallback_locale' => 'en',

#Determinar la configuración regional actual

Puede usar los métodos currentLocale e isLocale del facade App para determinar la configuración regional actual o verificar si la configuración regional 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 es usado por Eloquent y otras partes del framework para convertir cadenas singulares a plurales, que use 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 soportados por el pluralizador son: french, norwegian-bokmal, portuguese, spanish y turkish:

use Illuminate\Support\Pluralizer;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');

    // ...
}

#Definir cadenas de traducción

#Usar claves cortas

Normalmente, las cadenas de traducción se almacenan en archivos dentro del directorio lang. Dentro de este directorio, debe haber un subdirectorio para cada idioma soportado por su aplicación. Este es el enfoque que Laravel usa para gestionar las cadenas de traducción de características integradas 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 con claves. Por ejemplo:

<?php

// lang/en/messages.php

return [
    'welcome' => 'Welcome to our application!',
];

#Usar cadenas de traducción como claves

Para aplicaciones con un gran número de cadenas traducibles, definir cada cadena con una "clave corta" puede volverse confuso al referenciar las claves en sus vistas y es engorroso inventar claves continuamente para cada cadena de traducción soportada por su aplicación.

Por esta razón, Laravel también ofrece soporte para definir cadenas de traducción usando la traducción "por defecto" 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, debe crear un archivo lang/es.json:

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

#Conflictos entre claves y 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 existe un archivo nl/action.php pero no existe un archivo nl.json resultará en que el traductor devuelva todo el contenido de nl/action.php.

#Recuperar cadenas de traducción

Puede recuperar cadenas de traducción de sus archivos de idioma usando la función auxiliar __. Si está usando "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 __ usando la sintaxis de "puntos". Por ejemplo, recuperemos la cadena de traducción welcome del archivo de idioma lang/en/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. Así, usando el ejemplo anterior, la función __ devolvería messages.welcome si la cadena de traducción no existe.

Si está usando sus cadenas de traducción por defecto como claves de traducción, debe pasar la traducción por defecto de su cadena a la función __;

echo __('I love programming.');

De nuevo, si la cadena de traducción no existe, la función __ devolverá la clave de la cadena de traducción que se le proporcionó.

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

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

#Reemplazar 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 están prefijados con un :. 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 letras mayúsculas, o solo tiene la primera letra en mayúscula, el valor traducido se capitalizará en consecuencia:

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

#Formateo 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" incorporados en PHP. Sin embargo, a veces puede que no tenga control sobre el método __toString de una clase dada, como cuando la clase con la que interactúa pertenece a una biblioteca de terceros.

En estos casos, Laravel le permite registrar un manejador 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 closure, que debe indicar el tipo de objeto que es responsable de formatear. Normalmente, el método stringable debe invocarse dentro del método boot de la clase AppServiceProvider de su aplicación:

use Illuminate\Support\Facades\Lang;
use Money\Money;

/**
 * Bootstrap any application services.
 */
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 ayudarle a traducir cadenas de forma diferente según las reglas de pluralización que defina. Usando el carácter |, puede distinguir formas singulares y plurales de una cadena:

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

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

{
    "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 múltiples 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 "conteo" dado. En este ejemplo, dado que el conteo es mayor que uno, se devuelve la forma plural de la cadena de traducción:

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

También puede definir atributos de marcador de posición en cadenas de pluralización. Estos marcadores pueden ser reemplazados 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',

#Sobrescribir archivos de idioma de paquetes

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

Por ejemplo, si necesita sobrescribir 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 sobrescribir. Cualquier cadena que no sobrescriba seguirá cargándose desde los archivos de idioma originales del paquete.