Guide de migration - Lingo.dev Compiler

Migrez de l'ancien compilateur (lingo.dev/compiler) vers le nouveau @lingo.dev/compiler.

Pourquoi migrer ?

Le nouveau compilateur offre :

Meilleure expérience développeur — Automatique par défaut (pas besoin de 'use i18n')
Meilleures performances — Builds plus rapides, meilleur HMR
Modes de build — Séparation des préoccupations dev/CI/prod
Surcharges manuelles — Attribut data-lingo-override
Résolveurs de locale personnalisés — Détection flexible de la locale
Outils de développement — Pseudotraducteur, widget de développement (bientôt disponible)
Architecture plus propre — Meilleure séparation des préoccupations

Changements incompatibles

1. Nom du package

Ancien :

npm install lingo.dev

Nouveau :

npm install @lingo.dev/compiler

2. Chemins d'import

Ancien :

import lingoCompiler from "lingo.dev/compiler";
import { LingoProvider } from "lingo.dev/react/rsc";

Nouveau :

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

3. API de configuration

Next.js

Ancien :

// next.config.js
import lingoCompiler from "lingo.dev/compiler";

export default lingoCompiler.next({
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
})(nextConfig);

Nouveau :

// next.config.ts
import { withLingo } from "@lingo.dev/compiler/next";

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

Changements :

La configuration doit être une fonction asynchrone
Nouvelle option sourceRoot
Wrapper withLingo au lieu de lingoCompiler.next

Vite

Ancien :

import lingoCompiler from "lingo.dev/compiler";

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    targetLocales: ["es", "de"],
    models: "lingo.dev",
  })(viteConfig)
);

Nouveau :

import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

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

Modifications :

Basé sur des plugins au lieu d'un wrapper de configuration
sourceLocale est maintenant requis
Placer avant le plugin react()

4. Configuration du provider

Ancien :

import { LingoProvider, loadDictionary } from "lingo.dev/react/rsc";

export default function Layout({ children }) {
  return (
    <LingoProvider loadDictionary={(locale) => loadDictionary(locale)}>
      {children}
    </LingoProvider>
  );
}

Nouveau :

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

export default function Layout({ children }) {
  return (
    <LingoProvider>
      {children}
    </LingoProvider>
  );
}

Modifications :

Pas de prop loadDictionary—géré en interne
API plus simple

5. Structure des fichiers

Ancien :

lingo/
├── dictionary.js
├── meta.json
└── [locale]/
    └── *.json

Nouveau :

.lingo/
└── metadata.json

Modifications :

Répertoire renommé (.lingo vs lingo)
Un seul fichier de métadonnées au lieu de plusieurs fichiers
Structure JSON différente

6. Directive "use i18n"

Ancien : Requis par défaut. Ajouter à chaque fichier que vous souhaitez traduire :

'use i18n';

export function Component() { ... }

Nouveau : Optionnel. Par défaut, tous les fichiers sont traduits automatiquement. Pour activer l'opt-in :

{
  useDirective: true, // Enable opt-in behavior
}

Puis ajouter la directive :

'use i18n';

export function Component() { ... }

Étapes de migration

Étape 1 : mettre à jour le package

# Uninstall old package
npm uninstall lingo.dev

# Install new package
npm install @lingo.dev/compiler

Étape 2 : mettre à jour la configuration

Next.js

Avant :

// next.config.js
import lingoCompiler from "lingo.dev/compiler";

export default lingoCompiler.next({
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
})(nextConfig);

Après :

// next.config.ts
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"],
    models: "lingo.dev",
    dev: {
      usePseudotranslator: true, // Recommended for development
    },
  });
}

Vite

Avant :

import lingoCompiler from "lingo.dev/compiler";

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    targetLocales: ["es", "de"],
    models: "lingo.dev",
  })(viteConfig)
);

Après :

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"],
      models: "lingo.dev",
      dev: {
        usePseudotranslator: true,
      },
    }),
    react(),
  ],
});

Étape 3 : mettre à jour le provider

Avant :

import { LingoProvider, loadDictionary } from "lingo.dev/react/rsc";

export default function Layout({ children }) {
  return (
    <LingoProvider loadDictionary={(locale) => loadDictionary(locale)}>
      {children}
    </LingoProvider>
  );
}

Après :

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

export default function Layout({ children }) {
  return (
    <LingoProvider>
      {children}
    </LingoProvider>
  );
}

Étape 4 : nettoyer les anciens fichiers

# Backup old translations (optional)
mv lingo lingo.backup

# Remove old directory
rm -rf lingo

# New directory will be created automatically
# on first build

Étape 5 : tester avec le pseudotraducteur

npm run dev

Avec usePseudotranslator: true, vous verrez des fausses traductions instantanées. Vérifiez :

Tout le texte attendu est traduit
Aucune erreur de compilation
La mise en page gère les longueurs de texte variables

