Structure du projet

Comprendre le répertoire .lingo/ et son contenu.

Vue d'ensemble du répertoire

Lors de la première exécution du compilateur, il crée un répertoire .lingo/ à la racine de votre projet :

your-project/
├── .lingo/
│   ├── metadata.json
│   ├── locale-resolver.server.ts (optional)
│   └── locale-resolver.client.ts (optional)
├── src/
├── package.json
└── ...

metadata.json

Le fichier principal contenant toutes les données de traduction.

Structure

{
  "version": "1",
  "sourceLocale": "en",
  "targetLocales": ["es", "de", "fr"],
  "translations": {
    "abc123def456": {
      "source": "Welcome to our app",
      "context": {
        "file": "app/page.tsx",
        "line": 12,
        "component": "HomePage"
      },
      "locales": {
        "es": "Bienvenido a nuestra aplicación",
        "de": "Willkommen in unserer App",
        "fr": "Bienvenue dans notre application"
      },
      "metadata": {
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    }
  }
}

Champs clés

Version : version du format des métadonnées. Actuelle : "1"

Locales source/cible : vos locales configurées

Traductions : mappage basé sur des hash de toutes les chaînes traduisibles :

  • Hash (abc123def456) : identifiant stable basé sur le texte source + contexte
  • source : texte anglais original
  • context : emplacement de ce texte (fichier, ligne, composant)
  • locales : traductions pour chaque locale cible
  • metadata : date de création/mise à jour de la traduction

Génération des hash

Les hash sont déterministes :

  • basés sur le texte source + contexte du composant
  • même texte à différents emplacements = hash différents
  • permet des traductions contextuelles

Exemple :

// app/home/page.tsx
<button>Submit</button> // Hash: abc123

// app/checkout/page.tsx
<button>Submit</button> // Hash: def456 (different context)

Résolveurs de locale personnalisés

Fichiers optionnels pour personnaliser la détection et la persistance des locales.

locale-resolver.server.ts

Détection de locale côté serveur (Next.js uniquement) :

// .lingo/locale-resolver.server.ts
export async function getServerLocale(): Promise<string> {
  // Your custom logic
  return "en";
}

locale-resolver.client.ts

Détection et persistance de locale côté client :

// .lingo/locale-resolver.client.ts
export function getClientLocale(): string {
  // Detect locale
  return "en";
}

export function persistLocale(locale: string): void {
  // Save locale preference
}

Si ces fichiers n'existent pas, le compilateur utilise le comportement par défaut basé sur les cookies.

Voir Résolveurs de locale personnalisés pour plus de détails.

Contrôle de version

Devez-vous commiter .lingo/ ?

Oui. Le répertoire .lingo/ doit être sous contrôle de version :

À commiter :

  • metadata.json — Contient toutes les traductions
  • Résolveurs de locale personnalisés (si créés)

À ne pas commiter :

  • Rien — tous les fichiers dans .lingo/ doivent être commités

Pourquoi commiter les traductions ?

  1. Contrôle de version — Suivez les modifications de traduction avec le code
  2. Collaboration d'équipe — Partagez les traductions au sein de l'équipe
  3. CI/CD — Les builds de production utilisent les traductions commitées
  4. Piste d'audit — Voyez quand les traductions ont changé et pourquoi

Intégration Git

Ajoutez .lingo/ à votre dépôt :

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

Le compilateur met automatiquement à jour .lingo/metadata.json lorsque :

  • Un nouveau texte traduisible est ajouté
  • Un texte existant est modifié
  • Des traductions sont générées

Commitez ces mises à jour régulièrement.

Taille des fichiers

metadata.json grandit avec votre application :

  • Petite application (50 chaînes) : ~10 Ko
  • Application moyenne (500 chaînes) : ~100 Ko
  • Grande application (5000 chaînes) : ~1 Mo

C'est normal et acceptable pour le contrôle de version.

Nettoyage

Supprimer les traductions inutilisées

Au fil du temps, vous pouvez accumuler des traductions inutilisées (provenant de composants supprimés).

Nettoyage manuel :

  1. Recherchez le hash dans votre base de code
  2. S'il n'est pas trouvé, supprimez-le de metadata.json

Nettoyage automatisé (bientôt disponible) :

npx @lingo.dev/compiler clean

Cela supprimera automatiquement les traductions inutilisées.

Réinitialiser les traductions

Pour régénérer toutes les traductions depuis zéro :

# Backup current translations
cp .lingo/metadata.json .lingo/metadata.backup.json

# Delete metadata
rm .lingo/metadata.json

# Regenerate
npm run dev # or npm run build

Migration

Depuis l'ancien compilateur

L'ancien compilateur utilisait une structure de fichiers différente :

Ancien :

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

Nouveau :

.lingo/
└── metadata.json

La migration n'est pas automatisée. Consultez le guide de migration pour plus de détails.

Inspection des traductions

Afficher dans l'éditeur

Ouvrez .lingo/metadata.json dans votre éditeur :

{
  "translations": {
    "abc123": {
      "source": "Welcome",
      "locales": {
        "es": "Bienvenido"
      }
    }
  }
}

Rechercher une traduction

Trouvez une traduction par le texte source :

grep -r "Welcome" .lingo/metadata.json

Rechercher par hash

grep -r "abc123" .lingo/metadata.json

Affichage formaté

cat .lingo/metadata.json | jq '.'

Questions fréquentes

Puis-je modifier metadata.json manuellement ? Oui, mais ce n'est pas recommandé. Utilisez plutôt data-lingo-override — c'est plus sûr et versionné dans le code source.

Que se passe-t-il si je supprime metadata.json ? Le compilateur le régénère lors de la prochaine compilation. Toutes les traductions seront générées à nouveau (coûte des crédits API).

Puis-je déplacer .lingo/ vers un autre répertoire ? Oui. Configurez via l'option lingoDir :

{
  lingoDir: "translations"
}

Le fichier metadata.json contient-il des données sensibles ? Non. Il contient uniquement le texte source et les traductions — aucune clé API ni secret.

Puis-je fusionner metadata.json depuis plusieurs branches ? Oui. Git gère les fusions automatiquement. Les conflits sont rares (les hachages sont uniques).

Que se passe-t-il si deux branches ajoutent la même traduction ? Git les fusionne automatiquement. Si les hachages diffèrent (contexte différent), les deux sont conservés.

Prochaines étapes