App GitHub

L’app GitHub de Lingo.dev met en place une localisation continue pour un dépôt à l’aide de .lingo/config.json.

Prérequis#

Avant d’installer l’app, assurez-vous d’avoir :

• Une organisation Lingo.dev avec la fonctionnalité d’intégration GitHub activée
• Un moteur de localisation dans cette organisation
• Un accès administrateur à l’organisation ou au dépôt GitHub que vous souhaitez connecter

Connecter l’app GitHub#

1. Dans Lingo.dev, ouvrez votre organisation.
2. Accédez à Settings.
3. Repérez GitHub (App) dans la section des intégrations.
4. Sur la ligne GitHub (App), cliquez sur Connect.
5. Dans GitHub, choisissez le compte ou l’organisation où installer l’app.
6. Choisissez All repositories ou Only select repositories.
7. Cliquez sur Install.

Après l’installation, Lingo.dev affiche le compte GitHub connecté et les dépôts dans Settings > GitHub (App). Utilisez Manage repositories on GitHub depuis la même carte de paramètres si vous devez ajouter ou supprimer des dépôts par la suite.

Si votre demande d’installation est en attente d’approbation, un administrateur GitHub peut l’examiner dans GitHub, dans la section Settings > GitHub Apps de l’organisation. GitHub affiche également les demandes d’app en attente aux propriétaires de l’organisation dans les paramètres de celle-ci.

Ajouter la configuration du dépôt#

Créez .lingo/config.json dans le dépôt sur lequel vous avez installé l’app :

{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de"],
  "files": [
    { "pattern": "docs/en/**/*.md" },
    { "pattern": "docs/en/**/*.mdx" },
    { "pattern": "locales/en.json" }
  ],
  "github": {
    "workflows": {
      "onPushToDefaultBranch": { "enabled": true },
      "onPullRequest": { "enabled": true }
    },
    "safety": {
      "requireApproval": false
    }
  }
}

Motifs de fichiers#

Les motifs files pointent vers les fichiers source (langue par défaut). L’app compare les fichiers modifiés à ces motifs et ne traite que les fichiers source pris en charge qui correspondent.

Les motifs sont relatifs au dépôt, sensibles à la casse, et peuvent utiliser :

• * pour correspondre à l’intérieur d’un segment de chemin
• **/ pour correspondre à n’importe quelle profondeur de répertoire

Les motifs ne peuvent pas commencer par / et ne peuvent pas contenir ...

{
  "files": [
    { "pattern": "docs/en/**/*.md" },
    { "pattern": "src/content/en/**/*.mdx" },
    { "pattern": "messages/en.jsonc" }
  ]
}

Options de fichier#

Chaque entrée de files peut inclure des options en plus de son pattern. Elles sont toutes facultatives et chacune ne s’applique qu’à certains formats.

Les entrées translateComponentProps sont soit un nom de prop, qui s’applique à cette prop sur n’importe quel composant ou balise, soit un objet qui limite ces props à des composants ou balises nommés :

{
  "files": [
    {
      "pattern": "src/content/en/**/*.mdx",
      "translateFrontmatterFields": ["title", "description"],
      "translateComponentProps": [
        "alt",
        { "component": ["Callout", "Hero"], "props": ["title", "subtitle"] }
      ]
    },
    {
      "pattern": "locales/en.json",
      "lockedKeys": ["app.version"],
      "injectLocale": { "enabled": true, "key": "language" }
    }
  ]
}

Où les fichiers localisés sont écrits#

L’app déduit chaque chemin cible à partir du chemin source et des codes de langue définis dans votre configuration :

Utilisez le nom complet du répertoire ou du fichier comme code de langue. Par exemple, si les fichiers source se trouvent dans docs/en-US/, définissez "sourceLocale": "en-US", et non "en". Si les chaînes source se trouvent dans messages/en.json, définissez "sourceLocale": "en".

Lorsque le chemin source contient un répertoire de langue, l’app remplace ce répertoire. Lorsque le chemin source est un fichier nommé d’après une langue, l’app remplace le nom du fichier. Si aucun de ces deux cas ne s’applique, l’app place le fichier traduit dans un nouveau répertoire de langue cible à côté du fichier source.

Workflows#

Push sur la branche par défaut#

Lorsqu’un fichier source correspondant est ajouté ou modifié sur la branche par défaut, l’app le traduit et commit les fichiers localisés dans :

