Référence de configuration
Alpha
Lingo.dev Compiler est en alpha. Il reste instable, n’est pas recommandé en production et ses API peuvent évoluer d’une version à l’autre.
L’objet de configuration de Lingo.dev Compiler détermine comment votre application React est traduite au moment du build. Cette page documente chaque option disponible, avec son type, sa valeur par défaut et des exemples d’utilisation.
Options principales#
| Option | Type | Par défaut | Description |
|---|---|---|---|
sourceRoot | string | "src" | Répertoire contenant les composants à traduire. Chemin relatif à la racine du projet. |
lingoDir | string | ".lingo" | Répertoire des métadonnées de traduction et des fichiers de cache. |
sourceLocale | string | obligatoire | Code de langue de votre contenu source (par ex. "en"). |
targetLocales | string[] | obligatoire | Liste des codes de langue cibles (par ex. ["es", "de", "fr"]). |
useDirective | boolean | false | Lorsque true, seuls les fichiers contenant la directive 'use i18n' sont traduits. Lorsque false, tous les fichiers de sourceRoot sont traduits. |
models | string | object | "lingo.dev" | Configuration du fournisseur de traduction. Une chaîne définit la valeur par défaut pour toutes les paires de langues. Un objet associe chaque paire de langues à un fournisseur spécifique. |
prompt | string | undefined | Prompt système personnalisé pour le LLM de traduction. Prend en charge les placeholders {SOURCE_LOCALE} et {TARGET_LOCALE}. |
buildMode | "translate" | "cache-only" | "translate" | Détermine si le Compiler génère de nouvelles traductions ou utilise uniquement les traductions en cache. |
Options de développement#
Les options sous la clé dev contrôlent le comportement en phase de développement :
| Option | Type | Par défaut | Description |
|---|---|---|---|
dev.usePseudotranslator | boolean | false | Génère instantanément de fausses traductions (par ex. [!!! Welcome !!!]) au lieu d’appeler un LLM. Aucune clé API n’est nécessaire. |
dev.translationServerStartPort | number | 60000 | Port de départ du serveur de traduction local. Le Compiler trouve automatiquement un port disponible dans la plage 60000-60099. |
dev.translationServerUrl | string | undefined | Remplace l’URL du serveur de traduction. Utile pour les configurations personnalisées ou les serveurs de traduction distants. |
Persistance de la langue#
Les options sous localePersistence déterminent comment la langue sélectionnée par l’utilisateur est enregistrée et récupérée :
| Option | Type | Par défaut | Description |
|---|---|---|---|
localePersistence.type | string | "cookie" | Mécanisme de persistance. Prend actuellement en charge "cookie". |
localePersistence.config.name | string | "locale" | Nom du cookie utilisé pour stocker la langue. |
localePersistence.config.maxAge | number | 31536000 | Durée de vie maximale du cookie, en secondes (1 an par défaut). |
Pour une logique de persistance personnalisée (localStorage, URL, en-têtes), voir Custom Locale Resolvers.
Pluralisation#
Les options sous pluralization contrôlent la détection et la génération automatiques des formes plurielles :
| Option | Type | Par défaut | Description |
|---|---|---|---|
pluralization.enabled | boolean | true | Active ou désactive la détection automatique de la pluralisation. |
pluralization.model | string | "groq:llama-3.1-8b-instant" | Modèle LLM utilisé pour détecter les formes plurielles dans le texte source. Un modèle plus petit et plus rapide est recommandé, car cette détection est plus simple que la traduction. |
Voir Automatic Pluralization pour en savoir plus sur le fonctionnement de la détection des pluriels.
Variables d’environnement#
Les variables d’environnement remplacent ou complètent la configuration :
| Variable | Quand elle est requise | Description |
|---|---|---|
LINGO_BUILD_MODE | Facultatif | Remplace l’option de configuration buildMode. À définir sur "translate" ou "cache-only". |
LINGODOTDEV_API_KEY | Lors de l’utilisation de modèles "lingo.dev" | Clé API du moteur de localisation Lingo.dev. Disponible via npx @lingo.dev/cli login. |
OPENAI_API_KEY | Lors de l’utilisation de modèles "openai:*" | Clé API OpenAI. |
ANTHROPIC_API_KEY | Lors de l’utilisation de modèles "anthropic:*" | Clé API Anthropic. |
GOOGLE_API_KEY | Lors de l’utilisation de modèles "google:*" | Clé API Google AI. |
GROQ_API_KEY | Lors de l’utilisation de modèles "groq:*" | Clé API Groq. |
MISTRAL_API_KEY | Lors de l’utilisation de modèles "mistral:*" | Clé API Mistral. |
OPENROUTER_API_KEY | Lors de l’utilisation de modèles "openrouter:*" | Clé API OpenRouter. |
Exemple complet#
ts
// 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",
lingoDir: ".lingo",
sourceLocale: "en",
targetLocales: ["es", "de", "fr", "ja"],
useDirective: false,
models: {
"*:*": "lingo.dev",
"*:ja": "anthropic:claude-3-5-sonnet",
},
prompt: "Translate UI text from {SOURCE_LOCALE} to {TARGET_LOCALE}. Keep it concise.",
buildMode: "translate",
dev: {
usePseudotranslator: true,
translationServerStartPort: 60000,
},
localePersistence: {
type: "cookie",
config: {
name: "locale",
maxAge: 31536000,
},
},
pluralization: {
enabled: true,
model: "groq:llama-3.1-8b-instant",
},
});
}