Language variables

As with config variables, Outlast Framework provides a way to separate language items into a nicely organized, standardized, simple key/value ini file.

Unlike configuration files, language files are also defined for each supported locale in your app.

In addition to language files, there are many internationalization features of Outlast Framework. Check out the detailed info here.

Warning! Language variables and configuration variables use a shared namespace! This means that $this->zajlib->config->variable->example is the same exact variable as $this->zajlib->lang->variable->example (since in the template syntax both are {{#example#}}).

Setting up locales

In order to create language files, you must first set up locales in your app. Check out the documentation on this here.

You should also set the locale for your project, most often with $this->zajlib->lang->auto();.

Creating your language files

You should create a language file for each supported locale, making sure that all keys are translated in each file (you also can verify that all keys exist, see below).

The required naming convention for language files is /lang/my_name.en_US.lang.ini. So, you would typically place language files under /app/lang/myapp.en_US.lang.ini and then load them with $this->zajlib->lang->load('myapp');. More on this below…

Use in controllers

Once you have set up locales and created all the language files you are ready to load up languages in your controllers.

Use in views

Although usually it is better practice to load language files in a controller (see above), it may sometimes be necessary to load a language file directly from a view. You can do this with the {% lang %} tag. See documentation here.

Within Outlast Framework templates, language variables behave just like any other variable. The only difference is that they use the {{#example#}} syntax. But similar to variables, you can apply filters or pass them as parameters to tags or filters. Here are some examples:

Use in Javascript

To use language variables in Javascript you can set variables manually using ofw.setLang() (see docs).

Better yet, you can use the preferred method, the {% langjs %} tag (see docs) to load a specific lang section as a key/value list available via the ofw.lang object.

Since this will send language file data to the client side, make sure that you load as few keys as possible and avoid loading any sensitive data!

Example use:

Sections

You can use [section_names] to separate your language or configuration file in to multiple parts. This is useful to provide both visual and logical areas within the file. Here is an example:

Variables that are used more than once may overwrite one another, but you can also reference them directly. Here are some examples:

Placeholders

Placeholders are a way to specify where dynamic data will go within localized data. The syntax is with %1, %2, etc. where each item is replaced with specific data in the template.

Here is an example:

Variable language variables

Variable variables are available in PHP $var = 'asdf'; echo $$var; and for regular ofw variables. This same concept can also be used for language and configuration variables in the OFW template system by using the keyvalue filter on the {{ofw.config}} variable – this variable returns a list of all available language and config variables.

IMPORTANT! As we’ve mentioned before – config and language variables are in the same namespace. But for variable language variables you must use {{zaj.config}} because {{zaj.lang}} actually returns the two-letter language code. Using the keyvalue filter on {{zaj.lang}} will throw a warning.

Here’s an example:

Language variations: formal vs informal

Certain languages have different variations for formal and informal settings – in some cases even more than two variations.

You can add any number of variations by overriding only those keys that are different in the variation. So as an example in German “Wie heißt du?” (What’s your name – informal) vs “Wie heißen Sie?” (What’s your name – formal) can be used alongside “Danke!” (Thanks – same in formal and informal).

To define the variation you can create a new language file with the variation name used as an extension to the file name, so formfields.de_DE.lang.ini would be augmented with formfields.de_DE-formal.lang.ini. You can then specify that you want to use the formal version by setting locale_variation in site/index.php (see below in example) or by calling $this->zajlib->lang->set_variation('formal') (see docs) at runtime. After this each time a language file is loaded, the system will check to see if a ‘formal’ variation can be found for the current language file. If so, it too will be loaded after the default one (thus overwriting the identical keys).

Here’s a full example of how to define and load the language file variations:

Checking for missing keys

Outlast Framework’s unit test script (http://example.com/update/test/) will throw notices for any missing language file keys. You’ll get messages like Not all translations from hu_HU found in en_US (base/photo). Missing the following keys: fileselect. You should review this before going live with any site.

Localizing longer text or complex HTML

Language files are good for localizing short segments of texts or user interface elements. If you want to localize longer text or HTML you should either make this editable via admin using database value localization or you should use the {% insertlocale %} tag. For more info on this tag, check out the documentation.

You can also use the OFW content plugin which provides a full-fledged, multi-lingual content management system.

Localizing database values

Language files are a good way to localize static data, but you may want to also have localized versions of your database data, such as the name of a product in a shop.

Fortunately, OFW supports database value localization. Check out the documentation on this.