Lingo.dev - Automated AI localization for web & mobile apps

Introduction

Lingo.dev Compiler est un outil alimenté par l'IA qui vous permet de localiser des applications basées sur React sans apporter de modifications aux composants existants. Vous configurez simplement quelques éléments, enveloppez votre application dans un fournisseur de contexte, et c'est tout — votre application est localisée.

Ce guide explique comment configurer Lingo.dev Compiler avec The Epic Stack, un framework d'application web full-stack de Kent C. Dodds qui est construit sur Remix.

Ce que vous allez apprendre

Comment initialiser Lingo.dev Compiler dans The Epic Stack
Comment configurer le compilateur pour la compatibilité avec The Epic Stack
Comment mettre en place un sélecteur de langue pour basculer entre les locales

Étape 1. Configurer une clé API

Lingo.dev Compiler utilise des modèles de langage avancés (LLMs) pour localiser les applications avec l'IA. Pour utiliser l'un de ces modèles, vous avez besoin d'une clé API d'un fournisseur pris en charge.

Pour démarrer le plus rapidement possible, nous recommandons d'utiliser Lingo.dev Engine — notre propre plateforme hébergée qui offre 10 000 tokens d'utilisation mensuelle gratuite.

Pour configurer une clé API :

Connectez-vous à Lingo.dev Engine.
Naviguez vers la page Projects.
Cliquez sur API key > Copy.
Stockez la clé API dans une variable d'environnement :
```
export LINGODOTDEV_API_KEY="<your_api_key>"
```

Alternative : Fournisseurs LLM personnalisés

Vous n'êtes pas obligé d'utiliser Lingo.dev Engine. Vous pouvez configurer le compilateur pour l'intégrer avec plusieurs fournisseurs LLM personnalisés, notamment :

Groq
Google
Mistral
Ollama
OpenRouter

Étape 2. Installer le package

Lingo.dev Compiler est distribué dans le cadre du package npm lingo.dev. Pour l'installer, utilisez votre gestionnaire de packages préféré :

npm install lingo.dev

Étape 3. Initialiser le compilateur

Le Compilateur Lingo.dev s'intègre avec Vite et s'exécute au moment de la compilation. Pour s'intégrer au processus de build de Vite, effectuez les modifications suivantes dans le fichier vite.config.ts :

Importez le compilateur :

import lingoCompiler from "lingo.dev/compiler";

Initialisez le compilateur avec la méthode vite :
```
const withLingo = lingoCompiler.vite({
  sourceRoot: "app",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});
```
Pour la compatibilité avec The Epic Stack, assurez-vous que :
- sourceRoot est défini sur "app"
- rsc est défini sur false
Pour en savoir plus sur les options disponibles, consultez Options du compilateur.

Fusionnez la configuration du compilateur avec la configuration existante et exportez-la :

export default defineConfig((config) => {
  const configWithSentry = {
    ...viteConfig,
    plugins: [
      ...viteConfig.plugins!.filter(Boolean),
      MODE === "production" && process.env.SENTRY_AUTH_TOKEN
        ? sentryReactRouter(sentryConfig, config)
        : null,
    ].filter(Boolean),
  };

  return withLingo(configWithSentry);
});

Avec cette configuration en place, le Compilateur Lingo.dev va :

Parcourir l'arbre de syntaxe abstraite (AST) du code source
Trouver le contenu localisable (c'est-à-dire le texte dans les éléments JSX et certaines valeurs d'attributs)
Utiliser le(s) modèle(s) d'IA configuré(s) pour générer des traductions
Stocker le contenu original et traduit dans un fichier dictionary.js
Remplacer le contenu localisé par des placeholders

Étape 4. Charger le contenu localisé

Après que le compilateur a traité votre application et généré des traductions, vous devez charger et servir ce contenu localisé à vos utilisateurs. Cela implique :

Charger le dictionnaire approprié en fonction des préférences de langue de l'utilisateur
Fournir les traductions chargées à votre application via un fournisseur de contexte

Chargement du dictionnaire

Dans le fichier app/root.tsx :

