Dépannage

Problèmes courants et solutions lors de l'utilisation de @lingo.dev/compiler.

Problèmes d'installation

« Cannot find module '@lingo.dev/compiler' »

Cause : Le package n'est pas installé ou a été installé incorrectement.

Solution :

npm install @lingo.dev/compiler
# or
pnpm install @lingo.dev/compiler

Vérifiez l'installation :

ls node_modules/@lingo.dev/compiler

« Module not found: Can't resolve '@lingo.dev/compiler/react' »

Cause : Importation depuis un chemin incorrect ou package obsolète.

Solution :

  1. Vérifiez l'instruction d'importation :

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

  2. Réinstallez le package :

    rm -rf node_modules
npm install

Problèmes de configuration

« Config must be async function » (Next.js)

Cause : La configuration Next.js n'est pas encapsulée dans une fonction asynchrone.

Solution :

// Wrong
export default withLingo(nextConfig, {...});

// Correct
export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {...});
}

« sourceLocale is required »

Cause : sourceLocale manquant dans la configuration.

Solution :

{
  sourceLocale: "en", // Required
  targetLocales: ["es", "de"],
}

« targetLocales must be an array »

Cause : targetLocales n'est pas un tableau ou est vide.

Solution :

{
  targetLocales: ["es", "de"], // Must be array with at least one locale
}

Problèmes de traduction

Les traductions ne s'affichent pas

Symptômes : Le texte apparaît uniquement dans la langue source.

Causes et solutions :

1. LingoProvider non ajouté ou mal positionné

// Wrong - too low in tree
export default function Page() {
  return (
    <LingoProvider>
      <Content />
    </LingoProvider>
  );
}

// Correct - in root layout
export default function RootLayout({ children }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

2. Traductions manquantes dans les métadonnées Vérifiez .lingo/metadata.json :

{
  "translations": {
    "abc123": {
      "locales": {
        "es": "..." // Should have translation
      }
    }
  }
}

Si vide ou manquant, exécutez avec buildMode: "translate" :

npm run dev # or build

3. Le mode de build est cache-only sans traductions en cache

# Generate translations first
LINGO_BUILD_MODE=translate npm run build

# Then use cache-only
LINGO_BUILD_MODE=cache-only npm run build

Toutes les traductions sont "[!!! ...]"

Cause : Le pseudotraducteur est activé.

Solution :

{
  dev: {
    usePseudotranslator: false, // Disable for real translations
  }
}

Redémarrez le serveur de développement.

Certains textes ne sont pas traduits

Causes :

1. Contenu dynamique ou props

// Not translated (yet) - string in variable
const title = "Welcome";
<h1>{title}</h1>

// Translated - string in JSX
<h1>Welcome</h1>

Solution : Le compilateur est en cours d'amélioration pour prendre en charge les littéraux de chaîne. Pour l'instant, placez le texte directement dans le JSX.

2. Le texte dans les attributs nécessite une gestion spécifique

// Translated automatically
<img alt="Logo" />
<button aria-label="Close" />

// May need explicit handling
<div custom-attr="Some text" /> // Not translated unless configured

3. useDirective est activé Si useDirective: true, les fichiers sans 'use i18n' ne sont pas traduits.

Solution : ajoutez la directive :

'use i18n';

export function Component() { ... }

Problèmes de build

« Traductions manquantes pour la locale X »

Cause : buildMode: "cache-only" mais les traductions sont manquantes.

Solution :

  1. Générez les traductions :

    npm run dev # or
LINGO_BUILD_MODE=translate npm run build

  2. Commitez .lingo/metadata.json

  3. Réessayez avec cache-only

« Échec de la génération de traduction »

Causes :

1. Clé API invalide

# Check .env file
cat .env | grep API_KEY

Assurez-vous que la clé API est correcte pour votre fournisseur.

2. Problèmes réseau Testez la connexion API :

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

3. Limitation de débit Ralentissez la génération de traductions ou passez à un niveau d'API supérieur.

4. Configuration de modèle invalide

// Wrong
{
  models: {
    "*:*": "invalid-provider:model",
  }
}

// Correct
{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
  }
}

Le build est lent

Causes :

1. Génération de nombreuses traductions Le premier build avec du nouveau texte est lent. Les builds suivants sont rapides (mis en cache).

2. Pseudotranslator désactivé en développement

{
  dev: {
    usePseudotranslator: true, // Enable for fast development
  }
}

3. Pluralisation activée inutilement

{
  pluralization: {
    enabled: false, // Disable if not using plural forms
  }
}

Problèmes HMR

HMR ne fonctionne pas

Cause : Placement du LingoProvider ou configuration du framework.

Solutions :

Next.js : Assurez-vous que LingoProvider est dans la mise en page racine, pas dans des mises en page imbriquées.

Vite : Assurez-vous que lingoCompilerPlugin est placé avant le plugin react() :

