The translation model generates classes that are used to facilitate the creation of multi-lingual websites. You may want to use this model even though your website only supports a single language because the generated classes also allow hard coded text to be removed from forms and program logic to make it easier to alter the vernacular used within your user interface without having to make program changes.

Language

Each translation definition must be associated with a certain language. Normally the translation model is used to define translations for your main language then the translate model is used to translate these strings into other languages.

translation Model Columns

The first two columns of a translation specification are mandatory. The first column defines a translation identifier and must be unique within a given set of translations. The second column defines the translation to be associated with the identifier for the current language. Generally, this column is used to store form labels however you could use this for some other specialized purpose.

Any number of additional columns can be added according to your translation requirements. The column heading is an identifier and must be unique.

Mobile Labels

Recall that the field property *label-mobile takes the place of the *label property when the user is on a phone or other small device. Similar functionality is achieved by defining a column named short_label within translation objects. Here we see that you only need to enter short_label values for the labels you want to shorten since the other ones will revert to the label values.

Configuring Infoboxes

A common use case for translations is for infobox help.  To configure these, the translation must include the columns with heading info_head and info_body as illustrated here.

Notice that row 3 contains translations associated with the empty_cell_handling field. Here we see an example of how these are used:

Often the heading of the infobox is the same value as the label for the field. In such a case, you can use the short form notation = under the info_head column rather than re-typing the label.

Accessing the Translations

There are many ways that the translations can be accessed and incorporated into your website. Here we discuss several common methods.

Form Labels

The form model specification contains two properties related to translations.

1. The Translation Class refers to a definition stowed by the translation model. 
2. The Default Label indicates how :: is to resolved when entered in a cell preceding a a field reference.

When Default Label contains a ?, the :: placeholder will be substituted with a label that includes an infobox like the one show above. If Default Label contains :, the label will be translated without an infobox.

In all cases the translation returned will be associated with the site's current language setting. If the translation is not found, it will attempt to fallback to the English values.

Using $translate

dollar]translate(class,variable,column) can be used to translate a particular variable. The column value reflects the column heading of the translation definition for the value to be returned.

Using $infolabel

$infolabel(class,variable) is passed the name of a translation class followed by a variable within the class definition. This will generate an infobox dropdown for the indicated field.

Calling site Class Method get_translation

To access any translation from your php classes simply call the get_translation method of the site object. The first parameter is the name of the translation class, this is followed by the variable (in column 1) of the translation. By default this returns the label translation but a third parameter can be passed to obtain a different translation value. For example:

$trans = $this->site->get_translation('form','date_of_birth','info_body');

Setting the Current Language

At startup, the framework checks for a cookie named _language. If defined, this will be used to set the current language value. This value can also include a locale component. This is done by setting the _language cookie in the format language-locale, for example en-US. Notice that language codes are in lower case and locale codes should be in upper case. 

One way to set this cookie is by invoking the page named set_language which is part of the system pseudo site so it can be invoked from any site. The language to be set must be passed in the query string using the language parameter.  By default, this system page will redirect back to the current page after changing the language. You can also pass the parameter redirect_to to redirect to an alternate page.

You can use the dollar function $language_links() to define links that can be used to change the current language and/or locale.

You can also programmatically set the language and locale by calling:

$this->site->set_language($language_code);
$this->site->set_locale($locale_code);

Translating Placeholders

If you are using the form model, you may want to take advantage of a feature to translate in-field placeholders. Consider the following html_field_type definition named req_text that defines a required text field and sets the placeholder to ?.

Here is a sample form that contains fields based upon this html_field_type as well as some other definitions that use placeholder:?.

To use this feature, the form or field must be linked to a translation class that contains a column named placeholder as shown here:

Notice that the shortcut = sign can be placed in the placeholder column if the value should match whatever is entered in the Label column. 

Recall that setting the field property placeholder:? indicates that you want to use the placeholder column of the translation class to obtain the translation. Another option is to set the placeholder property to

"?label".

In this case, the Label column will be used to obtain the placeholder value thereby eliminating the need for a placeholder column.

Here we see the English version of this form. The language link at the top of the form is rendered using $language_links(en,fr).

When the user clicks on the français link the page will change the default language to french and re-render showing the following translated version of the identical form.

Supported Examples

The example command can be used to load the following examples

example infobox

Build the columns to support standard infobox processing.

example dollar_function

Build the columns used for dollar function help.