lingo/translations/<default-branch>

Elle ouvre ensuite une pull request, ou met à jour une pull request existante, depuis cette branche de traductions vers la branche par défaut. Si la branche de traductions existe déjà, les nouveaux commits y sont ajoutés.

Si un fichier cible est ajouté ou modifié dans le même push, l’app considère qu’il a déjà été traité et l’inclut dans la PR de traduction au lieu de l’écraser.

Pull requests#

Lorsque github.workflows.onPullRequest.enabled vaut true, l’app vérifie les modifications de la pull request pour repérer les fichiers source correspondants. Elle commit les fichiers traduits directement sur la branche de la PR.

L’app n’écrit pas sur les branches de PR forkées et n’écrit pas sur la branche par défaut à partir d’un commentaire de PR. Les pull requests doivent être ouvertes pour que l’app puisse y commit des traductions.

Sur les PR, Lingo.dev met à jour un commentaire avec les fichiers traduits et les éventuels échecs.

Mises à jour incrémentielles et récupération#

Pour les fichiers cibles existants, l’app traduit uniquement les modifications source qu’elle détecte au lieu de régénérer tout le fichier. Pour les nouveaux fichiers cibles, elle crée le fichier localisé pour chaque langue cible configurée.

Si une précédente localisation de PR a manqué une modification source ou a échoué avant de mettre à jour le fichier cible, la synchronisation suivante de la PR peut corriger le tir en comparant la source de la PR à celle de la branche de base et en traduisant la modification manquante.

Si un fichier source n’existe plus au commit en cours de traitement, l’app l’ignore.

Mode approbation#

Définissez github.safety.requireApproval sur true si vous voulez ajouter une étape d’approbation humaine avant le lancement des traductions automatiques.

Lors des pushes sur la branche par défaut, le check run Lingo.dev affiche les actions Approve et Deny. Sur les pull requests, l’app publie un commentaire de proposition de traduction ; répondez avec :

/lingo approve

Les commandes /lingo translate limitées à un périmètre donné ne nécessitent pas cette étape d’approbation.

Commande PR manuelle#

Utilisez /lingo dans un commentaire de pull request pour compléter ou forcer les traductions de fichiers spécifiques.

/lingo translate docs/en/**/*.md

/lingo translate docs/en/**/*.mdx --locales fr,es

/lingo translate docs/en/**/*.md --force

Référence des commandes :

La commande doit figurer seule sur sa ligne. Les globs sont comparés aux fichiers qui correspondent aussi à vos motifs source files configurés. Comme les motifs de configuration, les globs de commande ne peuvent pas commencer par / et ne peuvent pas contenir ...

Par défaut, /lingo translate s’exécute en mode backfill : il crée uniquement les fichiers cibles manquants sur la branche de PR. Ajoutez --force si vous souhaitez régénérer les fichiers cibles existants.

Formats pris en charge#

L’app GitHub détecte ces formats à partir de l’extension du fichier :

• JSON (.json)
• JSONC (.jsonc)
• Markdown (.md)
• MDX (.mdx)
• Markdoc

Les documents OpenAPI rédigés en YAML sont également pris en charge, mais ne sont pas détectés automatiquement. Définissez "format": "yaml-openapi" sur le motif de fichier :

{
  "files": [
    { "pattern": "openapi/en.yaml", "format": "yaml-openapi" }
  ]
}

Mises à jour volumineuses#

L’app peut répartir la sortie de traduction sur plusieurs commits. Cela se produit lorsqu’une exécution écrirait plus de 100 fichiers dans un seul commit ou plus de 5 Mo de contenu traduit dans un seul commit.

Dans ce cas, les messages de commit incluent le numéro du lot, par exemple :

feat: Lingo.dev translations (1/3)
feat: Lingo.dev translations (2/3)
feat: Lingo.dev translations (3/3)

Que se passe-t-il si rien ne correspond#

Si .lingo/config.json est absent, l’app ignore le dépôt sans rien signaler. Une fois la configuration en place, une configuration invalide génère un check run en échec et, sur les PR, un commentaire avec l’erreur de validation.

Si aucun fichier modifié ne correspond à vos motifs source, l’app termine sans écrire de traductions. Pour /lingo translate, le bot répond par une courte explication, par exemple : aucun fichier correspondant, aucune langue correspondante ou tous les fichiers cibles existent déjà.

Étapes suivantes#