plugins: [
  lingoCompilerPlugin({...}), // Before react plugin
  react(),
]

Réinitialisation de l'état lors du changement de traduction

Cause : Rechargement de la page déclenché par le changement de locale.

Comportement attendu : setLocale() recharge la page par défaut pour appliquer la nouvelle locale.

Pour éviter le rechargement : Implémentez un persistLocale personnalisé sans rechargement :

// .lingo/locale-resolver.client.ts
export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
  // Don't call window.location.reload()
}

Remarque : cela nécessite le préchargement des traductions pour toutes les locales.

Problèmes API/authentification

« Clé API invalide »

Solutions :

1. Vérifiez le nom de la variable d'environnement

# Lingo.dev Engine
LINGODOTDEV_API_KEY=...

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

2. Vérifiez que la clé API est active Connectez-vous au tableau de bord du fournisseur et vérifiez le statut de la clé.

3. Redémarrez le serveur de développement après avoir ajouté la clé

npm run dev

Les variables d'environnement sont chargées au démarrage.

« Échec de l'authentification » (Lingo.dev)

Solutions :

1. Se réauthentifier

npx lingo.dev@latest login

2. Clé API manuelle

# Add to .env
LINGODOTDEV_API_KEY=your_key_here

Obtenez la clé depuis les paramètres du projet sur lingo.dev.

Le navigateur bloque le flux d'authentification

Cause : Le navigateur Brave ou des extensions bloquent l'authentification.

Solution : Ajoutez manuellement la clé API dans .env :

LINGODOTDEV_API_KEY=...

Problèmes de serveur

« Échec du démarrage du serveur de traduction »

Cause : Tous les ports 60000-60099 sont utilisés.

Solutions :

1. Configurer une plage de ports différente

{
  dev: {
    translationServerStartPort: 61000,
  }
}

2. Arrêter les processus existants

# Find processes using ports
lsof -i :60000-60099

# Kill process
kill -9 <PID>

« Le port 60000 est déjà utilisé »

Cause : Un autre processus utilise ce port.

Solution : Le serveur trouve automatiquement le prochain port disponible. Vérifiez la console pour connaître le port réel :

[lingo] Translation server started on port 60001

Si tous les ports sont occupés, consultez « Échec du démarrage du serveur de traduction » ci-dessus.

Erreurs de type

« La propriété 'data-lingo-override' n'existe pas »

Cause : TypeScript ne reconnaît pas l'attribut.

Solution : Ajoutez une déclaration de type :

// global.d.ts
declare namespace React {
  interface HTMLAttributes<T> {
    "data-lingo-override"?: Record<string, string>;
  }
}

Ou utilisez des guillemets :

<div {"data-lingo-override"}={{ es: "..." }}>
  Text
</div>

« Erreur de type : Config doit retourner Promise »

Cause : La configuration Next.js n'est pas correctement typée.

Solution :

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, {...});
}

Problèmes en production

Traductions manquantes en production

Causes :

1. .lingo/ non commité

git add .lingo/
git commit -m "chore: add translations"
git push

2. Le mode de build de production est incorrect

// Should be cache-only in production
{
  buildMode: "cache-only",
}

3. La CI n'a pas généré les traductions Vérifiez les logs de la CI — assurez-vous que les traductions ont été générées et commitées.

Traductions différentes en dev et en prod

Cause : Le pseudotraducteur est activé en production.

Solution :

{
  dev: {
    usePseudotranslator: process.env.NODE_ENV === "development", // Only in dev
  }
}

Obtenir de l'aide

Si vous êtes toujours bloqué :

  1. Vérifiez les logs — Recherchez les messages d'erreur dans la console
  2. Vérifiez .lingo/metadata.json — Vérifiez la structure et le contenu
  3. Testez avec le pseudotraducteur — Isolez les problèmes d'API
  4. Consultez les issues GitHub — github.com/lingodotdev/lingo.dev/issues
  5. Posez vos questions sur Discord — discord.gg/lingo

Lorsque vous demandez de l'aide, incluez :

  • Message d'erreur (trace complète de la pile)
  • Configuration (next.config.ts ou vite.config.ts)
  • Versions des packages (npm list @lingo.dev/compiler)
  • Étapes pour reproduire

Questions fréquentes

Q : Ai-je besoin de clés API en production ? R : Non, avec buildMode: "cache-only". Les traductions sont pré-générées dans la CI.

Q : Pourquoi ma compilation échoue-t-elle ? R : Vérifiez le message d'erreur. Causes courantes : traductions manquantes, clé API invalide, problèmes réseau.

Q : Puis-je utiliser plusieurs fournisseurs LLM ? R : Oui, avec le mappage de paires de locales dans la configuration models.

Q : Comment tester sans frais d'API ? R : Activez usePseudotranslator: true en développement.

Prochaines étapes