Bonjour

Voici un exemple.

Cette phrase n'est pas disponible en anglais.

Il y a un singe sur l'arbre.
Il y a 12 singes sur l'arbre.

Langage actuelle : fr
Toutes les langues dispo. : fr, en

# Sommaire

Installation
- NPM
- Yarn
- CDN
Utilisation
Méthodes
Options par défaut

# Installation

npm

npm i si18n.js

Yarn

yarn add si18n.js

CDN ES6 Modules

Vous pouvez aussi utiliser si18n.js à partir d'un CDN. Il existe différentes versions de liens disponibles pour différentes plateformes CDN. Vous pouvez choisir et utiliser un seul lien à la fois.

<!-- si18n.js latest version @1.4.4 -->
<script type="module" src="https://si18n.js.bruxelles.dev/si18n.js"></script>
<script type="module" src="https://si18n.js.bruxelles.dev/si18n.min.js"></script>

<!-- UNPKG -->
<script type="module" src="https://unpkg.com/si18n.js"></script>
<script type="module" src="https://unpkg.com/si18n.js@1.4.4/si18n.js"></script>
<script type="module" src="https://unpkg.com/si18n.js@1.4.4/si18n.min.js"></script>

<!-- jsDelivr -->
<script type="module" src="https://cdn.jsdelivr.net/npm/si18n.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/si18n.js@1.4.4"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/si18n.js@1.4.4/si18n.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/si18n.js@1.4.4/si18n.min.js"></script>

<!-- ESM -->
<!-- (?target=es2015|es2022|esnext) -->
<script type="module" src="https://esm.sh/si18n.js@1.4.4"></script>

<script type="module" src="https://cdn.jsdelivr.net/npm/si18n.js@1.4.4/+esm"></script>

<!-- UNPKG -->
<script type="module">
  import Si18n from "https://cdn.jsdelivr.net/npm/si18n.js@1.4.4/si18n.min.js";
  // ...
</script>

# Utilisation

NPM

import Si18n from "si18n";

Exemple de base

let loc = new Si18n();
loc.init({
  locales: {}, // { "en": {...}, "fr": {...}}
  lang: "fr",
  fallbackLang: "en",
  translate() {
    document.querySelector(".lang").innerText = loc.getLocale();
    document.querySelector(".title").innerText = loc.t("nested.title");
    // ...
  },
  onLocaleChanged() {
    // ...
  }
});

Détection automatique

Ceci permet à si18n.js de détecter et de mettre à jour automatiquement le texte de l'élément :

<div data-si18n="site.title"></div>

Pas pour le contenu des balises

Lorsqu'il y a l'attribut data-si18n-default et que c'est défini à false, le texte ne sera pas défini comme contenu de la balise. Vous devez utiliser cette option uniquement pour le contenu des attributs, sans oublier de mention de quel(s) attribut(s) il s'agit.

<div data-si18n="site.title" data-si18n-default="false" data-si18n-title="true"></div>

Tous les attributs sont :

Les attributs suivants sont des booléens. Ils sont obligatoires selon les besoins. Les valeurs possibles sont true ou false.

