The locale model is used to facilitate the translation of words to accommodate variations and nuances in the vernacular used within different geographic locations that all speak a similar language. Consider the English words color and colour. The first spelling is generally used in the US whereas the second spelling is generally used in Canada and other historically British colonies. English has hundreds of words like this, with different spellings associated with different locales. In fact, many languages have different spellings of the same words in different locations.

The locale model is supported by the $locale function which is used to show a certain term in the locale assigned to the current website.

When To Use The locale Model

In many cases you may not want to bother making your website locale aware. This decision will often depend on the makeup of your audience which you can usually determine by looking at your site's statistics (using Google Analytics for example). If you discover that a large percentage of your users reside in the same country you may want to simply adopt the locale of that country rather than making it dynamic. On the other hand, if you find that a substantial percentage of your visitors reside in countries that have different vernaculars, you should consider adapting your site to cater to your different users.

Establishing The User's Locale

In order for the locale model and the $locale function to render an appropriate translation into the current web visitor's locale it is necessary to have a means of ascertaining what this is. The method you use to make this determination will vary by situation. Here are some common methods:

• If your users need to log into your system you will most likely have address (or at least country) information for your users so you could make use of the current user's address country to establish the locale for this user.
• If your site runs under multiple domains, such as example.com, example.ca, example.uk, you could use the domain or the top level domain to determine the locale setting. This can be ascertained using $site(tld).
• You can use the $geoloc(,string,:countryCode:) function to ascertain the current user's location based on their IP address.

Having determined the current user's country location you can use this to derive the most appropriate language and locale. Often this will be done in the startup class for your site (specified in site_settings). Consider the following code snippet:

$tld = $this->site->dollar_function('site','tld'); // Get the top level domain
$locale = ($tld === 'ca') ? 'CA' : 'US'; 
$this->site->set_locale($locale);  // Set site locale to either US or CA

// Set the HTML tag lang property to en-US or en-CA
$this->site->dollar_function('property','html','lang','en-'.$locale);

This code assumes that the current website can either be run from a .com domain or a .ca (Canada) domain and uses this information to set the current site locale and the html lang property.

Defining the Locale Translations

Consider the following locale specification named en.

The name en was chosen since the $locale function defaults to the current language when the name of the locale definition is not supplied. This makes it easier to code $locale functions since in most cases you only need to pass one parameter, that is the name of the variable to be translated.

locale Model Columns

The locale model allows any number of columns to be defined. The header row of the column corresponds to the Locale settings that may be in place when your website is running. In this example, the site is intended to have special translations for US English and the default setting will be used for all other locales (Canada, UK, etc.).

Notice that column one is used to define a locale variable (identifier). Often, this identifier will coincide with a word that you want to translate. In column two we enter the default translation for this identifier. We see that some rows have an equal sign in this column. This is a short form to indicate that the translation is the same as the identifier. For example, the identifier "centre" will be translated to "center" if the current locale is US, otherwise it will be translated to "centre".

Using $locale

The $locale function can take 1, 2 or 3 parameters. These are described below.

1. The first parameter must be the name of a variable identifier (column 1 of the locale definition)
2. The second parameter is optional and can be used to apply case translation
3. The third parameter can be used to supply the name of the locale specification containing the identifier. This defaults to the current language so, in our examples, since we named the specification "en", we can omit this parameter.

Consider the sentence "We accept $locale(cheque)s and credit cards".

If the current locale is set to US, this will be rendered as "We accept checks and credit cards". In all other cases, this will be rendered as "We accept cheques and credit cards".

Translating Units

Notice that the locale features can be used for things besides strictly translating words. Consider the phrase "Our materials can be using in temperatures as low as $locale(minus_20c)". In the US, this will be rendered as "Our materials can be using in temperatures as low as -4F". Everywhere else, this will render "Our materials can be using in temperatures as low as -20C".

This feature can extend to almost anything. Notice that one of the translations is named home_youtube. This was done so that a different video can be shown to US users vs. Canadian users. The video could be rendered using the nested dollar functions $youtube($locale(home_youtube)).

Character Translation

There are hundreds of English words that are written with an "s" in US English and a "z" in Canadian English. Here are just a few examples:

Rather than defining every such word that is used on your website, it might make sense to "cheat" and just define a translation for the letter z. In this case, we would write these words as:

capitali$locale(z)e will be written as capitalize or capitalise.

prioriti$locale(z)e will be written as prioritize or prioritise.

maximi$locale(z)e will be written as maximize or maximise.

Changing the Case Translation

The second parameter to the $locale function can be used for automated case translation. This allows you to use the same lower case translation for words that may appear at the beginning of a sentence.

Please refer back to the free_shipping variable shown on row 6 in the screen shot above. Here we show the various case outcomes controlled by the value passed  to $locale in parameter 2.