Installation

To install using October CMS v3.1 or above:

php artisan plugin:install rainlab.translate

To install using October CMS v3.0 and below:

php artisan plugin:install rainlab.translate --want="^1.0"

Upgrading from v1 to v2

If you are upgrading from version 1 of this plugin, view the upgrade guide.

Language Picker Component

A visitor can select their chosen language using the native SitePicker component that is included in the October CMS core. This component will display a simple dropdown that changes the page language depending on the selection.

title = "Home"
url = "/"

[sitePicker]
==

<h3>{{ 'Please select your language:'|_ }}</h3>
<select class="form-control" onchange="window.location.assign(this.value)">
    {% for site in sitePicker.sites %}
        <option value="{{ site.url }}" {{ this.site.code == site.code ? 'selected' }}>{{ site.name }}</option>
    {% endfor %}
</select>

If translated, the text above will appear as whatever language is selected by the user. The dropdown is very basic and is intended to be restyled. A simpler example might be:

<p>
    Switch language to:

    {% for site in sitePicker.sites %}
        <a href="{{ site.url }}">{{ site.name }}</a>
    {% endfor %}
</p>

Message Translation

Message or string translation is the conversion of adhoc strings used throughout the site. A message can be translated with parameters.

{{ 'site.name'|_ }}

{{ 'Welcome to our website!'|_ }}

{{ 'Hello :name!'|_({ name: 'Friend' }) }}

A message can also be translated for a choice usage.

{{ 'There are no apples|There are :number applies!'|__(2, { number: 'two' }) }}

Or you set a locale manually by passing a second argument.

{{ 'this is always english'|_({}, 'en') }}

Themes can provide default values for these messages by defining a translate key in the theme.yaml file, located in the theme directory.

name: My Theme
# [...]

translate:
    en:
        site.name: 'My Website'
        nav.home: 'Home'
        nav.video: 'Video'
        title.home: 'Welcome Home'
        title.video: 'Screencast Video'

You may also define the translations in a separate file, where the path is relative to the theme. The following definition will source the default messages from the file config/lang.yaml inside the theme.

name: My Theme
# [...]

translate: config/lang.yaml

This is an example of config/lang.yaml file with two languages:

en:
    site.name: 'My Website'
    nav.home: 'Home'
    nav.video: 'Video'
    title.home: 'Welcome Home'
hr:
    site.name: 'Moje web stranice'
    nav.home: 'Početna'
    nav.video: 'Video'
    title.home: 'Dobrodošli'

You may also define the translations in a separate file per locale, where the path is relative to the theme. The following definition will source the default messages from the file config/lang-en.yaml inside the theme for the english locale and from the file config/lang-fr.yaml for the french locale.

name: My Theme
# [...]

translate:
    en: config/lang-en.yaml
    fr: config/lang-fr.yaml

This is an example for the config/lang-en.yaml file:

site.name: 'My Website'
nav.home: 'Home'
nav.video: 'Video'
title.home: 'Welcome Home'

In order to make these default values reflected to your frontend site, go to Settings -> Translate messages in the backend and hit Scan for messages. They will also be loaded automatically when the theme is activated.

The same operation can be performed with the translate:scan artisan command. It may be worth including it in a deployment script to automatically fetch updated messages:

php artisan translate:scan

Add the --purge option to clear old messages first:

php artisan translate:scan --purge

Content & Mail Template Translation

This plugin activates a feature in the CMS that allows content & mail template files to use language suffixes, for example:

• welcome.htm will contain the content or mail template in the default language.
• welcome-ru.htm will contain the content or mail template in Russian.
• welcome-fr.htm will contain the content or mail template in French.

Model Translation

Models can have their attributes translated by using the RainLab\Translate\Behaviors\TranslatableModel behavior and specifying which attributes to translate in the class.

class User
{
    public $implement = [
        \RainLab\Translate\Behaviors\TranslatableModel::class
    ];

    public $translatable = ['name'];
}

The attribute will then contain the default language value and other language code values can be created by using the translateContext() method.

$user = User::first();

// Outputs the name in the default language
echo $user->name;

$user->translateContext('fr');

// Outputs the name in French
echo $user->name;

You may use the same process for setting values.

$user = User::first();

// Sets the name in the default language
$user->name = 'English';

$user->translateContext('fr');

