Traduisez votre site web Vite et Lit en utilisant Intlayer | Internationalisation (i18n)

Table des matières

Qu'est-ce qu'Intlayer ?

Intlayer est une bibliothèque d'internationalisation (i18n) innovante et open-source conçue pour simplifier le support multilingue dans les applications web modernes.

Avec Intlayer, vous pouvez :

• Gérer facilement les traductions en utilisant des dictionnaires déclaratifs au niveau des composants.
• Localiser dynamiquement les métadonnées, les routes et le contenu.
• Assurer le support TypeScript avec des types autogénérés, améliorant l'autocomplétion et la détection d'erreurs.
• Bénéficier de fonctionnalités avancées, comme la détection et le changement dynamique de langue.

Guide étape par étape pour configurer Intlayer dans une application Vite et Lit

Étape 1 : Installer les dépendances

Installez les paquets nécessaires en utilisant npm :

npm install intlayer lit-intlayernpm install vite-intlayer --save-devnpx intlayer init

• intlayer

  Le paquet principal qui fournit des outils d'internationalisation pour la gestion de la configuration, la traduction, la déclaration de contenu, la transpilation et les commandes CLI.

• lit-intlayer Le paquet qui intègre Intlayer aux applications Lit. Il fournit des hooks basés sur ReactiveController (useIntlayer, useLocale, etc.) pour que les LitElements se re-rendent automatiquement lorsque la langue change.

• vite-intlayer Comprend le plugin Vite pour intégrer Intlayer avec le bundler Vite, ainsi qu'un middleware pour détecter la langue préférée de l'utilisateur, gérer les cookies et gérer la redirection d'URL.

Étape 2 : Configuration de votre projet

Créez un fichier de configuration pour configurer les langues de votre application :

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Vos autres langues
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Via ce fichier de configuration, vous pouvez configurer les URL localisées, la redirection du middleware, les noms des cookies, l'emplacement et l'extension de vos déclarations de contenu, désactiver les logs Intlayer dans la console, et plus encore. Pour une liste complète des paramètres disponibles, reportez-vous à la documentation de configuration.

Étape 3 : Intégrer Intlayer dans votre configuration Vite

Ajoutez le plugin intlayer dans votre configuration.

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [intlayer()],
});

Le plugin Vite intlayer() est utilisé pour intégrer Intlayer avec Vite. Il assure la construction des fichiers de déclaration de contenu et les surveille en mode développement. Il définit les variables d'environnement Intlayer dans l'application Vite. De plus, il fournit des alias pour optimiser les performances.

Étape 4 : Initialiser Intlayer dans votre point d'entrée

Appelez installIntlayer() avant que les éléments personnalisés ne soient enregistrés pour que le singleton global de langue soit prêt lorsque le premier élément se connecte.

import { installIntlayer } from "lit-intlayer";// Doit être appelé avant qu'un LitElement ne soit connecté au DOM.installIntlayer();// Importez et enregistrez vos éléments personnalisés.import "./my-element.js";

Si vous utilisez également des déclarations de contenu md() (Markdown), installez également le moteur de rendu markdown :

import { installIntlayer, installIntlayerMarkdown } from "lit-intlayer";installIntlayer();installIntlayerMarkdown();import "./my-element.js";

Étape 5 : Déclarer votre contenu

Créez et gérez vos déclarations de contenu pour stocker les traductions :

