User Guides

Localisation

Creating localised websites with LexasCMS is incredibly simple. In fact, it is possible to add multilingual support to a new or existing website without touching a single route config, template or controller.


Configuring Locales

The first thing you'll need to do, is enable localisation and define the locales that your website will support. You can do this by following the below example.

Note: LexasCMS comes preconfigured with an en (English) locale which will be used as the default locale. You only need to specify additional locales in the config file.

# config/default/l10n.yaml
enabled: true
locales:
  fr: { label: French }
  de: { label: German }

Once you have enabled localisation and defined your required locales, the admin panel will automatically begin to display a sidebar while editing content, allowing you to switch the locale that you are currently editing.


Configuring Translatable Content

In LexasCMS, there are two types of translatable content, dynamic and static.

Dynamic Content

This is content that is populated and managed using the admin panel, and will likely make up a majority of your websites translatable content.

By default, all content fields will be defined as "translatable", storing content on a per-locale basis. You can mark fields as "non-translatable" by setting the translatable key in the fields configuration to false.

# config/default/content.yaml
sections:
  Services:
    fields:
      - { name: "heading", type: "text", title: "Page Heading" }
      - { name: "banner", type: "image", widths: [1140], title: "Page Banner", translatable: false }
      - { name: "copy", type: "html", title: "Page Copy" }

As you can see from the example above, the banner field has been declared as not translatable while the heading and copy fields are both still translatable.

Static Content

This content is populated using config files, and is useful for providing translations for things such as menus and headings that are usually just hard coded in your templates.

Translation config files are placed in the config/_ENVIRONMENT_/translations/ directory and are named using the locales key. See the examples below:

# config/default/translations/en.yaml
hello_world: Hello World!
hello_user: Hello {user}!

### --- ###

# config/default/translations/fr.yaml
hello_world: Bonjour le monde!
hello_user: Bonjour {user}!

You can then access these translations from a template using the translate template helper.

Alternatively, you can access the translations in a controller using the Localisation classes translate() method.


Accessing Localised Content

The simplest way to load your website with localised content is to prefix your URL paths with the key of the locale you would like to load.

Imagine your website was running on the domain www.example.com. By default, if you were to visit http://www.example.com on your browser, the English content would be loaded. However, if you were to visit http://www.example.com/fr/, LexasCMS would automatically load your websites French content.

For example, to visit your websites French about page, you would visit http://www.example.com/fr/about/ in your browser, rather than http://www.example.com/about/.

Manually Define Locale

If you would like to use a sub-domain based approach to localisation, or if you need to manually define which locale should be loaded, you can define the LEXASCMS_LOCALE PHP constant in your websites index.php. This constant tells LexasCMS which locale should be loaded.

// index.php
<?php

// Set locale based on sub-domain
if ($_SERVER['HTTP_HOST'] === "fr.example.com") {
  define("LEXASCMS_LOCALE", "fr");
}

require_once("phar://LexasCMS.phar/init.php");
Note: Manually defining the locale using this method will disable the automatic localisation of URLs in the request classes composeHref method and in template helpers such as linkTo, routeHref etc.

Further Reading

You can find full documentation for the Localisation class in the full API reference.