Référence de configuration

Référence complète pour toutes les options de configuration de @lingo.dev/compiler.

Options principales

Exemple

{
  sourceRoot: "./app",
  lingoDir: ".lingo",
  sourceLocale: "en",
  targetLocales: ["es", "de", "fr", "ja"],
  useDirective: false,
  models: "lingo.dev",
  buildMode: "translate",
}

Options de développement

Configurez le comportement spécifique au développement via l'objet dev :

Exemple

{
  dev: {
    usePseudotranslator: true, // Fast fake translations
    translationServerStartPort: 60000, // Default port range
  }
}

Pourquoi le pseudotraducteur ? Il est instantané (aucun appel API), montre exactement ce qui est traduit et teste votre interface utilisateur avec des longueurs de texte variables, le tout sans frais d'API.

Persistance de la locale

Configurez la manière dont les changements de locale sont persistés :

Exemple

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "user-locale",
      maxAge: 31536000, // 1 year
    },
  },
}

Persistance personnalisée ? Implémentez des résolveurs de locale personnalisés pour utiliser localStorage, des paramètres d'URL ou une persistance en base de données.

Pluralisation

Configurez la détection automatique de la pluralisation :

Exemple

{
  pluralization: {
    enabled: true,
    model: "groq:llama-3.1-8b-instant", // Fast model for plural detection
  },
}

Comment ça fonctionne : Le compilateur détecte les formes plurielles dans votre texte (par exemple, « Vous avez 5 éléments ») et les convertit au format ICU MessageFormat ({count, plural, one {1 item} other {# items}}).

Désactiver pour les performances : Si vous n'utilisez pas de formes plurielles, désactivez cette option pour éviter les appels LLM pour la pluralisation.

Fournisseurs de traduction

L'option models configure quel(s) fournisseur(s) LLM utiliser pour les traductions.

Configuration simple

Utilisez un seul fournisseur pour toutes les traductions :

{
  models: "lingo.dev" // Recommended: Lingo.dev Engine
}

Configuration avancée

Utilisez le mappage par paire de locales pour un contrôle granulaire :

{
  models: {
    "en:es": "groq:llama-3.3-70b-versatile", // English to Spanish
    "en:de": "google:gemini-2.0-flash",      // English to German
    "*:fr": "openai:gpt-4o",                 // Any locale to French
    "*:*": "anthropic:claude-3-5-sonnet",    // Fallback for all others
  }
}

Modèles :

• "source:target" : paire de locales spécifique (par ex., "en:es")
• "*:target" : n'importe quelle source vers une cible spécifique (par ex., "*:de")
• "source:*" : source spécifique vers n'importe quelle cible (par ex., "en:*")
• "*:*" : solution de repli pour toutes les paires

Consultez Fournisseurs de traduction pour la syntaxe des fournisseurs et la configuration des clés API.

Prompts de traduction personnalisés

Personnalisez le prompt de traduction en utilisant des espaces réservés :

{
  prompt: `Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}.
Use a formal tone and preserve all technical terms.
Do not translate brand names or product names.`
}

Espaces réservés disponibles :

• {SOURCE_LOCALE} : code de la locale source (par ex., "en")
• {TARGET_LOCALE} : code de la locale cible (par ex., "es")

Le compilateur ajoute le contexte du texte en cours de traduction (emplacement du composant, éléments environnants) à votre prompt personnalisé.

Remplacement par variable d'environnement

Remplacez la configuration via des variables d'environnement :

# Override build mode
LINGO_BUILD_MODE=cache-only npm run build

# Set API key
LINGODOTDEV_API_KEY=your_key_here
GROQ_API_KEY=gsk_...
GOOGLE_API_KEY=...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
MISTRAL_API_KEY=...
OPENROUTER_API_KEY=...

Exemple complet

// 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, {
    // Core
    sourceRoot: "./app",
    lingoDir: ".lingo",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr", "ja"],
    useDirective: false,

    // Build mode
    buildMode: process.env.NODE_ENV === "production" ? "cache-only" : "translate",

    // Models
    models: {
      "en:es": "groq:llama-3.3-70b-versatile",
      "*:*": "lingo.dev",
    },

    // Custom prompt
    prompt: "Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}. Use a professional tone.",

    // Development
    dev: {
      usePseudotranslator: true,
      translationServerStartPort: 60000,
    },

    // Locale persistence
    localePersistence: {
      type: "cookie",
      config: {
        name: "locale",
        maxAge: 31536000,
      },
    },

    // Pluralization
    pluralization: {
      enabled: true,
      model: "groq:llama-3.1-8b-instant",
    },
  });
}

Types TypeScript

Importez les types de configuration pour la sécurité des types :

import type { LingoConfig } from "@lingo.dev/compiler";

const config: LingoConfig = {
  // ...config
};

Questions fréquentes

Dois-je configurer toutes les options ? Non. Seuls sourceLocale et targetLocales sont requis. Toutes les autres ont des valeurs par défaut sensées.

Quelle est la différence entre sourceRoot et lingoDir ? sourceRoot est l'emplacement de votre code source (par ex., ./app, src). lingoDir est l'emplacement où les métadonnées de traduction sont stockées (par défaut : .lingo).

Puis-je utiliser différents modèles par locale ? Oui. Utilisez le mappage par paire de locales dans l'option models. Consultez Fournisseurs de traduction.

Dois-je commiter .lingo/ dans git ? Oui. Le répertoire .lingo/ contient les métadonnées de traduction et le cache. Il doit être versionné avec votre code.

Comment désactiver la pluralisation ? Définissez pluralization.enabled: false. Cela ignore la détection des formes plurielles et réduit les appels au LLM.

Prochaines étapes

• Fournisseurs de traduction — Configurer les fournisseurs LLM
• Modes de compilation — Comprendre translate vs cache-only
• Résolveurs de locale personnalisés — Implémenter une détection de locale personnalisée
• Bonnes pratiques — Configurations recommandées