import { t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: "Vite + Lit",

    viteLogo: t({
      en: "Vite logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),
    litLogo: t({
      en: "Lit logo",
      fr: "Logo Lit",
      es: "Logo Lit",
    }),

    count: t({
      en: "count is {{count}}",
      fr: "le compte est {{count}}",
      es: "el recuento es {{count}}",
    }),

    readTheDocs: t({
      en: "Click on the Vite and Lit logos to learn more",
      fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
      es: "Haga clic en los logotipos de Vite y Lit para obtener más información",
    }),
  },
} satisfies Dictionary;

export default appContent;

Vos déclarations de contenu peuvent être définies n'importe où dans votre application dès qu'elles sont incluses dans le répertoire contentDir (par défaut, ./src) et correspondent à l'extension du fichier de déclaration de contenu (par défaut, .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Pour plus de détails, reportez-vous à la documentation sur la déclaration de contenu.

Étape 6 : Utiliser Intlayer dans votre LitElement

Utilisez useIntlayer à l'intérieur d'un LitElement. Il renvoie un proxy ReactiveController qui déclenche automatiquement des re-rendus dès que la langue active change - aucune configuration supplémentaire n'est requise.

import { LitElement, html } from "lit";import { customElement, property } from "lit/decorators.js";import { useIntlayer } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  @property({ type: Number })  count = 0;  // useIntlayer s'enregistre en tant que ReactiveController.  // L'élément se re-rend automatiquement lorsque la langue change.  private content = useIntlayer(this, "app");  override render() {    const { content } = this;    return html`      <h1>${content.title}</h1>      <img src="/vite.svg" alt=${content.viteLogo.value} />      <img src="/lit.svg" alt=${content.litLogo.value} />      <button @click=${() => this.count++}>        ${content.count({ count: this.count })}      </button>      <p>${content.readTheDocs}</p>    `;  }}

Lorsque vous avez besoin de la chaîne traduite dans un attribut HTML natif (ex: alt, aria-label, title), appelez .value sur le nœud terminal :

typescript

Copier le contenu

Copier le code

Copier le code dans le presse-papiers

html`<img alt=${content.viteLogo.value} />`;html`<img alt=${content.viteLogo.toString()} />`;html`<img alt=${String(content.viteLogo)} />`;

(Optionnel) Étape 7 : Changer la langue de votre contenu

Pour changer la langue de votre contenu, utilisez la méthode setLocale exposée par le contrôleur useLocale.

import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

(Optionnel) Étape 8 : Rendre du contenu Markdown et HTML

Intlayer prend en charge les déclarations de contenu md() et html(). Dans Lit, le résultat compilé est injecté en tant que HTML brut via la directive unsafeHTML.

Rendez le HTML compilé dans votre élément :

import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { unsafeHTML } from "lit/directives/unsafe-html.js";import { useIntlayer } from "lit-intlayer";import { compileMarkdown } from "lit-intlayer/markdown";@customElement("my-element")export class MyElement extends LitElement {  private content = useIntlayer(this, "app");  override render() {    return html`      <div class="edit-note">        ${unsafeHTML(compileMarkdown(String(this.content.editNote)))}      </div>    `;  }}

TIP

String(content.editNote) appelle toString() sur l'IntlayerNode, qui renvoie la chaîne Markdown brute. Passez-la à compileMarkdown pour obtenir une chaîne HTML, puis rendez-la avec la directive unsafeHTML de Lit.

(Optionnel) Étape 9 : Ajouter le routage localisé à votre application

Pour créer des routes uniques pour chaque langue (utile pour le SEO), vous pouvez utiliser un routeur côté client aux côtés des helpers localeMap / localeFlatMap d'Intlayer, et le plugin Vite intlayerProxy pour la détection de la langue côté serveur.

Tout d'abord, ajoutez intlayerProxy à votre configuration Vite :

Notez que pour utiliser intlayerProxy en production, vous devez déplacer vite-intlayer de devDependencies vers dependencies.

import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayerProxy(), // should be placed first
    intlayer(),
  ],
});

(Optionnel) Étape 10 : Changer l'URL lorsque la langue change

Pour mettre à jour l'URL du navigateur lorsque la langue change, utilisez useRewriteURL aux côtés du sélecteur de langue :

import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale, useRewriteURL } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  // Réécrit automatiquement l'URL actuelle lorsque la langue change.  private _rewriteURL = useRewriteURL(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

(Optionnel) Étape 11 : Changer les attributs de langue et de direction HTML

Mettez à jour les attributs lang et dir de la balise <html> pour qu'ils correspondent à la langue actuelle pour l'accessibilité et le SEO.

import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getHTMLTextDir } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  private locale = useLocale(this, {    onLocaleChange: (loc) => {      document.documentElement.lang = loc;      document.documentElement.dir = getHTMLTextDir(loc);    },  });  override render() {    return html`<!-- votre contenu -->`;  }}

