Traduction

i18n

x4js intègre un système de traduction, appelé i18n (internationalisation).

Le framework a parfois besoin d’afficher des chaînes de caractères : le texte d’un bouton OK, un message de champ obligatoire, le nom des mois. Dans un système multilingue, rien de tout cela n’est écrit en dur.

Deux langues sont fournies, le français et l’anglais. Vous pouvez ajouter vos propres traductions, modifier celles qui existent, ou créer de nouvelles langues.

Lire une traduction

Tout passe par une variable globale en lecture seule, nommée _tr.

import { _tr } from 'x4js';

console.log( _tr.global.ok );
console.log( _tr.global.day_long[0] );

Choisir la langue

x4js démarre en français. La langue se choisit ainsi :

import { selectLanguage } from 'x4js';

selectLanguage( "en" );

Attention

Choisissez la langue avant de construire le moindre composant : un composant lit ses textes au moment où il est créé.

Ajouter vos propres traductions

Déclarez un objet de traductions par langue, puis ajoutez-le.

import { _tr, addTranslation, selectLanguage } from 'x4js';

const app_fr = {
  app: {
    open: "Ouvrir",
    close: "Fermer",
  }
};

// même forme que app_fr : le compilateur signale un texte oublié
const app_en: typeof app_fr = {
  app: {
    open: "Open",
    close: "Close",
  }
};

addTranslation( "fr", app_fr );
addTranslation( "en", app_en );

// la langue se choisit après avoir ajouté les traductions
selectLanguage( "en" );

L’arborescence peut être aussi profonde que nécessaire, par exemple pour ranger les textes par fonctionnalité.

Garder l’aide à la saisie

_tr connaît les textes du framework, pas les vôtres. Pour que l’éditeur propose aussi les textes de l’application, donnez-lui leur forme :

export const tr = _tr as typeof _tr & typeof app_fr;

console.log( tr.app.open );

C’est une simple indication de type : tr et _tr sont le même objet.

Ajouter une langue

import { createLanguage } from 'x4js';

createLanguage( "de", "en" );

Le second paramètre est la langue de base. Définissez les langues avant toute utilisation.

Repli

Une traduction absente dans une langue est cherchée dans sa langue de base. Dans l’exemple, un texte qui n’existe pas en allemand s’affiche en anglais. On peut donc traduire progressivement.

Inspection

import { getAvailableLanguages, getCurrentLanguage } from 'x4js';

console.log( getCurrentLanguage( ) );
console.log( getAvailableLanguages( ) );

Éléments complexes

Les traductions peuvent contenir des tableaux :

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

La règle

Si vous développez des composants, n’écrivez aucun texte en dur. Vous ne savez pas dans quelle langue ils seront utilisés, et il est bien plus simple de le prévoir dès le début que de reprendre tout le code ensuite.