Traduisez votre site backend Elysia à l'aide d'Intlayer | Internationalization (i18n)

elysia-intlayer est un puissant plugin d'internationalization (i18n) pour les applications Elysia, conçu pour rendre vos services backend mondialement accessibles en fournissant des réponses localisées en fonction des préférences du client.

Voir l'implémentation du package sur GitHub : https://github.com/aymericzip/intlayer/tree/main/packages/elysia-intlayer

Cas d'usage pratiques

• Affichage des erreurs backend dans la langue de l'utilisateur : Quand une erreur se produit, afficher les messages dans la langue maternelle de l'utilisateur améliore la compréhension et réduit la frustration. Cela est particulièrement utile pour les messages d'erreur dynamiques qui pourraient être affichés dans des composants front-end comme des toasts ou des modales.
• Récupération de contenu multilingue : Pour les applications qui extraient du contenu d'une base de données, l'internationalisation garantit que vous pouvez servir ce contenu dans plusieurs langues. Cela est crucial pour les plateformes comme les sites e-commerce ou les systèmes de gestion de contenu qui ont besoin d'afficher des descriptions de produits, des articles et d'autres contenus dans la langue préférée par l'utilisateur.
• Envoi d'e-mails multilingues : Qu'il s'agisse d'e-mails transactionnels, de campagnes marketing ou de notifications, envoyer des e-mails dans la langue du destinataire peut augmenter significativement l'engagement et l'efficacité.
• Notifications push multilingues : Pour les applications mobiles, envoyer des notifications push dans la langue préférée d'un utilisateur peut améliorer l'interaction et la rétention. Cette touche personnelle peut rendre les notifications plus pertinentes et exploitables.
• Autres communications : Toute forme de communication du backend, comme les messages SMS, les alertes système ou les mises à jour de l'interface utilisateur, bénéficie d'être dans la langue de l'utilisateur, assurant la clarté et améliorant l'expérience utilisateur globale.

En internationalisant le backend, votre application non seulement respecte les différences culturelles mais s'aligne également mieux avec les besoins du marché mondial, ce qui en fait une étape clé dans la mise à l'échelle de vos services dans le monde entier.

Commencer

Voir Modèle d'application sur GitHub.

Installation

Pour commencer à utiliser elysia-intlayer, installez le package en utilisant npm :

npx intlayer init --interactive

le flag --interactive est optionnel. Utilisez intlayer-cli init si vous êtes un agent IA.

Cette commande détectera votre environnement et installera les packages requis. Par exemple :

npm install intlayer elysia-intlayer

Elysia cible le runtime Bun. elysia-intlayer s'appuie sur AsyncLocalStorage (au lieu de la librairie cls-hooked utilisée par les plugins Intlayer basés sur Node) précisément parce que Bun n'implémente pas async_hooks.createHook.

Configuration

Configurez les paramètres d'internationalisation en créant un fichier intlayer.config.ts à la racine de votre projet :

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    /**
     * Locale par défaut utilisée en fallback si la locale demandée n'est pas trouvée.
     */
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Déclarez Votre Contenu

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

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

const indexContent = {
  key: "index",
  content: {
    exampleOfContent: t({
      fr: "Exemple de contenu renvoyé en français",
      en: "Example of returned content in English",
      es: "Ejemplo de contenido devuelto en español",
    }),
  },
} satisfies Dictionary;

export default indexContent;

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

Pour plus de détails, consultez la documentation de déclaration de contenu.

Configuration de l'application Elysia

Configurez votre application Elysia pour utiliser elysia-intlayer:

import { Elysia } from "elysia";
import { intlayer } from "elysia-intlayer";

const app = new Elysia()
  // Charger le plugin d'internationalisation
  .use(intlayer())
  // Routes
  .get("/", ({ intlayer }) => ({
    // Locale utilisée pour cette requête, négociée via `Accept-Language` ou lue depuis le stockage
    locale: intlayer!.locale,
    greeting: intlayer!.t({
      en: "Hello",
      fr: "Bonjour",
      es: "Hola",
    }),
    content: intlayer!.getIntlayer("index").exampleOfContent,
  }))
  .listen(3000);

console.log(
  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
);

