Modes de compilation

@lingo.dev/compiler prend en charge deux modes de compilation qui contrôlent quand et comment les traductions sont générées.

Aperçu des modes

ModeQuand l'utiliserAppels APIComportement
translateDéveloppement, CIOuiGénère les traductions manquantes en utilisant le LLM configuré
cache-onlyBuilds de productionNonUtilise uniquement les traductions en cache depuis .lingo/metadata.json

Mode translate

Objectif : générer les traductions à la demande pendant les builds.

{
  buildMode: "translate"
}

Comportement :

  • Analyse le code pour détecter le texte traduisible
  • Vérifie .lingo/metadata.json pour les traductions existantes
  • Génère les traductions manquantes via le fournisseur LLM configuré
  • Met à jour .lingo/metadata.json avec les nouvelles traductions
  • Échoue le build si la génération de traduction échoue

Quand l'utiliser :

  • Développement local (avec usePseudotranslator: true)
  • Pipelines CI/CD (avec de vrais fournisseurs LLM)
  • Configuration initiale et génération de traductions

Nécessite :

  • Clé API valide pour le fournisseur configuré (ou pseudotranslator activé)
  • Connexion réseau au fournisseur LLM

Mode cache uniquement

Objectif : compiler en utilisant uniquement les traductions pré-générées.

{
  buildMode: "cache-only"
}

Comportement :

  • Lit les traductions depuis .lingo/metadata.json
  • Aucun appel API effectué
  • Échoue le build si des traductions manquent pour une locale
  • Builds rapides et déterministes

Quand l'utiliser :

  • Builds de production
  • Déploiements sans clés API
  • Environnements avec accès réseau restreint

Nécessite :

  • .lingo/metadata.json avec des traductions pour toutes les locales
  • Traductions pré-générées en CI ou en développement

Workflow recommandé

1. Développement local

Utilisez le pseudotranslator pour un retour instantané :

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: true,
  }
}

Avantages :

  • Traductions factices instantanées
  • Aucun coût d'API
  • Voir exactement ce qui est traduit
  • Tester l'interface utilisateur avec des longueurs de texte variables

2. Pipeline CI/CD

Générer de vraies traductions dans le CI :

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}

Configuration dans le CI :

# GitHub Actions example
- name: Install dependencies
  run: pnpm install

- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: pnpm run build

- name: Commit translations
  run: |
    git config user.name "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

Avantages :

  • Traductions réelles générées une fois par déploiement
  • Commitées dans le contrôle de version
  • Les builds de production n'ont pas besoin de clés API

3. Build de production

Utiliser uniquement les traductions en cache :

{
  buildMode: "cache-only",
}

Avantages :

  • Aucune clé API nécessaire
  • Builds rapides
  • Déterministe — la même entrée produit toujours la même sortie
  • Aucune dépendance réseau externe

Remplacement par variable d'environnement

Remplacer le mode de build via une variable d'environnement :

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

# Force translate mode
LINGO_BUILD_MODE=translate npm run build

Ceci est utile pour les environnements de déploiement où vous souhaitez imposer le mode cache-only sans modifier la configuration.

Gestion des traductions manquantes

En mode translate

Si la traduction échoue :

Error: Failed to generate translation for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - Provider: lingo.dev
  - Reason: API key invalid

Solution : Corriger la clé API, relancer le build.

En mode cache-only

Si des traductions sont manquantes :

Error: Missing translations for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - File: app/page.tsx:12

Run with buildMode: "translate" to generate missing translations.

Solution : Exécuter un build avec le mode translate pour générer les traductions manquantes, puis commiter .lingo/.

Traduction incrémentale

Le compilateur utilise le hachage de contenu pour déterminer ce qui nécessite une traduction :

  1. Chaque chaîne traduisible reçoit un hash stable
  2. Le hash est basé sur le texte source + le contexte
  3. Si le hash existe dans .lingo/metadata.json, la traduction est réutilisée
  4. Seul le texte nouveau ou modifié déclenche une nouvelle traduction

Résultat : vous ne payez les traductions qu'une seule fois. Les builds suivants réutilisent les traductions en cache.

Exemples de configuration CI

GitHub Actions

name: Generate Translations

on:
  push:
    branches: [main]
  pull_request:

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - name: Install dependencies
        run: pnpm install

      - name: Generate translations
        env:
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
        run: pnpm run build

      - name: Commit translations
        if: github.event_name == 'push'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add .lingo/
          git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
          git push

GitLab CI

stages:
  - translate

generate-translations:
  stage: translate
  script:
    - pnpm install
    - pnpm run build
    - git config user.name "GitLab CI"
    - git config user.email "[email protected]"
    - git add .lingo/
    - git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
    - git push origin HEAD:$CI_COMMIT_REF_NAME
  only:
    - main

Questions fréquentes

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

Que se passe-t-il si j'oublie de générer les traductions dans la CI ? Le build de production échouera avec une erreur claire listant les traductions manquantes. Générez-les dans la CI, committez et redéployez.

Puis-je utiliser le mode translate en production ? Oui, mais ce n'est pas recommandé. Cela rend les builds non déterministes et nécessite des clés API en production. Il est préférable de générer les traductions dans la CI.

Comment tester le mode cache-only localement ?

  1. Générez les traductions avec le mode translate
  2. Passez au mode cache-only
  3. Lancez le build — il devrait réussir en utilisant les traductions en cache

Que se passe-t-il si mon texte source change ? Le hash change, donc une nouvelle traduction est générée (en mode translate). L'ancienne traduction est conservée dans .lingo/metadata.json pour l'historique.

Dois-je committer .lingo/ dans git ? Oui. Le répertoire .lingo/ doit être versionné. Il contient votre cache de traductions.

Prochaines étapes