Étape 6 : générer les vraies traductions

Mettez à jour la configuration pour désactiver le pseudotraducteur :

{
  dev: {
    usePseudotranslator: false,
  }
}

Redémarrez le serveur de développement. Le compilateur générera de vraies traductions pour tout texte nouveau ou modifié.

Étape 7 : Valider les nouvelles traductions

git add .lingo/
git commit -m "chore: migrate to @lingo.dev/compiler"
git push

Correspondance des fonctionnalités

Anciennes fonctionnalités → Nouveaux équivalents

Ancienne fonctionnalité	Nouvel équivalent	Notes
`dictionary.js`	`.lingo/metadata.json`	Format différent
`meta.json`	`.lingo/metadata.json`	Fusionné dans un seul fichier
"use i18n" (requis)	"use i18n" (optionnel)	Désormais opt-in, non requis
Prompts personnalisés	Option de config `prompt`	Même fonctionnalité
Édition des traductions	`data-lingo-override`	Remplacements basés sur les attributs
Ignorer les traductions	`data-lingo-override` + vide	Ou utiliser `useDirective`
Remplacer les traductions	`data-lingo-override`	Basé sur les attributs
Changer de locale	`useLingoContext()`	Retourne `{ locale, setLocale }`
Fournisseurs LLM	Config `models`	Mêmes fournisseurs pris en charge

Nouvelles fonctionnalités (absentes de l'ancien compilateur)

Modes de build — translate vs cache-only
Pseudotraducteur — Fausses traductions instantanées
Widget de développement — Édition dans le navigateur (à venir)
Résolveurs de locale personnalisés — Détection flexible de la locale
Pluralisation automatique — Support du format ICU MessageFormat
Serveur de traduction — Traductions à la demande en dev

Traduire les traductions existantes

Le nouveau compilateur utilise un format de fichier différent. Les traductions existantes ne sont pas migrées automatiquement.

Options :

Option 1 : Régénérer toutes les traductions

Laisser le compilateur générer de nouvelles traductions :

Supprimer l'ancien répertoire lingo/
Exécuter le nouveau compilateur
Générer les traductions avec l'IA

Avantages : Nouveau départ, modèles d'IA les plus récents Inconvénients : Coûts d'API, risque de perte de nuances

Option 2 : script de migration manuel

Créez un script pour convertir l'ancien format vers le nouveau :

// migrate-translations.ts
import * as fs from "fs";

const oldDir = "./lingo";
const newFile = "./.lingo/metadata.json";

// Read old translations
const oldTranslations = {}; // Parse old files

// Convert to new format
const newMetadata = {
  version: "1",
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  translations: {}, // Convert old translations
};

// Write new metadata
fs.writeFileSync(newFile, JSON.stringify(newMetadata, null, 2));

Il s'agit d'un travail manuel et spécifique au format.

Option 3 : approche hybride

Générez de nouvelles traductions pour la plupart du texte
Utilisez data-lingo-override pour les traductions critiques nécessitant une formulation exacte

Problèmes courants

« Cannot find module '@lingo.dev/compiler' » Exécutez npm install @lingo.dev/compiler

« Config must be async function » (Next.js) Enveloppez votre configuration dans async function :

export default async function () {
  return await withLingo(...);
}

« sourceLocale is required » Ajoutez sourceLocale: "en" à votre configuration.

Les traductions ne s'affichent pas Vérifiez :

LingoProvider est dans la mise en page racine
.lingo/metadata.json existe
Aucune erreur dans la console

FAQ

Puis-je exécuter les deux compilateurs simultanément ? Non. Désinstallez l'ancien compilateur avant d'installer le nouveau.

Est-ce que je perds mes traductions ? Pas si vous les migrez manuellement. Sinon, régénérez-les avec l'IA (coûte des crédits API).

Que faire si mon framework n'est pas encore pris en charge ? Le nouveau compilateur prend actuellement en charge Next.js et Vite. D'autres frameworks arrivent bientôt. Continuez à utiliser l'ancien compilateur ou contribuez à la prise en charge de votre framework.

Combien de temps prend la migration ?

Projet simple : 15-30 minutes
Projet complexe : 1-2 heures
La majeure partie du temps est consacrée aux tests et à la vérification des traductions

Dois-je migrer maintenant ou attendre ? Migrez quand :

Vous avez besoin de nouvelles fonctionnalités (modes de build, overrides, résolveurs personnalisés)
Vous démarrez un nouveau projet
Vous voulez une meilleure expérience développeur

Attendez si :

Votre projet fonctionne bien avec l'ancien compilateur
Vous avez besoin de frameworks pas encore pris en charge par le nouveau compilateur

Prochaines étapes

Démarrage rapide — Configurez le nouveau compilateur
Référence de configuration — Explorez toutes les options
Bonnes pratiques — Workflows recommandés
Dépannage — Problèmes courants