Internacionalización · Documentación de Koshkil

Archivos de traducción

Las traducciones son archivos JSON, uno por idioma y dominio (un dominio agrupa textos de un área: common, errors, validation, admin, menu, api, messages…).

config/locales/
├── es/common.json
├── es/errors.json
├── en/common.json
└── pt/common.json
plugins/<plugin>/config/locales/es/<dominio>.json    traducciones de un plugin

{
  "save": "Guardar",
  "record_not_found": "{type} no encontrado",
  "user": {
    "greeting": "Hola, {name}"
  }
}

Las claves son relativas al archivo y usan puntos para los niveles: en el dominio common, user.greeting es "Hola, {name}". Los {parámetros} se reemplazan al traducir.

Traducir en PHP

__('save');                                          // dominio common
__('user.greeting', ['name' => 'Ana']);              // "Hola, Ana"
__('record_not_found', ['type' => 'Producto'], 'errors');
__('main', [], 'menu', 'noticias');                  // traducción de un plugin
__d('errors', 'not_found');                          // atajo con el dominio primero
__n('item', 'items', $cantidad);                     // singular / plural
I18n::translate('save');                             // la forma larga

Si la clave no existe en el idioma actual, se busca en el idioma por defecto. Si tampoco existe, se devuelve la clave (con returnKeyOnMissing) y, con logMissingKeys, se registra en el log.

Traducir en plantillas

{t key='save'}
{t key='user.greeting' name=$usuario->usr_nombre}
{t key='not_found' domain='errors'}
{t key='main' domain='menu' plugin='noticias'}
{t key='save' assign='textoBoton'}                 {* guarda en $textoBoton *}

{trans domain='validation'}required_field{/trans}
{'save'|t}

Idioma actual

El controlador fija el idioma al construirse, con esta prioridad:

El parámetro apiParameterName de la petición (por defecto ?language=en), solo para esa petición.
El valor guardado en la sesión con la clave sessionKey (por defecto Language.abbreviature).
defaultLanguage.

I18n::getLanguage();                  // 'es'
I18n::setLanguage('pt');              // solo si está en availableLanguages
I18n::getAvailableLanguages();

// Recordar la elección del usuario
$this->Session->write('Language.abbreviature', 'en');

Configuración

config/i18n.php (sobrescribible por dominio):

Clave	Uso
`defaultLanguage`, `fallbackLanguage`	Idioma por defecto y de respaldo.
`availableLanguages`	Idiomas permitidos, por ejemplo `['es', 'en', 'pt']`.
`autoload`, `autoloadDomains`	Dominios que se cargan al iniciar (por defecto `common` y `errors`). El resto se carga al primer uso.
`autoloadPlugins`	Buscar traducciones en los plugins activos.
`cache`	Guardar los JSON ya leídos en la caché `i18n`.
`logMissingKeys`, `returnKeyOnMissing`	Comportamiento ante claves faltantes.
`apiParameterName`, `sessionKey`	Parámetro y clave de sesión del idioma.
`pluralRules`	Regla de plural por idioma (función que recibe la cantidad).

Traducciones en JavaScript

El panel expone las traducciones al navegador desde Admin/Js/I18nController (/admin/js/i18n.js), para usarlas en los scripts del panel.

Contenido traducible

Para registros de la base traducidos a varios idiomas (nombres de categorías, noticias…), los modelos usan TTranslatableTrait: cada traducción es otro registro con idi_codigo y una referencia al registro principal. Ver Modelos.