// Sets the name in French
$user->name = 'Anglais';

The lang() method is a shorthand version of translateContext() and is also chainable.

// Outputs the name in French
echo $user->lang('fr')->name;

This can be useful inside a Twig template.

{{ user.lang('fr').name }}

There are ways to get and set attributes without changing the context.

// Gets a single translated attribute for a language
$user->getAttributeTranslated('name', 'fr');

// Sets a single translated attribute for a language
$user->setAttributeTranslated('name', 'Jean-Claude', 'fr');

Theme Data Translation

It is also possible to translate theme customisation options. Just mark your form fields with translatable property and the plugin will take care about everything else:

tabs:
    fields:
        website_name:
            tab: Info
            label: Website Name
            type: text
            default: Your website name
            translatable: true

Fallback Attribute Values

By default, untranslated attributes will fall back to the default locale. This behavior can be disabled by calling the noFallbackLocale method when reading the value.

$user = User::first();

$user->noFallbackLocale()->lang('fr');

// Returns NULL if there is no French translation
$user->name;

When writing the value, the fallback value is determined when the translated value matches the default value. In these cases, the translated value is considered untranslated and not stored.

For example, if the en default locale stores the message as "Hello World" and the fr locale value is also "Hello World", then the fr value is not stored. The fr value is accessed using the fallback value taken from en.

You may disable this behavior by passing the $transatable attribute value as an array. The first value is the attribute name, the other values represent options, in this case setting the option fallback to false.

public $translatable = [
    ['title', 'fallback' => false]
];

This above definition will force the title attribute value to be duplicated and stored across all locales.

Indexed Attributes

Translatable model attributes can also be declared as an index by passing the $transatable attribute value as an array. The first value is the attribute name, the other values represent options, in this case setting the option index to true.

public $translatable = [
    'name',
    ['slug', 'index' => true]
];

Once an attribute is indexed, you may use the transWhere method to apply a basic query to the model.

Post::transWhere('slug', 'hello-world')->first();

The transWhere method accepts a third argument to explicitly pass a locale value, otherwise it will be detected from the environment.

Post::transWhere('slug', 'hello-world', 'en')->first();

URL Translation

Pages in the CMS support translating the URL property. Assuming you have 3 languages set up:

• en: English
• fr: French
• ru: Russian

There is a page with the following content:

url = "/contact"

[viewBag]
localeUrl[ru] = "/контакт"
==
<p>Page content</p>

The word "Contact" in French is the same so a translated URL is not given, or needed. If the page has no URL override specified, then the default URL will be used. Pages will not be duplicated for a given language.

• /fr/contact - Page in French
• /en/contact - Page in English
• /ru/контакт - Page in Russian
• /ru/contact - 404

Translating URLs in Twig

The localeUrl method will replace the route prefix on a URL from one locale to another. For example, converting the current request URL from en to de.

{{ this.request.url|localeUrl('de') }}

The localePage will return a translated URL for a CMS page. It takes a locale (first argument) and page parameters (second argument).

{{ 'blog/post'|localePage('de', { slug: 'foobar' }) }}

URL Parameter Translation

It's possible to translate URL parameters by listening to the cms.sitePicker.overrideParams event, which is fired when discovering language URLs.

Event::listen('cms.sitePicker.overrideParams', function($page, $params, $oldSite, $newSite) {
    if ($page->baseFileName == 'your-page-filename') {
        return MyModel::translateParams($params, $oldSite->hard_locale, $newSite->hard_locale);
    }
});

In MyModel, one possible implementation might look like this:

public static function translateParams($params, $oldLocale, $newLocale)
{
    $newParams = $params;
    foreach ($params as $paramName => $paramValue) {
        $records = self::transWhere($paramName, $paramValue, $oldLocale)->first();
        if ($records) {
            $records->translateContext($newLocale);
            $newParams[$paramName] = $records->$paramName;
        }
    }
    return $newParams;
}

Query String Translation

It's possible to translate query string parameters by listening to the cms.sitePicker.overrideQuery event, which is fired when switching languages.

Event::listen('cms.sitePicker.overrideQuery', function($page, $params, $oldSite, $newSite) {
    if ($page->baseFileName == 'your-page-filename') {
        return MyModel::translateParams($params, $oldSite->hard_locale, $newSite->hard_locale);
    }
});

