Localization

Datamapper ORM can automatically load in a model-specific language file, and then it can set language-specific labels on each field or relationship. When using this method, there is no need to specify the label key in the $validation array.

It uses the built-in CodeIgniter library for localizing. For more information on this library, please see the CodeIgniter manual.

Subsections:

• Localization
  • Recommended Method - Get started easily
  • Alternate Method - Different Technique
  • Handling Language Changes - Changing the default language
  • Configuration - Config Options
• Localizing Helper Methods - Helper methods for localizing
  • localize_label - Get a per-model, per-field localized string
  • localize_by_model - Custom localizations

Recommended Method

The easiest way to add localization is use the following language file standards:

• For each model, create a new language file under application/language/<lang>/ named model_${model}_lang.php, where ${model} is replaced with the model's $model property.
• Using the CodeIgniter standard, create a key for each field (and, optionally, relationship) using the format ${model}_${field}.

Example

 1
 2
 3
 4
 5
 6
 7
 8
<?php
// Language File for Comment Model
$lang['comment_comment']         = 'Comment';
$lang['comment_bug']             = 'Bug';
$lang['comment_user']            = 'User';

/* End of file model_comment_lang.php */
/* Location: ./application/language/english/model_comment_lang.php */

Believe it or not, that's it! You don't even have to load in the language file. You can easily create multiple-languages by duplicating the language files for each model into a different language folder, and loading them as needed.

If you are upgrading from a version of Datamapper ORM older than 1.7.0, make sure you add the new lang_file_format configuration option, and set it to model_${model}.

Alternate Method

If you don't want automatic loading, or you prefer hard-coding the labels, you can also manually set the label field using the format lang:lang_key.

Datamapper ORM will automatically replace that label with the appropriate language value, if it exists. Using this method, you can still have Datamapper ORM automatically load the language file using the lang_file_format property.

Example

class User extends DataMapper {
    var $validation = array(
        'name' => array(
            'label' => 'lang:user.fields.Name',
            'rules' => array('required')
        )
    );
}

Handling Language Changes

The best solution is to somehow determine the language before loading any models. If you can do that, then simply change $this->config->config['language'] and all models will use that.

However, if you need changing the language dynamically, such as when loading a user's preference, you can use reinitialize_model to to reload the language.

Please read the linked section carefully, however, as it doesn't update other models, or any other already existing objects, so it should be called as early as possible.

Configuration

Most of the time, simply standardizing your language file settings will be all you need to do. However, Datamapper ORM is very flexible in configuring which files to load, and how to look for the language keys.

Both of the properties can be set globally (in the config file, or on a per-model basis.

Loading the Language File

The language file is specified by the configuration option lang_file_format. If it is not provided, is empty, or the file does not exist, no language file will be loaded by default.

The default format is model_${model}.

The option has two properties that can be used to dynamically change the file name. Please note that these must be specified exactly, including the dollar-sign ($) and braces ({}).

• ${model}: This is replaced by the class's $model property.
• ${table}: This is replaced by the class's $table property.

The result of the updated property is passed directly to lang->load(). Note: The actual file name must end in _lang.php.

(If the file does not exist, Datamapper ORM won't attempt load it. This prevents errors when you don't have a language file for a given model.)

Loading the Field Labels

The keys for the field labels is specified by the configuration option field_label_lang_format.

The default format is ${model}_${field}.

In addition to the model and table properties, each field key has an additional property:

• ${field}: This is replaced by the field's name.

Localizing Helper Methods

You can actually use the new localizing tools for more than just field labels. They can also be used to dynamically load in properties based on model, table, and field names at any time, using the following two methods.

$object->localize_label($field)

This method will use the field_label_lang_format property to localize a given $field.

Example

function __toString() {
    return $this->exists() ? $this->name : $this->localize_label('unset');
}

$object->localize_by_model($key, $field)

This method will automatically replace ${model} and ${table} in the given $key, and return the localized string. If $field is passed, that replaces ${field} in the $key.

This may be useful for loading in other common localized strings. For example, you might use it in an extension like this:

// Returns a localized error string
function localize_error($object, $error) {
    return $object->localize_by_model('${model}_error_${field}', $error);
}

Previous Topic:      ·   Top of Page   ·   User Guide Home    ·   Next Topic: