Localización

Trabajar con configuraciones regionales 

Higgs proporciona varias herramientas para ayudarle a localizar su aplicación en diferentes idiomas. mientras está lleno La localización de una aplicación es un tema complejo, es sencillo intercambiar cadenas en su aplicación. con diferentes idiomas soportados.

Las cadenas de idioma se almacenan en el directorio app/Language, con un subdirectorio para cada idioma soportado:

aplicación/
    Idioma/
        en/
            aplicación.php
        fr/
            aplicación.php

Importante

Locale detection only works for web-based requests that use the IncomingRequest class. Las solicitudes de línea de comandos no tendrán estas características.

Configurar la configuración regional 

Configuración de la configuración regional predeterminada 

Cada sitio tendrá un idioma/localización predeterminado en el que operará. Esto se puede configurar en app/Config/App.php:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class App extends BaseConfig
{
    // ...

    public string $defaultLocale = 'en';

    // ...
}

El valor puede ser cualquier cadena que utilice su aplicación para administrar cadenas de texto y otros formatos. Es recomendó que un BCP 47<http://www.rfc-editor.org/rfc/bcp/bcp47.txt> _ se utiliza el código de idioma. Esto resulta en códigos de idioma como en-US para inglés americano, o fr-FR, para francés/Francia. Una introducción más legible a esto se puede encontrar en el sitio del W3C<https://www.w3.org/International/articles/language-tags/> _.

El sistema es lo suficientemente inteligente como para recurrir a códigos de idiomas más genéricos si hay una coincidencia exacta. no pudo ser encontrado. Si el código local se configuró en en-US y solo tenemos archivos de idioma configurados para en entonces se usarán ya que no existe nada para el en-US más específico. Sin embargo, si una lengua Si el directorio existiera en el directorio app/Language/en-US, entonces ese se usaría primero.

Detección de configuración regional 

Se admiten dos métodos para detectar la configuración regional correcta durante la solicitud. El primero es «configurar y olvidar». método que realizará automáticamente negociación de contenido para que usted determinar la ubicación correcta a utilizar. El segundo método le permite especificar un segmento en sus rutas que se utilizará para establecer la configuración regional.

Si alguna vez necesita configurar la configuración regional directamente, consulte Configuración de la configuración regional actual.

Desde v7.4.0, se agregó IncomingRequest::setValidLocales() al conjunto (y restablecer) las configuraciones regionales válidas que se configuran desde la configuración Config\App::$supportedLocales.

Negociación de contenidos 

Puede configurar la negociación de contenido para que se realice automáticamente configurando dos configuraciones adicionales en app/Config/App.php. El primer valor le dice a la clase Request que queremos negociar una configuración regional, así que simplemente configúrelo en verdadero:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class App extends BaseConfig
{
    // ...

    public bool $negotiateLocale = true;

    // ...
}

Una vez habilitado, el sistema negociará automáticamente el idioma correcto basándose en una matriz de configuraciones regionales que ha definido en $supportLocales. Si no se encuentra ninguna coincidencia entre los idiomas que admite y el idioma solicitado, se utilizará el primer elemento de $supportedLocales. En En el siguiente ejemplo, se utilizaría la configuración regional en si no se encuentra ninguna coincidencia:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class App extends BaseConfig
{
    // ...

    public array $supportedLocales = ['en', 'es', 'fr-FR'];

    // ...
}

En Rutas 

El segundo método utiliza un marcador de posición personalizado para detectar la configuración regional deseada y configurarla en la Solicitud. El El marcador de posición {locale} se puede colocar como un segmento en su ruta. Si está presente, el contenido de la correspondencia El segmento será su localidad:

<?php

$routes->get('{locale}/books', 'App\Books::index');

En este ejemplo, si el usuario intentó visitar http://example.com/fr/books, entonces la configuración regional sería establecido en fr, asumiendo que fue configurado como una configuración regional válida.

Si el valor no coincide con una configuración regional válida como se define en $supportedLocales en app/Config/App.php, el valor predeterminado La configuración regional se usará en su lugar, a menos que configure usar solo las configuraciones regionales admitidas definidas en la configuración de la aplicación. archivo:

<?php

$routes->useSupportedLocalesOnly(true);

Nota

The useSupportedLocalesOnly() method can be used since v7.3.0.

Configuración de la configuración regional actual 

