Alpha
Le Compiler de Lingo.dev est en version alpha. Il est instable, déconseillé en production, et les API peuvent évoluer d’une version à l’autre.
Le Compiler de Lingo.dev fonctionne avec deux modes de build qui déterminent si de nouvelles traductions sont générées pendant le build. Bien comprendre ces modes est essentiel pour mettre en place un pipeline fiable en développement, en CI et en production.
Les deux modes#
| Mode | Comportement | Quand l’utiliser |
|---|---|---|
"translate" | Génère les traductions manquantes en faisant appel au fournisseur LLM configuré. Les traductions en cache sont réutilisées. | Développement et CI — lorsque du texte nouveau ou modifié doit être traduit. |
"cache-only" | Utilise uniquement les traductions issues de .lingo/metadata.json. Échoue si une traduction est manquante. | Builds de production — sortie déterministe sans appel à des API externes. |
Fonctionnement du mode translate#
En mode translate, le Compiler vérifie chaque chaîne traduisible dans .lingo/metadata.json. Si une traduction en cache existe et que le texte source n’a pas changé, la version en cache est utilisée. Si la chaîne est nouvelle ou a été modifiée, le Compiler fait appel au fournisseur de traduction configuré pour générer une traduction et met le cache à jour.
{
buildMode: "translate",
}C’est le mode par défaut. Il fonctionne aussi bien avec le pseudotraducteur (pour des pseudo-traductions instantanées) qu’avec de vrais fournisseurs LLM.
Fonctionnement du mode cache-only#
En mode cache-only, le Compiler lit les traductions exclusivement depuis .lingo/metadata.json. Aucun appel au LLM n’est effectué. Si une chaîne traduisible est absente du cache, le build échoue avec une erreur listant les chaînes manquantes.
.lingo/metadata.json doit être versionné. Les builds de production en mode cache-only dépendent de la présence de ce fichier dans le dépôt, et pas seulement de sa génération en local.
{
buildMode: "cache-only",
}Ce mode produit des builds déterministes : à code source et cache identiques, la sortie est toujours la même. Il supprime également toute dépendance à des API externes pendant les builds de production.
workflow recommandé#
Développement — pseudotraducteur
Activez le pseudotraducteur pour obtenir un retour instantané, sans appel API :
{
buildMode: "translate",
dev: {
usePseudotranslator: true,
},
}Les pseudo-traductions apparaissent sous la forme [!!! Welcome !!!], ce qui permet de repérer facilement les chaînes non traduites et de tester la mise en page avec des longueurs de texte variables.
CI — mode translate
Exécutez avec buildMode: "translate" et un vrai fournisseur LLM. La tâche CI génère les traductions pour toutes les nouvelles chaînes ou celles qui ont été modifiées, puis commit le .lingo/metadata.json mis à jour dans le dépôt.
# CI environment
LINGO_BUILD_MODE=translate npm run buildProduction — mode cache-only
Déployez avec buildMode: "cache-only" pour n’utiliser que des traductions pré-générées. Aucune clé d’API n’est nécessaire dans l’environnement de production.
# Production environment
LINGO_BUILD_MODE=cache-only npm run buildSurcharge via une variable d’environnement#
La variable d’environnement LINGO_BUILD_MODE remplace l’option de configuration buildMode. Cela vous permet d’utiliser le même fichier de configuration d’un environnement à l’autre :
# Override in any environment
LINGO_BUILD_MODE=cache-only npm run buildLa variable d’environnement est prioritaire sur la valeur définie dans le fichier de configuration.
Exemples de CI#
# .github/workflows/translate.yml
name: Generate Translations
on:
push:
branches: [main]
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run build
env:
LINGO_BUILD_MODE: translate
LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
- uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: "chore: update translations"
file_pattern: ".lingo/metadata.json"Versionnez toujours .lingo/metadata.json. Les builds de production en mode cache-only dépendent de ce fichier. S’il est absent ou incomplet, le build échouera.
