Translate¶

Um Tour Rápido¶

Depois de criar a tabela i18n no seu banco de dados, anexe o comportamento a qualquer objeto da Tabela que você deseja tornar traduzível:

class ArticlesTable extends Table
{
    public function initialize(array $config)
    {
        $this->addBehavior('Translate', ['fields' => ['title']]);
    }
}

Agora, selecione um idioma a ser usado para recuperar entidades alterando o idioma do aplicativo, o que afetará todas as traduções:

// Em um controlador. Alterar a localidade, por exemplo para espanhol
I18n::setLocale('es');
$this->loadModel('Articles');

Em seguida, obtenha uma entidade existente:

$article = $this->Articles->get(12);
echo $article->title; // Eco em 'Um título', ainda não traduzido

Em seguida, traduza sua entidade:

$article->title = 'Un Artículo';
$this->Articles->save($article);

Agora você pode tentar obter sua entidade novamente:

$article = $this->Articles->get(12);
echo $article->title; // Echo em 'Un Artículo', yay pedaço de bolo!

O trabalho com várias traduções pode ser feito usando uma trait especial na sua classe Entity:

use Cake\ORM\Behavior\Translate\TranslateTrait;
use Cake\ORM\Entity;

class Article extends Entity
{
    use TranslateTrait;
}

Agora você pode encontrar todas as traduções para uma única entidade:

$article = $this->Articles->find('translations')->first();
echo $article->translation('es')->title; // 'Un Artículo'

echo $article->translation('en')->title; // 'An Article';

É igualmente fácil salvar várias traduções ao mesmo tempo:

$article->translation('es')->title = 'Otro Título';
$article->translation('fr')->title = 'Un autre Titre';
$this->Articles->save($article);

Se você quiser se aprofundar em como ele funciona ou como ajustar o comportamento às suas necessidades, continue lendo o restante deste capítulo.

Inicializando a Tabela do Banco de Dados i18n¶

Para usar o comportamento, você precisa criar uma tabela i18n com o esquema correto. Atualmente, a única maneira de carregar a tabela i18n é executando manualmente o seguinte script SQL no seu banco de dados:

CREATE TABLE i18n (
    id int NOT NULL auto_increment,
    locale varchar(6) NOT NULL,
    model varchar(255) NOT NULL,
    foreign_key int(10) NOT NULL,
    field varchar(255) NOT NULL,
    content text,
    PRIMARY KEY     (id),
    UNIQUE INDEX I18N_LOCALE_FIELD(locale, model, foreign_key, field),
    INDEX I18N_FIELD(model, foreign_key, field)
);

O esquema também está disponível como arquivo sql em /config/schema/i18n.sql.

Uma observação sobre as abreviações de idioma: O comportamento de tradução não impõe restrições ao identificador de idioma; os valores possíveis são restritos apenas pelo tipo/tamanho da coluna locale. locale é definido como varchar(6) caso você queira usar abreviações como es-419 (espanhol para América Latina, abreviação de idioma com código de área UN M.49).

Portanto, é recomendável usar o código ISO de duas letras do idioma como en, fr, de ou o nome completo da localidade, como fr_FR, es_AR , da_DK, que contém o idioma e o país em que é falado.

Anexando o Comportamento da Conversão às suas Tabelas¶

Anexar o comportamento pode ser feito no método initialize() na sua classe Table:

class ArticlesTable extends Table
{

    public function initialize(array $config)
    {
        $this->addBehavior('Translate', ['fields' => ['title', 'body']]);
    }
}

A primeira coisa a observar é que você deve passar a chave fields na matriz de configuração. Essa lista de campos é necessária para informar ao comportamento quais colunas serão capazes de armazenar traduções.

class ArticlesTable extends Table
{
    public function initialize(array $config)
    {
        $this->addBehavior('Translate', [
            'fields' => ['title', 'body'],
            'translationTable' => 'ArticlesI18n'
        ]);
    }
}

Lendo Conteúdo Traduzido¶

Como mostrado acima, você pode usar o método setLocale() para escolher a tradução ativa para entidades que são carregadas:

// Carregue as funções principais do I18n no início do seu Controller:
use Cake\I18n\I18n;

// Depois, você pode alterar o idioma em sua ação:
I18n::setLocale('es');
$this->loadModel('Articles');

// Todas as entidades nos resultados conterão tradução para o espanhol
$results = $this->Articles->find()->all();

Este método funciona com qualquer localizador em suas tabelas. Por exemplo, você pode usar o TranslateBehavior com find('list'):

I18n::setLocale('es');
$data = $this->Articles->find('list')->toArray();

// Os dados conterão
[1 => 'Mi primer artículo', 2 => 'El segundo artículo', 15 => 'Otro articulo' ...]

// Encontre o primeiro artigo com todas as traduções correspondentes
$article = $this->Articles->find('translations')->first();

// Saídas 'en'
echo $article->_translations['en']->locale;

// Saídas 'title'
echo $article->_translations['en']->field;

// Saídas 'My awesome post!'
echo $article->_translations['en']->body;

use Cake\ORM\Behavior\Translate\TranslateTrait;
use Cake\ORM\Entity;

class Article extends Entity
{
    use TranslateTrait;
}

// Saída de 'title'
echo $article->translation('en')->title;