Si desea configurar la configuración regional directamente, puede usar SolicitudEntrante::setLocale(string $locale). Debes configurar las configuraciones regionales admitidas en app/Config/App.php:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class App extends BaseConfig
{
    // ...

    public array $supportedLocales = ['en', 'es', 'fr-FR'];

    // ...
}

Nota

Any attempt to set a locale not included in this array will result in la localización predeterminada siendo configurado.

Recuperar la configuración regional actual 

La configuración regional actual siempre se puede recuperar desde el objeto IncomingRequest, a través del método getLocale(). Si su controlador extiende Higgs\Controller, esto estará disponible a través de $this->request:

<?php

namespace App\Controllers;

class UserController extends BaseController
{
    public function index()
    {
        $locale = $this->request->getLocale();
    }
}

Alternativamente, puede utilizar la clase Services para recuperar la solicitud actual:

<?php

$locale = service('request')->getLocale();

Localización de idiomas 

Crear archivos de idioma 

Nota

The Language Files do not have namespaces.

Los idiomas no tienen ninguna convención de nomenclatura específica que sea necesaria. El archivo debe tener un nombre lógico para describir el tipo de contenido que contiene. Por ejemplo, digamos que desea crear un archivo que contenga mensajes de error. Podrías nombrarlo simplemente: Errors.php.

Dentro del archivo, devolvería una matriz, donde cada elemento de la matriz tiene una clave de idioma y puede tener una cadena para devolver:

<?php

return [
    'languageKey' => 'The actual message to be shown.',
];

También admite definiciones anidadas:

<?php

return [
    'languageKey' => [
        'nested' => [
            'key' => 'The actual message to be shown.',
        ],
    ],
];

<?php

return [
    'errorEmailMissing'    => 'You must submit an email address',
    'errorURLMissing'      => 'You must submit a URL',
    'errorUsernameMissing' => 'You must submit a username',
    'nested'               => [
        'error' => [
            'message' => 'A specific error message',
        ],
    ],
];

Uso básico 

Puede utilizar la función auxiliar lang() para recuperar texto de cualquiera de los archivos de idioma, pasando el nombre de archivo y la clave de idioma como primer parámetro, separados por un punto (.). Por ejemplo, para cargar el Cadena errorEmailMissing del archivo de idioma Errors.php, haría lo siguiente:

<?php

echo lang('Errors.errorEmailMissing');

Para una definición anidada, haría lo siguiente:

<?php

echo lang('Errors.nested.error.message');

Si la clave de idioma solicitada no existe en el archivo para la configuración regional actual, se pasará la cadena atrás, sin cambios. En este ejemplo, devolvería “Errors.errorEmailMissing” o “Errors.nested.error.message” si no existiera.

Reemplazo de parámetros 

Nota

The following functions all require the intl extension to cargarse en su sistema para poder funcionar. Si la extensión no está cargada, no se intentará reemplazarla. Puede encontrar una excelente descripción general en Sitepoint<https://www.sitepoint.com/localization-demystified-understanding-php-intl/> _.

Puede pasar una matriz de valores para reemplazar marcadores de posición en la cadena de idioma como segundo parámetro del Función lang(). Esto permite traducciones y formatos de números muy simples:

<?php

// The language file, Tests.php:
return [
    'apples'      => 'I have {0, number} apples.',
    'men'         => 'The top {1, number} men out-performed the remaining {0, number}',
    'namedApples' => 'I have {number_apples, number, integer} apples.',
];

// Displays "I have 3 apples."
echo lang('Tests.apples', [3]);

El primer elemento del marcador de posición corresponde al índice del elemento de la matriz, si es numérico:

<?php

// Displays "The top 23 men out-performed the remaining 20"
echo lang('Tests.men', [20, 23]);

También puede usar claves con nombre para que sea más fácil mantener las cosas claras, si lo desea:

<?php

// Displays "I have 3 apples."
echo lang('Tests.namedApples', ['number_apples' => 3]);

Obviamente, puedes hacer más que simplemente reemplazar números. De acuerdo con la Documentos oficiales de la UCI<https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classMessageFormat.html#details> _ para el subyacente biblioteca, se pueden reemplazar los siguientes tipos de datos:

números: entero, moneda, porcentaje
fechas: corta, media, larga, completa
tiempo: corto, medio, largo, completo
deletrear: deletrea los números (es decir, 34 se convierte en treinta y cuatro)
ordinal
duración

Aquí están algunos ejemplos:

<?php