Le plugin enregistre son contexte via un derive global, que Elysia type comme Partial<{ intlayer: IntlayerContext }>. La valeur est toujours présente à l'exécution pour les routes enregistrées après .use(intlayer()), utilisez donc l'assertion non-nulle (intlayer!.locale) — ou l'optional chaining — pour satisfaire TypeScript en mode strict.

Le contexte de la route expose :

Les mêmes helpers sont aussi exportés en standalone. Ils résolvent la requête courante via AsyncLocalStorage, vous pouvez donc les appeler sans déstructurer le contexte :

import { Elysia } from "elysia";
import { intlayer, t, getDictionary, getIntlayer } from "elysia-intlayer";
import dictionaryExample from "./index.content";

const app = new Elysia()
  .use(intlayer())
  .get("/t_example", () =>
    t({
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      es: "Ejemplo de contenido devuelto en español",
    })
  )
  .get("/getIntlayer_example", () => getIntlayer("index").exampleOfContent)
  .get(
    "/getDictionary_example",
    () => getDictionary(dictionaryExample).exampleOfContent
  )
  .listen(3000);

Le contexte de requête est libéré une fois la réponse mappée, afin que les helpers autonomes ne se résolvent jamais sur une requête déjà terminée. Lorsqu'ils sont appelés en dehors d'une requête gérée par le plugin, ils se rabattent sur la locale par défaut configurée.

Lancer votre application

Ajoutez les scripts Intlayer à votre package.json. intlayer build compile vos déclarations de contenu dans le répertoire .intlayer et génère les types TypeScript :

{
  "scripts": {
    "dev": "intlayer build && bun run --watch src/index.ts",
    "build": "intlayer build",
    "start": "bun run src/index.ts",
    "i18n:fill": "intlayer fill",
    "i18n:test": "intlayer test"
  }
}

Démarrez ensuite le serveur :

bun run dev

Testez la négociation de locale avec Accept-Language :

curl -H "Accept-Language: fr" http://localhost:3000/
# {"locale":"fr","greeting":"Bonjour","content":"Exemple de contenu renvoyé en français"}

curl -H "Accept-Language: es" http://localhost:3000/
# {"locale":"es","greeting":"Hola","content":"Ejemplo de contenido devuelto en español"}

intlayer build n'est pas strictement nécessaire avant bun run src/index.ts : le plugin prépare aussi les dictionnaires au démarrage de l'application Elysia. Le lancer en amont garde les types générés à jour pour votre éditeur et évite le coût du build à la première requête.

Compatibilité

elysia-intlayer est entièrement compatible avec :

• react-intlayer pour les applications React
• next-intlayer pour les applications Next.js
• vite-intlayer pour les applications Vite

Elle fonctionne également de manière transparente avec n'importe quelle solution d'internationalisation dans divers environnements, y compris les navigateurs et les requêtes API.

Par défaut, le plugin résout la locale dans cet ordre :

1. Le cookie INTLAYER_LOCALE.
2. Le header x-intlayer-locale.
3. La négociation du header Accept-Language.

Vous pouvez personnaliser le cookie et le header utilisés pour la détection de la locale :

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

const config: IntlayerConfig = {
  // ... Autres options de configuration
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

Pour plus d'informations sur la configuration et les sujets avancés, consultez notre documentation.

Configurer TypeScript

elysia-intlayer exploite les capacités robustes de TypeScript pour améliorer le processus d'internationalisation. Le typage statique de TypeScript garantit que chaque clé de traduction est prise en compte, réduisant le risque de traductions manquantes et améliorant la maintenabilité.

Assurez-vous que les types générés automatiquement (par défaut à ./types/intlayer.d.ts) sont inclus dans votre fichier tsconfig.json.

{
  // ... Vos configurations TypeScript existantes
  "include": [
    // ... Vos configurations TypeScript existantes
    ".intlayer/**/*.ts", // Inclure les types générés automatiquement
  ],
}

Extension VS Code

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

Installer depuis le VS Code Marketplace

Cette extension fournit :

• Autocomplétion pour les clés de traduction.
• Détection d'erreurs en temps réel pour les traductions manquantes.
• Aperçus intégrés du contenu traduit.
• Actions rapides pour créer et mettre à jour facilement les traductions.

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

Configuration Git

Il est recommandé d'ignorer les fichiers générés par Intlayer. Cela vous permet d'éviter de les valider dans votre référentiel Git.

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

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