Importez la fonction loadDictionary depuis lingo.dev/react/react-router :
```
import { loadDictionary } from "lingo.dev/react/react-router";
```
Cette fonction :
- Récupère la locale actuelle depuis le cookie lingo-locale
- Utilise "en" comme valeur par défaut lorsqu'une locale n'est pas définie
- Charge le contenu localisé depuis le fichier dictionary.js

Appelez la fonction loadDictionary depuis la fonction loader :

const lingoDictionary = await loadDictionary(request);

Retournez le dictionnaire comme partie des données du loader :

return data(
  {
    user,
    requestInfo: {
      hints: getHints(request),
      origin: getDomainUrl(request),
      path: new URL(request.url).pathname,
      userPrefs: {
        theme: getTheme(request),
      },
    },
    ENV: getEnv(),
    toast,
    honeyProps,
    lingoDictionary,
  },
  {
    headers: combineHeaders(
      { "Server-Timing": timings.toString() },
      toastHeaders,
    ),
  },
);

Fourniture des traductions

Dans le fichier app/root.tsx :

Importez le composant LingoProvider depuis lingo.dev/react/client :
```
import { LingoProvider } from "lingo.dev/react/client";
```
Ce composant est un fournisseur de contexte React qui remplace les placeholders créés par le compilateur par le contenu localisé.
Dans le composant Layout, récupérez les données du chargeur de données :
```
const data = useLoaderData<typeof loader | null>();
```

Encapsulez l'application dans le composant LingoProvider :

<LingoProvider>{/* Code existant de l'application */}</LingoProvider>

Transmettez le dictionnaire chargé au composant :

<LingoProvider dictionary={data?.lingoDictionary}>
  {/* Code existant de l'application */}
</LingoProvider>

Étape 5. Configurer un sélecteur de locale

Pour permettre aux utilisateurs de basculer entre les locales, importez le LocaleSwitcher depuis le package lingo.dev. Il s'agit d'un composant non stylisé qui :

Affiche un menu déroulant des locales disponibles
Permet aux utilisateurs de sélectionner une locale
Mémorise la locale sélectionnée pour les visites ultérieures

Pour utiliser ce composant, intégrez-le n'importe où dans votre application et définissez la prop locales comme un tableau contenant les locales source et cibles configurées :

import { LocaleSwitcher } from "lingo.dev/react/client";

<LocaleSwitcher locales={["en", "es"]} />;

Alternative : Sélecteur de langue personnalisé

Vous n'êtes pas obligé d'utiliser le composant LocaleSwitcher. Vous pouvez implémenter une logique et une interface utilisateur personnalisées pour changer de langue. La seule exigence est de lire et d'écrire la langue active dans le cookie lingo-locale.

Étape 6. Exécuter l'application

Pour vérifier que le Compilateur Lingo.dev a été correctement configuré :

Démarrez le serveur de développement :
```
npm run dev
```
Accédez à localhost:3000.
Utilisez le composant LocaleSwitcher pour basculer entre les langues.

La page devrait se recharger et afficher le contenu localisé.

Alternative : Définir les cookies manuellement

Si vous n'utilisez pas le composant LocaleSwitcher, une autre façon de vérifier que la localisation fonctionne consiste à définir manuellement le cookie lingo-locale.

Si vous utilisez Google Chrome, suivez ces instructions :

Accédez à Affichage > Développeur > Outils de développement.
Allez dans l'onglet Application.
Dans la barre latérale gauche, sous Stockage, développez Cookies et sélectionnez l'URL du site.
Dans le tableau des cookies, faites un clic droit n'importe où et sélectionnez Ajouter.
Dans la colonne Nom, saisissez lingo-locale.
Dans la colonne Valeur, saisissez la langue souhaitée (par exemple, es).
Appuyez sur Entrée pour enregistrer le cookie.
Actualisez la page pour appliquer le cookie.

Lectures complémentaires

Pour comprendre comment fonctionne le compilateur, consultez Comment ça marche.
Pour apprendre à configurer le compilateur, consultez Options du compilateur.

Démarrage rapide pour The Epic Stack