// The language file, Tests.php
return [
    'shortTime'  => 'The time is now {0, time, short}.',
    'mediumTime' => 'The time is now {0, time, medium}.',
    'longTime'   => 'The time is now {0, time, long}.',
    'fullTime'   => 'The time is now {0, time, full}.',
    'shortDate'  => 'The date is now {0, date, short}.',
    'mediumDate' => 'The date is now {0, date, medium}.',
    'longDate'   => 'The date is now {0, date, long}.',
    'fullDate'   => 'The date is now {0, date, full}.',
    'spelledOut' => '34 is {0, spellout}',
    'ordinal'    => 'The ordinal is {0, ordinal}',
    'duration'   => 'It has been {0, duration}',
];

// Displays "The time is now 11:18 PM"
echo lang('Tests.shortTime', [time()]);
// Displays "The time is now 11:18:50 PM"
echo lang('Tests.mediumTime', [time()]);
// Displays "The time is now 11:19:09 PM CDT"
echo lang('Tests.longTime', [time()]);
// Displays "The time is now 11:19:26 PM Central Daylight Time"
echo lang('Tests.fullTime', [time()]);

// Displays "The date is now 8/14/16"
echo lang('Tests.shortDate', [time()]);
// Displays "The date is now Aug 14, 2016"
echo lang('Tests.mediumDate', [time()]);
// Displays "The date is now August 14, 2016"
echo lang('Tests.longDate', [time()]);
// Displays "The date is now Sunday, August 14, 2016"
echo lang('Tests.fullDate', [time()]);

// Displays "34 is thirty-four"
echo lang('Tests.spelledOut', [34]);

// Displays "It has been 408,676:24:35"
echo lang('Tests.ordinal', [time()]);

Debe asegurarse de leer sobre la clase MessageFormatter y el formato ICU subyacente para obtener una mejor idea sobre las capacidades que tiene, como realizar el reemplazo condicional, la pluralización y más. Ambos enlaces proporcionados. anterior le dará una excelente idea de las opciones disponibles.

Especificación de configuración regional 

Para especificar una configuración regional diferente que se utilizará al reemplazar parámetros, puede pasar la configuración regional como tercer parámetro de la función lang().

<?php

// Displays "The time is now 23:21:28 GMT-5"
echo lang('Test.longTime', [time()], 'ru-RU');

// Displays "£7.41"
echo lang('{price, number, currency}', ['price' => 7.41], 'en-GB');
// Displays "$7.41"
echo lang('{price, number, currency}', ['price' => 7.41], 'en-US');

Matrices anidadas 

Los archivos de idioma también permiten matrices anidadas para facilitar el trabajo con listas, etc.

<?php

// Language/en/Fruit.php

return [
    'list' => [
        'Apples',
        'Bananas',
        'Grapes',
        'Lemons',
        'Oranges',
        'Strawberries',
    ],
];

// Displays "Apples, Bananas, Grapes, Lemons, Oranges, Strawberries"
echo implode(', ', lang('Fruit.list'));

Idioma alternativo 

Si tiene un conjunto de mensajes para una ubicación determinada, por ejemplo Idioma/en/app.php, puedes agregar variantes de idioma para esa configuración regional, cada uno en su propia carpeta, por ejemplo Idioma/en-US/app.php.

Sólo necesita proporcionar valores para aquellos mensajes que serían localizado de forma diferente para esa variante local. Cualquier mensaje faltante Las definiciones se extraerán automáticamente de la configuración regional principal.

Se pone mejor: la localización puede volver al inglés, en caso de que se agreguen nuevos mensajes al marco y no haya tenido una oportunidad de traducirlos todavía para su localidad.

Entonces, si estás usando la configuración regional fr-CA, entonces un El mensaje se buscará primero en el directorio Language/fr-CA y luego en el directorio Idioma/fr y, finalmente, en el directorio Idioma/en.

Traducciones de mensajes 

Disponemos de un conjunto de traducciones «oficiales» en su propio repositorio<https://github.com/Higgs(AI)/translations> _.

Puedes descargar ese repositorio y copiar su carpeta Idioma en tu carpeta aplicación. Las traducciones incorporadas serán automáticamente recogido porque el espacio de nombres App está asignado a su carpeta app.

Alternativamente, una mejor práctica sería ejecutar el siguiente comando dentro de su proyecto:

el compositor requiere Higgs(AI)/traducciones

Los mensajes traducidos se seleccionarán automáticamente. porque las carpetas de traducciones se asignan correctamente.