Internationalization

Make your UI translatable into many different languages.

If you’d like to contribute translations to Elgg, see the contributors‘ guide.

The default language is en for English. Currently Elgg will always fall back to an English translation, even if the site’s language is not English; this is a known bug.

Overview

Translations are stored in PHP files in the /languages directory of your plugin. Each file corresponds to a language. The format is /languages/{language-code}.php where {language-code} is the ISO 639-1 short code for the language. For example:

<?php // mod/example/languages/en.php

return [
        'example:text' => 'Some example text',
];

To override an existing translation, include it in your plugin’s language file, and make sure your plugin is ordered later on the Admin > Plugins page:

<?php // mod/better_example/languages/en.php

return [
        'example:text' => 'Some better text!',
];

Bemerkung

Unless you are overriding core’s or another plugin’s language strings, it is good practice for the language keys to start with your plugin name. For example: yourplugin:success, yourplugin:title, etc. This helps avoid conflicts with other language keys.

Server-side API

elgg_echo($key, $args, $language)

Output the translation of the key in the current language.

Example:

echo elgg_echo('example:text');

It also supports variable replacement using sprintf syntax:

// 'welcome' => 'Welcome to %s, %s!'
echo elgg_echo('welcome', [
        elgg_get_config('sitename'),
        elgg_get_logged_in_user_entity()->name,
]);

To force which language should be used for translation, set the third parameter:

echo elgg_echo('welcome', [], $user->language);

To first test whether elgg_echo() can find a translation:

$key = 'key:that:might:not:exist';
if (!elgg_language_key_exists($key)) {
        $key = 'fallback:key';
}

echo elgg_echo($key);

Bemerkung

Some APIs allow creating translations for new keys. Translators should always include an English translation as a fallback. This makes elgg_language_key_exists($key) a reliable way to predict whether elgg_echo($key) will succeed.

Javascript API

elgg.echo(key, args)

This function is like elgg_echo in PHP.

Client-side translations are loaded asynchronously. Ensure translations are available by requiring the „elgg“ AMD module:

define(function(require) {
        var elgg = require("elgg");

        alert(elgg.echo('my_key'));
});

Translations are also available after the init, system JavaScript event.