Translate¶

Initialisieren der i18n Datenbank-Tabellen¶

Man kann entweder die CakePHP-Konsole dazu verwenden oder die Tabellen manuell erzeugen. Es wird aber empfohlen, die Konsole zu verwenden, da sich das Layout in künftigen Versionen von CakePHP ändern könnte. Die Arbeit mit der Konsole stellt sicher, dass das korrekte Layout benutzt wird.

./cake i18n

Wenn man [I] eingibt, wir das Initialisierungs-Skript für die i18n-Datenbank aufgerufen. Danach wird gefragt, ob man eine existierende Datenbank löschen möchte und man eine Datenbank erzeugen möchte. Wenn man sich sicher ist, dass man noch keine i18n-Tabelle hat, antwortet man mit yes. Das zweite yes erzeugt dann die Tabelle.

Das Translate-Behavior an eigene Models binden¶

Mit der $actsAs-Eigenschaft fügt man es wie im folgenden Beispiel zu seinem Model hinzu.

<?php
class Post extends AppModel {
    var $name = 'Post';
    var $actsAs = array(
        'Translate'
    );
}
?>

Dies führt so noch zu keinen Ergebnis, da einige Optionen erwartet werden. Man muss definieren, welche Felder des aktuellen Models in der Übersetzungs-Tabelle gesucht werden sollen, die in einem ersten Schritt erzeugt wurde.

Defining the Fields¶

You can set the fields by simply extending the 'Translate' value with another array, like so:

<?php
class Post extends AppModel {
    var $name = 'Post';
    var $actsAs = array(
        'Translate' => array(
            'fieldOne', 'fieldTwo', 'and_so_on'
        )
    );
}
?>

After you have done that (for example putting „name“ as one of the fields) you already finished the basic setup. Great! According to our current example the model should now look something like this:

<?php
class Post extends AppModel {
    var $name = 'Post';
    var $actsAs = array(
        'Translate' => array(
            'name'
        )
    );
}
?>

When defining fields for TranslateBehavior to translate, be sure to omit those fields from the translated model’s schema. If you leave the fields in, there can be issues when retrieving data with fallback locales.

Conclusion¶

From now on each record update/creation will cause TranslateBehavior to copy the value of „name“ to the translation table (default: i18n) along with the current locale. A locale is the identifier of the language, so to speak.

The current locale is the current value of Configure::read('Config.language'). The value of Config.language is assigned in the L10n Class - unless it is already set. However, the TranlateBehavior allows you to override this on-the-fly, which allows the user of your page to create multiple versions without the need to change his preferences. More about this in the next section.

Retrieve all translation records for a field¶

If you want to have all translation records attached to the current model record you simply extend the field array in your behavior setup as shown below. The naming is completely up to you.

<?php
class Post extends AppModel {
    var $name = 'Post';
    var $actsAs = array(
        'Translate' => array(
            'name' => 'nameTranslation'
        )
    );
}
?>

With this setup the result of $this->Post->find() should look something like this:

Array
(
     [Post] => Array
         (
             [id] => 1
             [name] => Beispiel Eintrag
             [body] => lorem ipsum...
             [locale] => de_de
         )

     [nameTranslation] => Array
         (
             [0] => Array
                 (
                     [id] => 1
                     [locale] => en_us
                     [model] => Post
                     [foreign_key] => 1
                     [field] => name
                     [content] => Example entry
                 )

             [1] => Array
                 (
                     [id] => 2
                     [locale] => de_de
                     [model] => Post
                     [foreign_key] => 1
                     [field] => name
                     [content] => Beispiel Eintrag
                 )

         )
)

Note: The model record contains a virtual field called „locale“. It indicates which locale is used in this result.

Note that only fields of the model you are directly doing `find` on will be translated. Models attached via associations won’t be translated because triggering callbacks on associated models is currently not supported.

$this->Post->bindTranslation(array ('name' => 'nameTranslation'));
$this->Post->find('all', array ('recursive'=>1)); // need at least recursive 1 for this to work.

Array
(
     [Post] => Array
         (
             [id] => 1
             [name] => Beispiel Eintrag
             [body] => lorem ipsum...
             [locale] => de_de
         )

     [nameTranslation] => Array
         (
             [0] => Array
                 (
                     [id] => 1
                     [locale] => en_us
                     [model] => Post
                     [foreign_key] => 1
                     [field] => name
                     [content] => Example entry
                 )

             [1] => Array
                 (
                     [id] => 2
                     [locale] => de_de
                     [model] => Post
                     [foreign_key] => 1
                     [field] => name
                     [content] => Beispiel Eintrag
                 )

         )
)

Saving in another language¶

You can force the model which is using the TranslateBehavior to save in a language other than the one detected.

To tell a model in what language the content is going to be you simply change the value of the $locale property on the model before you save the data to the database. You can do that either in your controller or you can define it directly in the model.

Example A: In your controller

<?php
class PostsController extends AppController {
    var $name = 'Posts';

    function add() {
        if ($this->data) {
            $this->Post->locale = 'de_de'; // we are going to save the german version
            $this->Post->create();
            if ($this->Post->save($this->data)) {
                $this->redirect(array('action' => 'index'));
            }
        }
    }
}
?>

Example B: In your model

<?php
class Post extends AppModel {
    var $name = 'Post';
    var $actsAs = array(
        'Translate' => array(
            'name'
        )
    );

    // Option 1) just define the property directly
    var $locale = 'en_us';

    // Option 2) create a simple method
    function setLanguage($locale) {
        $this->locale = $locale;
    }
}
?>

Multiple Translation Tables¶

If you expect a lot of entries you probably wonder how to deal with a rapidly growing database table. There are two properties introduced by TranslateBehavior that allow you to specify which „Model“ to bind as the model containing the translations.

These are $translateModel and $translateTable.

Lets say we want to save our translations for all posts in the table „post_i18ns“ instead of the default „i18n“ table. To do so you need to setup your model like this:

<?php
class Post extends AppModel {
    var $name = 'Post';
    var $actsAs = array(
        'Translate' => array(
            'name'
        )
    );

    // Use a different model (and table)
    var $translateModel = 'PostI18n';
}
?>

Important to note is that you have to pluralize the table. It is now a usual model and can be treated as such and thus comes with the conventions involved. The table schema itself must be identical with the one generated by the CakePHP console script. To make sure it fits one could just initialize an empty i18n table using the console and rename the table afterwards.

<?php
class PostI18n extends AppModel {
    var $displayField = 'field'; // important
}
// filename: post_i18n.php
?>

<?php
class Post extends AppModel {
    var $name = 'Post';
    var $actsAs = array(
        'Translate' => array(
            'name'
        )
    );

    // Use a different model
    var $translateModel = 'PostI18n';

    // Use a different table for translateModel
    var $translateTable = 'post_translations';
}
?>