// Adiciona uma nova entidade de dados de tradução ao artigo
$article->translation('de')->title = 'Wunderbar';

$results = $this->Articles->find('translations', [
    'locales' => ['en', 'es']
]);
$article = $results->first();
$spanishTranslation = $article->translation('es');
$englishTranslation = $article->translation('en');

class ArticlesTable extends Table
{
    public function initialize(array $config)
    {
        $this->addBehavior('Translate', [
            'fields' => ['title', 'body'],
            'allowEmptyTranslations' => false
        ]);
    }
}

$article = $this->Articles->find('translations')->contain([
    'Categories' => function ($query) {
        return $query->find('translations');
    }
])->first();

// Saídas 'Programación'
echo $article->categories[0]->translation('es')->name;

I18n::setLocale('en'); // redefinir para ilustração

$this->loadModel('Articles');

// localidade específica. Use locale () anterior à 3.6
$this->Articles->setLocale('es');

$article = $this->Articles->get(12);
echo $article->title; // Echoes 'Un Artículo', yay piece of cake!

I18n::setLocale('en'); // Reseta para ilustração

$this->loadModel('Articles');
// Use locale() anterior à 3.6
$this->Articles->setLocale('es');
$this->Articles->Categories->setLocale('es');

$data = $this->Articles->find('all', ['contain' => ['Categories']]);

// Use locale() anterior à 3.6
$this->Articles->setLocale('es');
$data = $this->Articles->find()->where([
    $this->Articles->translationField('title') => 'Otro Título'
]);

Salvando em Outro Idioma¶

A filosofia por trás do TranslateBehavior é que você tem uma entidade que representa o idioma padrão e várias traduções que podem substituir determinados campos nessa entidade. Tendo isso em mente, você pode salvar intuitivamente traduções para qualquer entidade. Por exemplo, dada a seguinte configuração:

// Em src/Model/Table/ArticlesTable.php
class ArticlesTable extends Table
{
    public function initialize(array $config)
    {
        $this->addBehavior('Translate', ['fields' => ['title', 'body']]);
    }
}

// Em src/Model/Entity/Article.php
class Article extends Entity
{
    use TranslateTrait;
}

// Em um Controller
$this->loadModel('Articles');
$article = new Article([
    'title' => 'My First Article',
    'body' => 'This is the content',
    'footnote' => 'Some afterwords'
]);

$this->Articles->save($article);

Portanto, depois de salvar seu primeiro artigo, você pode salvar uma tradução para ele, existem algumas maneiras de fazê-lo. O primeiro é definir o idioma diretamente na entidade:

$article->_locale = 'es';
$article->title = 'Mi primer Artículo';

$this->Articles->save($article);

Depois que a entidade tiver sido salva, o campo traduzido também será mantido. Um valor a ser observado é que os valores do idioma padrão que não foram substituídos serão preservados:

// Saídas 'Este é o conteúdo'
echo $article->body;

// Saídas 'Mi primer Artículo'
echo $article->title;

Depois de substituir o valor, a conversão para esse campo será salva e poderá ser recuperada como de costume:

$article->body = 'El contendio';
$this->Articles->save($article);

A segunda maneira de usar para salvar entidades em outro idioma é definir o idioma padrão diretamente para a tabela:

$article->title = 'Mi Primer Artículo';

// Use locale() anterior à 3.6
$this->Articles->setLocale('es');
$this->Articles->save($article);

Definir o idioma diretamente na tabela é útil quando você precisa recuperar e salvar entidades para o mesmo idioma ou quando você precisa salvar várias entidades ao mesmo tempo.

Salvando Várias Traduções¶

É um requisito comum poder adicionar ou editar várias traduções em qualquer registro do banco de dados ao mesmo tempo. Isso pode ser feito usando o TranslateTrait:

use Cake\ORM\Behavior\Translate\TranslateTrait;
use Cake\ORM\Entity;

class Article extends Entity
{
    use TranslateTrait;
}

Agora, você pode preencher as traduções antes de salvá-las:

$translations = [
    'fr' => ['title' => "Un article"],
    'es' => ['title' => 'Un artículo']
];

foreach ($translations as $lang => $data) {
    $article->translation($lang)->set($data, ['guard' => false]);
}

$this->Articles->save($article);

A partir do 3.3.0, o trabalho com várias traduções foi simplificado. Você pode criar controles de formulário para seus campos traduzidos:

// Em um template.
<?= $this->Form->create($article); ?>
<fieldset>
    <legend>French</legend>
    <?= $this->Form->control('_translations.fr.title'); ?>
    <?= $this->Form->control('_translations.fr.body'); ?>
</fieldset>
<fieldset>
    <legend>Spanish</legend>
    <?= $this->Form->control('_translations.es.title'); ?>
    <?= $this->Form->control('_translations.es.body'); ?>
</fieldset>

No seu controlador, você pode organizar os dados normalmente:

$article = $this->Articles->newEntity($this->request->getData());
$this->Articles->save($article);

Isso resultará no seu artigo, que todas as traduções em francês e espanhol serão mantidas. Você precisará se lembrar de adicionar _translations aos campos $ _accessible da sua entidade também.

class ArticlesTable extends Table
{
    public function initialize(array $config)
    {
        $this->addBehavior('Translate', [
            'fields' => ['title'],
            'validator' => 'translated'
        ]);
    }
}