Guide de migration

Alpha

Le Compiler de Lingo.dev est en alpha. Il est instable, n’est pas recommandé en production, et les API peuvent évoluer d’une version à l’autre.

Ce guide couvre la migration de l’ancien package Compiler lingo.dev vers le package actuel @lingo.dev/compiler. Le nouveau package introduit un nom npm scindé, une API simplifiée, une intégration Vite via plugin et un nouveau répertoire .lingo/ pour les métadonnées.

Résumé des changements#

Élément	Avant (`lingo.dev`)	Après (`@lingo.dev/compiler`)
Nom du package	`lingo.dev`	`@lingo.dev/compiler`
Intégration Next.js	Modification directe de la configuration	Wrapper asynchrone `withLingo()`
Intégration Vite	Configuration manuelle	`lingoCompilerPlugin`
LingoProvider	Prop `loadDictionary` requise	Aucune prop requise
Répertoire de métadonnées	`lingo/`	`.lingo/`
Directive d’activation	`'use i18n'` requis	Facultatif (par défaut : tout traduire)
Imports	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Migration étape par étape#

Remplacer le package

Supprimez l’ancien package et installez le nouveau :

bash

npm uninstall lingo.dev
npm install @lingo.dev/compiler

Mettre à jour les imports

Remplacez tous les chemins d’import :

// Before
import { LingoProvider, useLingoContext } from "lingo.dev/react";

// After
import { LingoProvider, useLingoContext } from "@lingo.dev/compiler/react";

Mettre à jour la configuration Next.js (si nécessaire)

La configuration Next.js doit désormais être une fonction asynchrone :

// Before
import { withLingo } from "lingo.dev/next";
const nextConfig = {};
export default withLingo(nextConfig, { /* options */ });

// After
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr"],
    models: "lingo.dev",
  });
}

Le wrapper de fonction asynchrone est obligatoire. Un export synchrone fera échouer le build. Consultez Intégration Next.js pour en savoir plus.

Mettre à jour la configuration Vite (si nécessaire)

Remplacez toute configuration manuelle par lingoCompilerPlugin :

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr"],
      models: "lingo.dev",
    }),
    react(), // Must come AFTER lingoCompilerPlugin
  ],
});

Simplifier LingoProvider

La prop loadDictionary n’est plus nécessaire. Le Compiler gère automatiquement le chargement des dictionnaires :

tsx

// Before
import { LingoProvider } from "lingo.dev/react";

<LingoProvider loadDictionary={loadDictionary}>
  <App />
</LingoProvider>

// After
import { LingoProvider } from "@lingo.dev/compiler/react";

<LingoProvider>
  <App />
</LingoProvider>

Déplacer le répertoire de métadonnées

Renommez le répertoire de métadonnées de lingo/ en .lingo/ :

bash

mv lingo/ .lingo/

Mettez à jour votre .gitignore s’il fait référence à l’ancien nom de répertoire. Le répertoire .lingo/ doit être versionné.

Mettre à jour les directives 'use i18n' (facultatif)

Dans le nouveau package, 'use i18n' est facultatif. Par défaut, tous les fichiers de sourceRoot sont traduits. Si vous souhaitez conserver un comportement en opt-in, définissez useDirective: true dans votre configuration :

{
  useDirective: true, // Keep requiring 'use i18n' in each file
}

Si vous supprimez useDirective (ou le définissez sur false), vous pouvez aussi supprimer les directives 'use i18n' de vos fichiers : tous les fichiers de sourceRoot seront traduits automatiquement.

Recompiler et vérifier

Lancez le serveur de développement et vérifiez que les traductions s’affichent :

bash

npm run dev

Vérifiez que :

Le pseudotraducteur produit des marqueurs [!!! ... !!!] (si activé)
Toutes les chaînes déjà traduites fonctionnent toujours
Le fichier .lingo/metadata.json est créé ou mis à jour

Étapes suivantes#

Configuration

Guide complet de configuration

Référence de configuration

Toutes les nouvelles options de configuration

Intégration Next.js

Détails de migration spécifiques à Next.js

Vite + React

Détails de migration spécifiques à Vite

Cette page vous a-t-elle été utile ?

Guide de migration

Alpha

Le Compiler de Lingo.dev est en alpha. Il est instable, n’est pas recommandé en production, et les API peuvent évoluer d’une version à l’autre.

Résumé des changements#

Élément	Avant (`lingo.dev`)	Après (`@lingo.dev/compiler`)
Nom du package	`lingo.dev`	`@lingo.dev/compiler`
Intégration Next.js	Modification directe de la configuration	Wrapper asynchrone `withLingo()`
Intégration Vite	Configuration manuelle	`lingoCompilerPlugin`
LingoProvider	Prop `loadDictionary` requise	Aucune prop requise
Répertoire de métadonnées	`lingo/`	`.lingo/`
Directive d’activation	`'use i18n'` requis	Facultatif (par défaut : tout traduire)
Imports	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Migration étape par étape#

Remplacer le package

Supprimez l’ancien package et installez le nouveau :

bash

npm uninstall lingo.dev
npm install @lingo.dev/compiler

Mettre à jour les imports

Remplacez tous les chemins d’import :

// Before
import { LingoProvider, useLingoContext } from "lingo.dev/react";

// After
import { LingoProvider, useLingoContext } from "@lingo.dev/compiler/react";

Mettre à jour la configuration Next.js (si nécessaire)

La configuration Next.js doit désormais être une fonction asynchrone :

// Before
import { withLingo } from "lingo.dev/next";
const nextConfig = {};
export default withLingo(nextConfig, { /* options */ });

// After
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr"],
    models: "lingo.dev",
  });
}

Le wrapper de fonction asynchrone est obligatoire. Un export synchrone fera échouer le build. Consultez Intégration Next.js pour en savoir plus.

Mettre à jour la configuration Vite (si nécessaire)

Remplacez toute configuration manuelle par lingoCompilerPlugin :

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr"],
      models: "lingo.dev",
    }),
    react(), // Must come AFTER lingoCompilerPlugin
  ],
});

Simplifier LingoProvider

La prop loadDictionary n’est plus nécessaire. Le Compiler gère automatiquement le chargement des dictionnaires :

tsx

// Before
import { LingoProvider } from "lingo.dev/react";

<LingoProvider loadDictionary={loadDictionary}>
  <App />
</LingoProvider>

// After
import { LingoProvider } from "@lingo.dev/compiler/react";

<LingoProvider>
  <App />
</LingoProvider>

Déplacer le répertoire de métadonnées

Renommez le répertoire de métadonnées de lingo/ en .lingo/ :

bash

mv lingo/ .lingo/

Mettez à jour votre .gitignore s’il fait référence à l’ancien nom de répertoire. Le répertoire .lingo/ doit être versionné.

Mettre à jour les directives 'use i18n' (facultatif)

{
  useDirective: true, // Keep requiring 'use i18n' in each file
}

Recompiler et vérifier

Lancez le serveur de développement et vérifiez que les traductions s’affichent :

bash

npm run dev

Vérifiez que :

Le pseudotraducteur produit des marqueurs [!!! ... !!!] (si activé)
Toutes les chaînes déjà traduites fonctionnent toujours
Le fichier .lingo/metadata.json est créé ou mis à jour

Étapes suivantes#

Configuration

Guide complet de configuration

Référence de configuration

Toutes les nouvelles options de configuration

Intégration Next.js

Détails de migration spécifiques à Next.js

Vite + React

Détails de migration spécifiques à Vite

Cette page vous a-t-elle été utile ?