Bonnes pratiques

Modèles et flux de travail recommandés pour @lingo.dev/compiler.

Flux de travail de développement

Utiliser le pseudotraducteur par défaut

À faire :

{
  dev: {
    usePseudotranslator: true, // Fast, free, instant feedback
  }
}

Pourquoi :

  • Retour instantané — aucune latence d'API
  • Coût zéro — aucun crédit d'API consommé
  • Les marqueurs visuels indiquent ce qui est traduit
  • Teste l'interface avec des longueurs de texte variables

Désactiver uniquement lors de la vérification de la qualité réelle de la traduction.

Séparer le développement, l'intégration continue et la production

Développement :

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

Intégration continue :

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

Production :

{
  buildMode: "cache-only",
}

Ce flux de travail :

  • Maintient le développement rapide et économique
  • Génère de vraies traductions en intégration continue une fois par déploiement
  • Rend les builds de production déterministes et rapides

Stratégie de traduction

Laisser l'IA gérer la plupart des traductions

À faire :

<p>Welcome to our application</p>

À ne pas faire :

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our application
</p>

Utiliser les remplacements avec parcimonie — uniquement pour :

  • Les noms de marque
  • Les termes techniques nécessitant des traductions spécifiques
  • Le texte juridique nécessitant une certification
  • Le contenu marketing nécessitant une révision humaine

Utiliser les remplacements de manière cohérente

À faire :

// Consistent brand name across app
<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
  Lingo.dev
</h1>

<p>
  Welcome to <span data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
    Lingo.dev
  </span>
</p>

À ne pas faire :

<h1 data-lingo-override={{ es: "Lingo.dev" }}>Lingo.dev</h1>
<p>Welcome to Lingo.dev</p> // Missing override—inconsistent

Configuration

Commencer simplement

À faire :

{
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
}

À ne pas faire :

{
  sourceLocale: "en",
  targetLocales: ["es", "de", "fr", "pt", "it", "ja", "zh", "ar", "ru", "ko"],
  models: {
    "en:es": "groq:...",
    "en:de": "google:...",
    // Complex mappings for 10 locales
  },
  prompt: "Long custom prompt...",
  pluralization: { enabled: false },
}

Commencez avec 2 à 3 locales cibles. Ajoutez-en davantage selon les besoins. Évitez l'optimisation prématurée.

Utiliser le moteur Lingo.dev

À faire :

{
  models: "lingo.dev" // Simple, optimized, supports all features
}

À ne pas faire :

{
  models: {
    "*:*": "groq:...", // Requires manual model selection
  }
}

Le moteur Lingo.dev fournit :

  • Sélection automatique du modèle
  • Gestion des solutions de secours
  • Mémoire de traduction
  • Prise en charge du glossaire

Utilisez les fournisseurs LLM directs uniquement si vous avez besoin d'un contrôle total ou d'une optimisation des coûts.

Détection de la locale

À faire :

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

Quand personnaliser :

  • Besoin de localStorage (préférence SPA)
  • Routage basé sur l'URL (/en/about)
  • Routage par sous-domaine (es.example.com)
  • Préférences utilisateur stockées en base de données

Implémentez uniquement les résolveurs de locale personnalisés lorsque la configuration par défaut ne convient pas.

Contrôle de version

Commiter le répertoire .lingo/

À faire :

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

Pourquoi :

  • Le contrôle de version suit les modifications de traduction
  • L'équipe partage les traductions
  • Le CI/CD utilise les traductions commitées
  • Les builds de production n'ont pas besoin de clés API

Commiter après l'exécution du CI

À faire (dans le CI) :

- name: Generate translations
  run: npm run build

- name: Commit translations
  run: |
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

Cela garantit que les builds de production disposent toujours de traductions à jour.

CI/CD

Générer les traductions dans le CI

À faire :

# GitHub Actions
- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: npm run build

À ne pas faire :

# Production build without API key
- name: Build
  run: npm run build # Fails if translations missing

Générez les traductions dans le CI où vous disposez de clés API. Les builds de production utilisent les traductions en cache.

Utiliser cache-only en production

À faire :

# Production build
LINGO_BUILD_MODE=cache-only npm run build

À ne pas faire :

# Production build with translate mode
LINGO_BUILD_MODE=translate npm run build # Non-deterministic, requires API keys

Performance

Activer la pluralisation de manière sélective

À faire (si vous utilisez des formes plurielles) :

{
  pluralization: {
    enabled: true,
  }
}

