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:
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:
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".
The $locale function can take 1, 2 or 3 parameters. These are described below.
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".
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)).
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.
As you can see in the locale translations specification above, ou and re are also common patterns for which this technique might be used for writing words like center/centre and color/colour.
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.