Structure du projet

Le Compiler de Lingo.dev crée et maintient un répertoire .lingo/ à la racine de votre projet pour stocker les métadonnées de traduction et le cache. Comprendre sa structure vous aide à gérer les traductions dans le contrôle de version, à diagnostiquer les traductions manquantes et à optimiser les performances de build.

Le répertoire .lingo/#

Le Compiler crée ce répertoire automatiquement lors du premier build. Il contient toutes les métadonnées de traduction utilisées par le pipeline de build :

.lingo/
  metadata.json              # Translation cache and content hashes
  locale-resolver.server.ts  # Optional: custom server-side locale resolver
  locale-resolver.client.ts  # Optional: custom client-side locale resolver

metadata.json#

Il s’agit du fichier principal du répertoire .lingo/. Il contient :

• Hachages de contenu — des identifiants stables basés sur un hash pour chaque chaîne traduisible
• Traductions en cache — les traductions générées pour chaque paire de langues
• Instantanés du texte source — le texte source au moment de la traduction, utilisé pour détecter les changements

Le Compiler lit ce fichier au début de chaque build. Les chaînes dont le hash correspond réutilisent les traductions en cache. Les chaînes dont le hash a changé ou est manquant sont envoyées au fournisseur de traduction configuré.

À savoir pour .gitignore#

N’ajoutez pas .lingo/ à .gitignore. Ce répertoire doit être suivi dans le contrôle de version. Exemple de .gitignore pour un projet qui utilise le Compiler :

# Do NOT ignore .lingo/ - it contains translation cache
node_modules/
dist/
.env

sourceRoot#

L’option sourceRoot détermine le répertoire que le Compiler analyse pour trouver les composants React traduisibles :

{
  sourceRoot: "./app",  // Next.js App Router
  // or
  sourceRoot: "src",    // Vite + React
}

Le Compiler analyse récursivement tous les fichiers .tsx, .ts, .jsx et .js dans sourceRoot à la recherche de contenu JSX traduisible. Les fichiers en dehors de ce répertoire ne sont pas traités.

Mode opt-in avec 'use i18n'#

Par défaut, le Compiler traduit tout le texte JSX dans sourceRoot. Pour passer en mode opt-in, définissez useDirective: true :

{
  useDirective: true,
}

En mode opt-in, seuls les fichiers qui commencent par la directive 'use i18n' sont traités :

'use i18n';

export function Welcome() {
  return <h1>Welcome to our app</h1>;
  // This text IS translated
}

Les fichiers sans cette directive sont ignorés :

export function InternalAdmin() {
  return <h1>Admin Dashboard</h1>;
  // This text is NOT translated
}

Quand utiliser le mode opt-in#

lingoDir#

L’option lingoDir change l’emplacement du répertoire de métadonnées :

{
  lingoDir: ".lingo",  // Default
  // or
  lingoDir: ".translations",  // Custom location
}

C’est utile si .lingo/ entre en conflit avec un répertoire existant dans votre projet.

Étapes suivantes#