data-si18n-default : si défini sur false, le texte ne sera pas placé dans la balise. (Réservé pour les attributs.)
data-si18n-html : si défini sur true, le texte sera ajouté sous forme de code HTML. Défaut : false.
data-si18n-value pour l'attribut value d'une balise comme option et input.
data-si18n-alt pour l'attribut alt de la balise img pour fournir une description textuelle de l'image.
data-si18n-title pour l'attribut title de la balise.
data-si18n-label pour l'attribut label d'une balise comme optgroup.
data-si18n-aria-label pour l'attribut aria-label de la balise.
data-si18n-placeholder pour l'attribut placeholder des balises input et textarea.
data-si18n-content pour l'attribut content d'une balise comme meta pour la description du site, par exemple (utile si vous utilisez la technologie Prerendering.

Les attributs lang et dir de la balise html sont définis automatiquement. La seule chose que vous pouvez faire pour l'attribut dir, c'est de le définir manuellement pour toutes les langues ou seulement pour les langues en rtl (string). Par défaut : ltr. Exemple : "rtl": true.

Remplacement des valeurs

En plus de faire des simples remplacements de textes, si18n.js peut aussi insérer des valeurs dans des espaces réservés à ce but. Il suffit de définir une clé-valeur dans l'argument valeurs (deuxième argument) de la méthode t. Et dans vos textes, il suffira de réserver les espaces par un %{X} où X est la clé (numéro ou nom de propriété) de la valeur à insérer. Exemple :

<!-- 1. HTML -->
<p id="intro"></p>

// 2. JAVASCRIPT
// 2.1.
let data = {
  "fr": {
    "intro": "%{name} a eu %{age} ans cette année.",
    "test": "Ceci est un test."
  },
  "en": {
    "intro": "%{name} turned %{age} this year.",
    "test": "This is a test."
  }
};

loc.init({
  // ...
  translate() {
    document.querySelector("#intro").innerText = loc.t("intro", {
      age: (new Date().getFullYear()) - birthYear,
      name: "John Doe"
    });

    console.log(loc.t("test")) // "Ceci est un test."
    // ...
  }
});

// 2.2.
let data = {
  "fr": { "intro": "Mon ami s'appelle %{0} et travaille chez %{1}." },
  "en": { "intro": "My friend's name is %{0} and he works at %{1}." }
};

loc.init({
  // ...
  translate() {
    document.querySelector("#intro").innerText = loc.t("intro", {
      0: "Georges",
      1: "CRFEV"
    });
    // ...
  }
});

# Méthodes (7)

Méthode	Argument	Description
`constructor`	`options`:`object`	Fait la même chose que la méthode `init` suivante.
`init`	`options`:`object`	`Recommandé` - Initialise l'objet si18n avec les options données.
`setLocale`	`lang`:`string`	Définit la langue donnée et applique le changement en appelant la méthode d'option `translate`. N'utilisez pas cette méthode si vous avez configuré l'option `togglersSelector`.
`getLocale`	`void`	Renvoie le code de la langue actuelle (ex : 'en').
`getLocales`	`void`	Renvoie la liste de toutes les langues disponibles (ex : `['fr', 'en', 'it']`).
`t`	`JSONPath`:`string`, `valeurs`:`object`	Renvoie la chaîne de traduction à la clé donnée (ex : `heroTitle`, `site.title`, `site.menu.link1`). L'argument `valeurs` est facultatif. S'il est fourni, il doit contenir les clés-valeurs à remplacer. Voir l'exemple ci-dessous.
`static async getJSON`	`URL`: `string`, `callback(res: object)`: `fn`	Récupère et renvoie au format JSON dans le paramètre de la fonction callback les données de l'URL fournie.
`toJSON`	`void`	Renvoie les options de l'instance.

# Options par défaut (11)

Argument	Valeur par défaut	Description
`locales`	`{}`	Objet contenant vos traductions des langues. Obligatoire seulement si `path` n'est pas définie.
`path`	`null`	Chemin d'accès absolu vers le dossier contenant vos fichiers de traduction. Les fichiers vont être chargés automatiquement selon la langue active (la langue de secours sera toujours chargé). Prioritaire sur l'option `locales`. Obligatoire seulement si `locales` n'est pas définie. Ex : `./locales`.
`availableLocales`	`[]`	Liste contenant les noms des langues disponibles tel que défini dans les fichiers de traduction. Obligatoire seulement si `path` est définie.
`lang`	`''`	Langue active à utiliser. Ne l'utilisez pas si vous souhaitez laisser le détecteur de langue du navigateur fournir la langue. Si cette option n'est pas définie, l'option `fallbackLang` devient obligatoire.
`fallbackLang`	`''`	Langue de secours. La langue à utiliser lorsque la langue demandée ou une chaîne demandée dans une langue non entièrement traduite est manquante. Si elle n'est pas défini, la langue de secours sera la langue actuelle.
`activeClass`	`''`	Classe à ajouter au bouton actif pour la langue actuelle. À utiliser seulement si `togglersSelector` est utilisé.
`togglersSelector`	`''`	Sélecteur CSS pour les éléments basculeurs. si18n.js ajoutera un événement click aux éléments sélectionnés. Ne pas définir si vous utilisez la méthode `setLocale(lang)`. Ces éléments doivent obligatoirement avoir l'attribut `data-lang="XX"` où XX correspond au code de la langue du bouton (élément basculeur) pour être détectés.
`isTogglerSelect`	`false`	Si le basculeur est un élément `select` ou `button` (autre).
`saveLang`	`true`	S'il faut enregistrer la langue dans le localStorage.
`saveAs`	`'lang'`	Nom de la clé pour enregistrer la langue dans le localStorage. Si elle est définie, la valeur sera utilisée comme clé pour récupérer la langue à partir du paramètre URL (Défaut : `lang`).
`reloadPage`	`false`	Si cette option est définie à `true`, la page sera automatiquement actualisée après avoir changé la langue. Elle peut être utile seulement si vous avez une structure de page complexe et que vous souhaitez que les traductions soient chargées à chaque changement de langue, pour faire simple.
`translate`	`function() {}`	(obligatoire) - Fonction qui traduit le texte manuellement. Réservé uniquement à la traduction. Note: La balise `html` a automatiquement un attribut `lang` avec la langue actuelle, pas besoin de la coder manuellement.
`onLocaleChanged`	`function() {}`	Fonction de rappel déclenchée lorsque la langue change. Tout ce que vous voulez faire d'autre parce que la langue a changé, faites-le ici.