À faire (si vous n'utilisez pas de pluriels) :

{
  pluralization: {
    enabled: false, // Skip plural detection—faster builds
  }
}

La pluralisation ajoute une légère surcharge (un appel LLM par texte avec des nombres). Désactivez si non nécessaire.

Utiliser des modèles rapides pour la pluralisation

À faire :

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

À ne pas faire :

{
  pluralization: {
    model: "openai:gpt-4o", // Expensive overkill for plural detection
  }
}

Optimiser le mappage des paires de locales

À faire (optimisation des coûts) :

{
  models: {
    "en:es": "groq:llama-3.3-70b-versatile", // Fast & cheap
    "en:ja": "openai:gpt-4o", // High quality for complex language
    "*:*": "lingo.dev", // Fallback
  }
}

Utilisez des modèles rapides/économiques pour les langues similaires (romanes, germaniques). Utilisez des modèles de haute qualité pour les langues complexes (CJC, arabe).

Tests

Tester d'abord avec le pseudotraducteur

À faire :

  1. Activer le pseudotraducteur
  2. Tester tous les composants de l'interface
  3. Corriger les problèmes de mise en page (débordement, troncature)
  4. Ensuite générer les vraies traductions

Pourquoi :

  • Les pseudotraductions sont instantanées
  • Révèle les problèmes de mise en page tôt
  • Économise les coûts d'API

Tester toutes les locales cibles

À faire :

// Test with locale switcher
<LanguageSwitcher /> // Switch between all locales

// Or manually test
setLocale("es"); // Spanish
setLocale("de"); // German
setLocale("fr"); // French

Vérifiez chaque locale :

  • Les traductions s'affichent correctement
  • La mise en page s'adapte à la longueur du texte
  • Aucun texte non traduit
  • Les langues RTL s'affichent correctement (le cas échéant)

Gestion des erreurs

Gérer les traductions manquantes avec élégance

Le compilateur fait échouer la compilation si des traductions sont manquantes. C'est intentionnel — mieux vaut détecter les traductions manquantes tôt que de livrer une interface défectueuse.

Si la compilation échoue :

  1. Exécutez avec buildMode: "translate" pour générer les traductions manquantes
  2. Commitez .lingo/metadata.json
  3. Relancez la compilation de production avec buildMode: "cache-only"

Surveiller les échecs de traduction

Dans la CI, vérifiez les erreurs de traduction :

- name: Generate translations
  run: npm run build 2>&1 | tee build.log

- name: Check for translation errors
  run: |
    if grep -q "Failed to generate translation" build.log; then
      echo "Translation generation failed"
      exit 1
    fi

Maintenance

Nettoyage régulier

Supprimez périodiquement les traductions inutilisées :

# Backup first
cp .lingo/metadata.json .lingo/metadata.backup.json

# Manual: Search for each hash in codebase, remove if not found

# Automated (coming soon):
npx @lingo.dev/compiler clean

Surveiller la taille du fichier

.lingo/metadata.json grandit avec votre application. S'il devient volumineux (>5 Mo) :

  • Envisagez de diviser en plusieurs applications
  • Archivez les anciennes traductions
  • Utilisez le nettoyage automatisé

Anti-patterns courants

N'abusez pas des remplacements

Mauvais :

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our app
</p>

Laissez l'IA gérer le texte standard. Les remplacements sont pour les exceptions.

Ne commitez pas les clés API

Mauvais :

// next.config.ts
{
  models: "lingo.dev",
  apiKey: "your-api-key-here", // NEVER commit API keys
}

Bon :

# .env (not committed)
LINGODOTDEV_API_KEY=your_key_here

N'utilisez pas le mode translate en production

Mauvais :

// production config
{
  buildMode: "translate", // Non-deterministic, requires API keys
}

Bon :

{
  buildMode: "cache-only", // Deterministic, no API keys
}

N'ignorez pas le contrôle de version

Mauvais :

# .gitignore
.lingo/ # DON'T ignore translations

Bon :

# .gitignore
.env # Ignore API keys only

Stratégie de migration

Déploiement progressif

Lors de l'ajout du compilateur à une application existante :

  1. Commencez avec 1 à 2 locales
  2. Activez le pseudotraducteur
  3. Testez toutes les pages
  4. Corrigez les problèmes de mise en page
  5. Ajoutez d'autres locales
  6. Générez les traductions réelles
  7. Déployez

N'essayez pas de traduire 20 locales dès le premier jour.

Adoption incrémentale

Vous n'avez pas besoin de traduire l'application entière d'un coup :

{
  useDirective: true, // Opt-in per file
}

Ajoutez la directive 'use i18n' aux fichiers que vous souhaitez traduire :

'use i18n'; // This file gets translated

export function HomePage() {
  return <h1>Welcome</h1>;
}

Les autres fichiers restent non traduits jusqu'à ce que vous les activiez.

Prochaines étapes