(Optionnel) Étape 12 : Extraire le contenu de vos composants

Si vous avez une base de code existante, transformer des milliers de fichiers peut prendre du temps.

Pour faciliter ce processus, Intlayer propose un compilateur / extracteur pour transformer vos composants et extraire le contenu.

Pour le configurer, vous pouvez ajouter une section compiler dans votre fichier intlayer.config.ts :

import { type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... Reste de votre config  compiler: {    /**     * Indique si le compilateur doit être activé.     */    enabled: true,    /**     * Définit le chemin des fichiers de sortie     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Indique si les composants doivent être sauvegardés après avoir été transformés.     * De cette façon, le compilateur peut être exécuté une seule fois pour transformer l'application, puis il peut être supprimé.     */    saveComponents: false,    /**     * Préfixe de clé de dictionnaire     */    dictionaryKeyPrefix: "",  },};export default config;

(Facultatif) Sitemap et robots.txt (génération au build)

Intlayer fournit des utilitaires - generateSitemap et getMultilingualUrls - pour produire un sitemap.xml multilingue et un robots.txt prêts pour les crawlers, que vous pouvez écrire automatiquement dans public/. En pratique, exécutez un petit script Node avant Vite (par exemple les hooks npm predev / prebuild) afin que ces fichiers soient présents au build ou au serveur de développement.

Sitemap

Le générateur de sitemap Intlayer tient compte de vos locales et ajoute les métadonnées attendues par les moteurs.

Le sitemap généré prend en charge l’espace de noms xhtml:link (extensions hreflang). Contrairement aux générateurs qui ne listent que des URL brutes, Intlayer relie de façon bidirectionnelle toutes les versions linguistiques d’une même page (par ex. /about, /fr/about ou /about?lang=fr selon votre mode de routage), ce qui aide les crawlers.

Robots.txt

Utilisez getMultilingualUrls pour que les règles Disallow couvrent toutes les variantes localisées des chemins sensibles.

1. Créer generate-seo.mjs à la racine du projet

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

Le paquet intlayer doit être installé pour que le script puisse l’importer. Définissez SITE_URL dans l’environnement pour la production (par ex. en CI).

Préférez generate-seo.mjs pour l’ESM Node. Avec generate-seo.js, assurez-vous que "type": "module" est présent dans package.json, ou activez l’ESM côté Node.

2. Lancer le script avant Vite

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

Adaptez les commandes si vous utilisez pnpm ou yarn. Vous pouvez aussi appeler ce script depuis la CI ou une autre étape de votre pipeline.

Configurer TypeScript

Assurez-vous que votre configuration TypeScript inclut les types autogénérés.

{  "compilerOptions": {    // ...    "experimentalDecorators": true,    "useDefineForClassFields": false,  },  "include": ["src", ".intlayer/**/*.ts"],}

experimentalDecorators et useDefineForClassFields: false sont requis par Lit pour le support des décorateurs.

Configuration Git

Il est recommandé d'ignorer les fichiers générés par Intlayer. Cela vous permet d'éviter de les commettre dans votre dépôt Git.

Pour ce faire, vous pouvez ajouter les instructions suivantes à votre fichier .gitignore :

# Ignorez les fichiers générés par Intlayer.intlayer

Extension VS Code

Pour améliorer votre expérience de développement avec Intlayer, vous pouvez installer l'extension officielle Intlayer VS Code.

Installer depuis le VS Code Marketplace

Cette extension fournit :

• L'autocomplétion pour les clés de traduction.
• La détection d'erreurs en temps réel pour les traductions manquantes.
• Des aperçus en ligne du contenu traduit.
• Des actions rapides pour créer et mettre à jour facilement les traductions.

Pour plus de détails sur l'utilisation de l'extension, reportez-vous à la documentation de l'extension Intlayer VS Code.

Aller plus loin

Pour aller plus loin, vous pouvez implémenter l'éditeur visuel ou externaliser votre contenu en utilisant le CMS.