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.
Pour que votre agent de programmation puisse se connecter à l’application, consultez Configuration avec un agent de programmation.
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
Si vous n’êtes pas administrateur de l’organisation GitHub, vous pouvez demander l’installation via GitHub. Un administrateur de l’organisation GitHub devra approuver cette demande avant que Lingo.dev puisse accéder aux dépôts sélectionnés.
Installer l'application GitHub#
- Dans Lingo.dev, ouvrez votre organisation.
- Accédez à Studio > All integrations.
- Sur la carte GitHub, cliquez sur Install on GitHub.
- Dans GitHub, choisissez le compte ou l’organisation où installer l’app.
- Choisissez All repositories ou Only select repositories.
- Cliquez sur Install.
GitHub vous redirige vers Lingo.dev sur l’écran Connect GitHub :
- Choisissez l’organisation Lingo.dev via laquelle ce compte GitHub gère la localisation. La dernière organisation que vous avez ouverte est sélectionnée automatiquement.
- Cliquez sur Connecter.
- Lorsque GitHub connected s’affiche, cliquez sur View integration pour ouvrir la connexion.
La connexion apparaît dans la barre latérale de Studio, sous Connected. Son onglet Paramètres affiche le Compte, le Type de compte, l’Installation, les Dépôts et indique si la Connexion fonctionne. Son onglet Exécutions de workflow répertorie chaque exécution lancée par l’application, y compris le dépôt concerné et si elle a été déclenchée par un push ou une pull request.
Pour ajouter ou retirer des dépôts plus tard, ouvrez l’onglet Paramètres de la connexion et utilisez Manage on GitHub : l’accès aux dépôts se configure toujours sur GitHub, directement au niveau de l’installation.
Si vous avez demandé l’installation au lieu de l’installer, Lingo.dev affiche Installation requested : un administrateur de l’organisation GitHub doit l’approuver. Une fois l’approbation donnée, GitHub vous renvoie vers l’écran Connect GitHub pour finaliser la configuration. L’administrateur peut examiner la demande dans GitHub, dans la section Paramètres > GitHub Apps de l’organisation. GitHub affiche aussi les demandes d’application en attente aux propriétaires de l’organisation dans les paramètres de l’organisation.
Si Studio 2.5 est activé pour votre organisation, sa barre latérale Contenu source affiche les dépôts accessibles à votre installation connectée, sans attendre un événement GitHub. Avec un .lingo/config.json valide sur la branche par défaut, vous pouvez ouvrir les fichiers source JSON et JSONC configurés ainsi que leurs traductions existantes, sans nouveau commit ni nouvelle exécution de traduction. La consultation ne consomme aucun crédit de traduction et n’active pas la synchronisation automatique. Les dépôts sans configuration valide restent visibles ; une erreur de configuration est signalée à l’ouverture de leurs fichiers.
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
}
}
}| Champ | Obligatoire | Description |
|---|---|---|
engineId | Oui | Le moteur Lingo.dev qui doit traduire ce dépôt. |
sourceLocale | Oui | La langue source utilisée dans les chemins de vos fichiers source, comme en ou en-US. |
targetLocales | Oui | Les codes de langue à traduire. Jusqu’à 50 langues distinctes sont prises en charge. |
files | Oui | Motifs de fichiers source relatifs au dépôt. Jusqu’à 100 motifs sont pris en charge. |
github.workflows.onPushToDefaultBranch.enabled | Non | S’exécute lorsque les fichiers source changent sur la branche par défaut. Activé par défaut. |
github.workflows.onPullRequest.enabled | Non | S’exécute lorsque les fichiers source changent dans les pull requests. Désactivé par défaut. |
github.safety.requireApproval | Non | Nécessite une approbation avant que les workflows automatiques sur push ou PR n’exécutent les traductions. Désactivé par défaut. |
Utilisez la CLI pour créer la configuration du dépôt. Exécutez les commandes suivantes dans cet ordre :
- Exécutez
npx @lingo.dev/cli initpour enregistrer la langue source, les langues cibles et les motifs de fichiers dans.lingo/config.json. - Exécutez
npx @lingo.dev/cli loginpour vous connecter et enregistrer vos identifiants localement dans~/.lingo/credentials.json. - Exécutez
npx @lingo.dev/cli linkpour choisir une organisation et un moteur. Cette commande ajouteorgIdetengineIdà.lingo/config.json.
La commande init ne crée pas la section github. Si vous en avez besoin, copiez-la à partir de l’exemple ci-dessus. Consultez le guide de démarrage rapide de la CLI.
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.
| Option | S’applique à | Description |
|---|---|---|
format | Tous | Remplace le format déduit de l’extension du fichier. Obligatoire pour OpenAPI YAML ("yaml-openapi"). |
include / exclude | Tous | Listes de globs permettant d’affiner les fichiers auxquels l’entrée correspond, à utiliser avec pattern ou à sa place. |
translateFrontmatterFields | Markdown, MDX, Markdoc | Clés de frontmatter à traduire. Par défaut : title et description. |
translateComponentProps | MDX, Markdoc | Props de composants MDX et attributs de balises Markdoc à traduire. |
lockedKeys | JSON, JSONC | Chemins de clés conservés avec la valeur source, jamais traduits. |
preservedKeys | JSON, JSONC | Chemins de clés conservés avec la valeur cible existante, sans retraduction. |
injectLocale | JSON, JSONC | Écrit le code de langue cible dans la sortie à la clé indiquée (par défaut language). |
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 :
| Chemin source | Langue cible | Chemin de sortie |
|---|---|---|
docs/en/guide.md | es | docs/es/guide.md |
docs/en-US/guide.md | fr-FR | docs/fr-FR/guide.md |
locales/en.json | de | locales/de.json |
README.md | es | es/README.md |
Localizable.xcstrings | es-MX | Localizable.xcstrings (même fichier) |
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.
Les catalogues de chaînes font exception. Comme un seul fichier .xcstrings regroupe toutes les langues, le chemin cible est identique au chemin source : l’application écrit chaque langue dans ce même fichier, sans jamais ajouter de répertoire de langue ni de nom de fichier.
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 approveLes 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 traduire les modifications du contenu source, créer les fichiers cibles manquants par remplissage rétroactif ou retraduire les clés sélectionnées.
Traduisez les modifications du contenu source dans la pull request tout en conservant les traductions inchangées :
/lingo translatePour créer les fichiers cibles manquants par remplissage rétroactif, indiquez des motifs de fichiers avec jokers :
/lingo translate docs/en/**/*.md/lingo translate docs/en/**/*.mdx --locales fr,es/lingo translate docs/en/**/*.md --forceRéférence des commandes :
| Commande | Description |
|---|---|
/lingo | Affiche l’aide. |
/lingo help | Affiche l’aide. |
/lingo translate | Traduit les modifications du contenu source dans cette PR tout en conservant les traductions inchangées. |
/lingo translate --locales fr,es | Traduit les modifications du contenu source de cette PR pour les langues cibles sélectionnées parmi celles qui sont configurées. |
/lingo translate <glob>... | Traduit les fichiers cibles manquants pour les fichiers source correspondants. |
/lingo translate <glob>... --locales fr,es | Limite l’exécution aux langues cibles configurées. Les valeurs de langue sont converties en minuscules par l’analyseur de commandes. |
/lingo translate <glob>... --force | Traduit chaque source et chaque langue correspondante dans le périmètre défini, en écrasant les cibles existantes. |
/lingo translate [<glob>...] --key <pattern> | Retraduit les clés nommées qui correspondent aux motifs dans les traductions existantes, tout en conservant les traductions non concernées. Répétez --key pour utiliser plusieurs motifs. |
/lingo translate [<glob>...] --key <pattern> --context "text" | Ajoute des consignes pour toutes les clés et langues sélectionnées, uniquement pour cette exécution. Nécessite --key ; indiquez --context une seule fois. |
/lingo approve | Approuve une proposition de traduction en attente sur la PR. |
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 ...
Avec des motifs de fichiers avec jokers explicites et sans --key, /lingo translate <glob>... s’exécute en mode remplissage rétroactif : il crée uniquement les fichiers cibles manquants sur la branche de la PR. Ajoutez --force pour régénérer ces fichiers cibles lorsqu’ils existent déjà.
Retraduire les clés sélectionnées#
Utilisez --key pour mettre à jour les clés nommées sélectionnées sans remplacer les traductions non concernées, y compris les modifications acceptées sur d’autres clés :
/lingo translate locales/en.json --key "auth.login" --locales fr,esLes motifs de clés prennent en charge les correspondances exactes, les préfixes et les jokers :
| Motif | Sélection |
|---|---|
auth.login | Sélectionne la clé nommée auth.login et toutes les clés descendantes sous ce préfixe. |
auth | Sélectionne auth et les clés descendantes telles que auth.login et auth.logout. |
auth.* | Sélectionne les clés correspondant à un motif avec jokers, par exemple auth.login et auth.logout. |
Répétez --key pour sélectionner plusieurs motifs. Placez entre guillemets les motifs de clés contenant des espaces. Les motifs de fichiers avec jokers et --locales restreignent la portée de la demande ; sans motifs de fichiers, tous les fichiers sources configurés sont sélectionnés :
/lingo translate --key "auth.*" --key "checkout.submit" --locales frLa traduction ciblée par clé nécessite un format avec des clés nommées et une traduction existante pour chaque langue cible sélectionnée. Les formats sans clés nommées et les langues sans traduction existante sont ignorés. Pour créer d’abord les fichiers cibles manquants, exécutez /lingo translate <glob>... sans --key. L’ajout de --force à une commande ciblée par clé n’élargit pas la sélection de clés et ne remplace pas les traductions non concernées.
Donner à une exécution son propre contexte#
Ajoutez --context pour expliquer le sens d’une clé sélectionnée ou donner des consignes sur le ton et l’emploi des majuscules et des minuscules :
/lingo translate --key "keyname" --context "button label, keep sentence case"--context nécessite --key. Indiquez le contexte une seule fois ; il s’applique à toutes les clés et langues sélectionnées pour cette exécution. Il est conservé avec l’exécution pour les nouvelles tentatives et l’historique, mais ne modifie pas les règles ou les instructions enregistrées du moteur et n’est pas repris par les exécutions suivantes. Les règles existantes concernant le glossaire, les paramètres de substitution et le format de sortie continuent de s’appliquer.
Gardez la commande sur une seule ligne. Encadrez tout contexte contenant des espaces avec des guillemets simples ou doubles ; --context="button label" fonctionne également. Pour inclure dans le texte le guillemet utilisé comme délimiteur, faites-le précéder d’une barre oblique inverse :
/lingo translate --key "checkout.submit" --context "Use \"Save\" as a button label"Dans un contexte entre guillemets, seuls \\ et une barre oblique inverse précédant le guillemet utilisé comme délimiteur sont décodés. Les paramètres de substitution tels que $name et ${name}, les séquences telles que \n et la ponctuation restent inchangés.
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
- Catalogue de chaînes Xcode (
.xcstrings)
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" }
]
}Catalogues de chaînes Xcode#
Un catalogue de chaînes Xcode regroupe toutes les langues dans un seul fichier .xcstrings. L’application le traduit donc directement dans ce fichier, au lieu de créer un fichier par langue. Le chemin cible est identique au chemin source : chaque langue cible est écrite dans le même fichier, aux côtés de la langue source et de toutes les langues déjà traduites. Faites pointer le modèle source directement vers le catalogue et définissez sourceLocale sur sa langue de développement :
{
"sourceLocale": "en",
"targetLocales": ["es-MX", "fr-CA", "pt-BR"],
"files": [{ "pattern": "**/*.xcstrings" }]
}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à.
Le push qui ajoute .lingo/config.json traduit uniquement les fichiers sources qui correspondent aux motifs définis et qui ont été modifiés dans ce push. Les fichiers sources existants qui restent inchangés nécessitent un remplissage rétroactif distinct. Pour créer les fichiers cibles manquants, ouvrez une demande de fusion depuis une branche du même dépôt, et non depuis un fork. Ajoutez le commentaire /lingo translate <glob> à la demande de fusion.