For a possible implementation of the MyModel::translateParams method look at the example under URL parameter translation from above.

Extend Theme Scan

Event::listen('rainlab.translate.themeScanner.afterScan', function (ThemeScanner $scanner) {
    // ...
});

Settings Model Translation

It's possible to translate your settings model like any other model. To retrieve translated values use:

Settings::instance()->getAttributeTranslated('your_attribute_name');

Conditionally Extending Plugins

Models

It is possible to conditionally extend a plugin's models to support translation by placing an @ symbol before the behavior definition. This is a soft implement will only use TranslatableModel if the Translate plugin is installed, otherwise it will not cause any errors.

/**
 * Post Model for the blog
 */
class Post extends Model
{
    // [...]

    /**
     * @var array implement the TranslatableModel behavior softly.
     */
    public $implement = ['@'.\RainLab\Translate\Behaviors\TranslatableModel::class];

    /**
     * @var array translatable attributes, if available.
     */
    public $translatable = ['title'];

    // [...]
}

The back-end forms will automatically detect the presence of translatable fields and replace their controls for multilingual equivalents.

User Interface

Switching Locales

Users can switch between locales by clicking on the site selection menu in the backend panel. This will add a _site_id query value to the URL, allowing for multiple browser tabs to be used.

This guide can be used to help migrate from RainLab.Translate v1 to v2. It should be straight forward process without any major disruptions.

Beginning from October CMS v3.1, a multisite feature was introduced that supercedes many functions provided by the RainLab.Translate plugin. The existing data structures are preserved so all translations are carried across and no "retranslation" or modifying existing plugins should be needed.

Upgrade Instructions

1. Run php artisan plugin:install rainlab.translate to request the latest version (you do not need to uninstall v1 first).

2. Navigate to System → Sites and create a site for each locale used by the website.

3. Replace the localePicker and alternateHrefLangElements components used in the front end (see below).

4. Migrate theme messages using php artisan translate:migratev1 (non destructive).

5. Continue using this plugin as normal.

Key Differences

• The "Languages" settings area is replaced by the "Sites" settings area. This is where available sites are defined, including the available languages.

• The per-field language picker is replaced by a per-site language picker. The translator selects the active language globally and can perform comparisons using multiple browser tabs.

• Storing the locale in the session is no longer used and must be determined by the site definition, as a hostname or route prefix.

Key Similarities

• Models are still translated using the RainLab\Translate\Behaviors\TranslatableModel.

• Theme translation is still managed by this plugin.

Breaking Changes

Middleware class is replaced

If using PHP routes to determine locale, the RainLab\Translate\Classes\LocaleMiddleware class is replaced by the System\Middleware\ActiveSite middleware class.

CMS Components replaced

The localePicker and alternateHrefLangElements components provided by this plugin have been replaced by the sitePicker component.

Here is the sample code to replace the localePicker component:

<select class="form-control" onchange="window.location.assign(this.value)">
    {% for site in sitePicker.sites %}
        <option value="{{ site.url }}" {{ this.site.code == site.code ? 'selected' }}>{{ site.name }}</option>
    {% endfor %}
</select>

Here is the sample code to replace the alternateHrefLangElements component:

{% for site in sitePicker.sites %}
    <link rel="alternate" hreflang="{{ site.locale }}" href="{{ site.url }}" />
{% endfor %}

Events Updated

The translate.localePicker.translateQuery event has been replaced by the cms.sitePicker.overrideQuery. The arguments are the same except the site definition is passed instead of the locale code, use the hard_locale attribute of the site definition to obtain the locale.

Event::listen('cms.sitePicker.overrideQuery', function($page, $params, $currentSite, $proposedSite) {
    if ($page->baseFileName == 'your-page-filename') {
        return YourModel::translateQuery($params, $currentSite->hard_locale, $proposedSite->hard_locale);
    }
});

The translate.localePicker.translateParams event has been replaced by the cms.sitePicker.overrideParams event. The arguments are the same except the site definition is passed instead of the locale code, use the hard_locale attribute of the site definition to obtain the locale.

Event::listen('cms.sitePicker.overrideParams', function($page, $params, $currentSite, $proposedSite) {
    if ($page->baseFileName == 'your-page-filename') {
        return YourModel::overrideParams($params, $currentSite->hard_locale, $proposedSite->hard_locale);
    }
});