Internacionalização · Documentação do Koshkil

Arquivos de tradução

As traduções são arquivos JSON, um por idioma e domínio (um domínio agrupa textos de uma á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/pt/<domínio>.json    traduções de um plugin

{
  "save": "Salvar",
  "record_not_found": "{type} não encontrado",
  "user": {
    "greeting": "Olá, {name}"
  }
}

As chaves são relativas ao arquivo e usam pontos para os níveis: no domínio common, user.greeting é "Olá, {name}". Os {parâmetros} são substituídos na tradução.

Traduzir em PHP

__('save');                                          // domínio common
__('user.greeting', ['name' => 'Ana']);              // "Olá, Ana"
__('record_not_found', ['type' => 'Produto'], 'errors');
__('main', [], 'menu', 'noticias');                  // tradução de um plugin
__d('errors', 'not_found');                          // atalho com o domínio primeiro
__n('item', 'items', $quantidade);                   // singular / plural
I18n::translate('save');                             // a forma longa

Se a chave não existe no idioma atual, é procurada no idioma padrão. Se também não existir, a própria chave é retornada (com returnKeyOnMissing) e, com logMissingKeys, é registrada no log.

Traduzir em templates

{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='textoBotao'}                 {* guarda em $textoBotao *}

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

Idioma atual

O controlador define o idioma ao ser construído, com esta prioridade:

O parâmetro apiParameterName da requisição (padrão ?language=en), somente para aquela requisição.
O valor guardado na sessão com a chave sessionKey (padrão Language.abbreviature).
defaultLanguage.

I18n::getLanguage();                  // 'pt'
I18n::setLanguage('en');              // só se estiver em availableLanguages
I18n::getAvailableLanguages();

// Lembrar a escolha do usuário
$this->Session->write('Language.abbreviature', 'pt');

Configuração

config/i18n.php (pode ser sobrescrito por domínio):

Chave	Uso
`defaultLanguage`, `fallbackLanguage`	Idioma padrão e de reserva.
`availableLanguages`	Idiomas permitidos, por exemplo `['es', 'en', 'pt']`.
`autoload`, `autoloadDomains`	Domínios carregados na inicialização (por padrão `common` e `errors`). Os demais são carregados no primeiro uso.
`autoloadPlugins`	Procurar traduções nos plugins ativos.
`cache`	Guardar os JSON já lidos no cache `i18n`.
`logMissingKeys`, `returnKeyOnMissing`	Comportamento diante de chaves ausentes.
`apiParameterName`, `sessionKey`	Parâmetro e chave de sessão do idioma.
`pluralRules`	Regra de plural por idioma (uma função que recebe a quantidade).

Traduções em JavaScript

O painel expõe as traduções ao navegador por meio de Admin/Js/I18nController (/admin/js/i18n.js), para uso nos scripts do painel.

Conteúdo traduzível

Para registros do banco traduzidos para vários idiomas (nomes de categorias, notícias…), os modelos usam TTranslatableTrait: cada tradução é outro registro com idi_codigo e uma referência ao registro principal. Veja Modelos.