Skip to content
x4x4x4js2.3.29

Translation

x4js includes a translation system, called i18n (internationalisation).

The framework sometimes needs to display strings: the text of an OK button, a required-field message, the names of the months. In a multilingual system, none of this is hard-coded.

Four languages are provided: French (the default), English, Spanish and German. You can add your own translations, change the existing ones, or create new languages.

Everything goes through a read-only global variable named _tr.

import { _tr } from 'x4js';
console.log( _tr.global.ok );
console.log( _tr.global.day_long[0] );

x4js starts in French. The language is chosen like this:

import { selectLanguage } from 'x4js';
selectLanguage( "en" );

The language also gives the format of numbers, amounts and dates: formatNumber, formatMoney, formatPercent, formatDate and formatDateTime follow its locale ("fr-FR" for fr, "en-US" for en). So selectLanguage( "en" ) changes both.

import { formatMoney, formatNumber } from 'x4js';
formatNumber( 1234.5 ); // "1 234,5" in French
formatMoney( 1234.5 ); // "1 234,50 €"

To force a locale and a currency, whatever the language:

import { Application } from 'x4js';
Application.setLocale( "de-CH", "CHF" );

Application.setLocale( null ) goes back to the locale of the language. Date fields and the Calendar follow the formats of the language (date_format…), not the locale.

Declare one translation object per language, then add it.

import { _tr, addTranslation, selectLanguage } from 'x4js';
const app_fr = {
app: {
open: "Ouvrir",
close: "Fermer",
}
};
// same shape as app_fr: the compiler reports a missing text
const app_en: typeof app_fr = {
app: {
open: "Open",
close: "Close",
}
};
addTranslation( "fr", app_fr );
addTranslation( "en", app_en );
// the language is chosen after the translations are added
selectLanguage( "en" );

The tree can be as deep as needed, for example to group texts by feature.

_tr knows the texts of the framework, not yours. For the editor to suggest the texts of the application too, give it their shape:

export const tr = _tr as typeof _tr & typeof app_fr;
console.log( tr.app.open );

This is only a type hint: tr and _tr are the same object.

import { addTranslation, createLanguage } from 'x4js';
createLanguage( "it", "en" );
addTranslation( "it", { app: { open: "Apri", close: "Chiudi" } } );

The second parameter is the base language. Define the languages before any use.

A translation missing in a language is looked up in its base language, at the same path. In the example, the texts of x4js that are not translated into Italian (_tr.global.ok…) are displayed in English. So you can translate progressively.

A regional variant is a language based on another one, that only changes what differs. For example Swiss French, with its number formats:

createLanguage( "fr-ch", "fr" );
addTranslation( "fr-ch", { global: { locale: "fr-CH" } } );
import { getAvailableLanguages, getCurrentLanguage } from 'x4js';
console.log( getCurrentLanguage( ) );
console.log( getAvailableLanguages( ) );

Translations can contain arrays:

const app_fr = {
app: {
modes: [ "simple", "normal", "avancé" ],
}
};

If you write components, do not hard-code any text. You do not know which language they will be used in, and it is far simpler to plan for it from the start than to go back over all the code later.