GitHub
Traduisez le contenu de votre dépôt avec la GitHub App, tout en gardant la possibilité de relire les modifications du contenu source et les traductions produites.
La GitHub App de Lingo.dev intègre les fichiers traduits à l’historique des modifications de votre dépôt. Vous committez le contenu source et une configuration de traduction ; l’application lit les fichiers sélectionnés, les traduit à l’aide d’un moteur de localisation et renvoie un diff que l’équipe peut examiner dans GitHub.
Dans le menu de navigation de Studio 2.5, ouvrez Studio 2.5 → Intégrations plutôt que Paramètres → Intégrations. Les liens de connexion et de configuration existants restent valides.
Les modifications de la branche par défaut donnent lieu à une demande de fusion contenant les traductions. Si vous activez le traitement des demandes de fusion, les traductions sont plutôt ajoutées à la branche de la demande concernée. Cette page présente d’abord le workflow de la branche par défaut et distingue la livraison des traductions de la décision de les fusionner. Pour exécuter la CLI dans votre propre environnement d’exécution, utilisez la recette GitHub Actions.
Pour permettre à votre agent de développement de se connecter à l’application, consultez Configurer avec un agent de développement.
Connecter le dépôt et la configuration de traduction #
Dans Lingo.dev, ouvrez Paramètres → Intégrations et sélectionnez Connecter pour GitHub. Reliez l’installation de l’application à votre organisation et accordez-lui l’accès aux dépôts à traiter. L’approbation d’une personne administrant l’organisation GitHub peut être nécessaire ; l’accès aux dépôts dépend du périmètre choisi pour l’installation.
Choisissez un moteur de localisation accessible dans l’organisation connectée. Sa configuration définit les modèles, le glossaire, les règles, le ton et les modalités de relecture applicables. Les autorisations de l’installation GitHub permettent les opérations sur le dépôt ; les autorisations Lingo.dev permettent l’utilisation du moteur de localisation.
Ouvrez la connexion dans Paramètres → Intégrations pour examiner son installation et vérifier son état. Gérer sur GitHub ouvre les paramètres d’accès aux dépôts de l’installation. Dans Studio, sélectionnez un dépôt sous Connectés, puis consultez Exécutions de workflow, le contrôle GitHub et les commits pour suivre une modification précise du contenu source.
Si Studio 2.5 est activé pour votre organisation, sa barre latérale Contenu source répertorie 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 sources JSON et JSONC configurés ainsi que leurs traductions existantes, sans nouveau commit ni exécution de traduction. La consultation ne consomme pas de crédits de traduction et n’active pas la synchronisation automatique. Les dépôts sans configuration valide restent visibles ; l’ouverture de leurs fichiers signale l’erreur de configuration.
Créez .lingo/config.json à la racine du dépôt. Cet exemple sélectionne les catalogues JSON en anglais sous locales/en/ et génère les fichiers en français aux chemins locales/fr/ correspondants. Remplacez eng_example par l’identifiant de votre moteur de localisation :
{
"engineId": "eng_example",
"sourceLocale": "en",
"targetLocales": ["fr"],
"files": [
{
"pattern": "locales/en/**/*.json",
"format": "json"
}
],
"github": {
"workflows": {
"onPushToDefaultBranch": { "enabled": true },
"onPullRequest": { "enabled": false }
},
"safety": { "requireApproval": true }
}
}Mener une exécution à terme et en vérifier le résultat #
Cet exemple nécessite une approbation avant le début de la traduction. Pour le tester :
- Committez la configuration et une petite modification du contenu source sur la branche par défaut, par exemple un message dans
locales/en/checkout.json. - Ouvrez le contrôle GitHub en attente et approuvez l’exécution. Si l’approbation n’est pas disponible, consultez les règles d’approbation.
- Ouvrez la demande de fusion contenant les traductions créée ou mise à jour par l’application. Repérez
locales/fr/checkout.jsonet comparez le message modifié au texte source. - Compilez ou exécutez l’application avec le fichier traduit. Vérifiez la formulation, les variables et la sélection de la langue, puis relisez et fusionnez la demande de fusion selon le processus habituel de votre dépôt.
L’approbation à l’étape 2 autorise le travail de traduction et la consommation associée. Elle ne valide pas la formulation obtenue et ne fusionne pas la demande de fusion. Si des résultats manquent, consultez l’inspection et la reprise pour identifier l’étape inachevée.
Adapter la configuration à l’organisation de vos fichiers #
Les motifs de sélection des sources doivent inclure uniquement des fichiers sources. Par exemple, locales/en/**/*.json exclut les fichiers français générés des recherches ultérieures de fichiers sources. Les motifs sont relatifs au dépôt ; les chemins absolus et .. sont refusés. Chaque entrée de fichier nécessite un pattern ou une liste include. Une configuration prend en charge jusqu’à 100 entrées de fichiers et 50 langues cibles distinctes.
Par défaut, la langue source présente dans un chemin détermine l’emplacement des fichiers cibles. Si les chemins ne contiennent pas de langue, définissez targetPath : [locale] fournit la langue cible et [path] fournit le chemin source après suppression du préfixe facultatif sourceRoot. Par exemple, sourceRoot: "content" et targetPath: "translations/[locale]/[path]" font correspondre content/help/start.md à translations/fr/help/start.md pour le français. Un modèle basé sur un motif glob nécessite les deux paramètres de substitution. sourceRoot nécessite targetPath et doit figurer au début des chemins sources sélectionnés. Les formats multilingues à fichier unique, comme les catalogues de chaînes Xcode et CSV, n’acceptent pas les modèles de sortie, car leurs traductions restent dans le fichier d’origine.
Utilisez localeFormat lorsque l’application exige des codes de langue au format BCP-47, avec des traits de soulignement ou au format Android dans les chemins. Les ressources Android utilisent par défaut les qualificateurs Android. Vérifiez que le premier chemin de sortie correspond au système de chargement de l’application avant d’ajouter d’autres langues.
Choisir quand lancer la traduction et où enregistrer les résultats #
Le traitement des push sur la branche par défaut est activé par défaut. Le traitement des demandes de fusion est désactivé par défaut et doit être activé explicitement dans la configuration.
Committez un .lingo/config.json valide sur la branche par défaut avant d’activer le traitement des demandes de fusion. L’application lit l’identifiant du moteur, github.workflows et github.safety dans cette révision de confiance de la branche par défaut. Modifier ces paramètres dans une demande de fusion n’autorise pas l’utilisation d’un autre moteur et ne change pas la politique d’approbation de l’exécution concernée. La langue source, la sélection des fichiers et les langues cibles proviennent de la révision à traduire.
| Déclencheur | Livraison des traductions |
|---|---|
| Push sur la branche par défaut | Crée des commits sur lingo/translations/<default-branch> et ouvre ou met à jour une demande de fusion vers la branche par défaut. |
| Workflow de demande de fusion activé | Committe les traductions produites sur la branche source de la demande de fusion. |
| Commande de traduction sur une demande de fusion | Écrit les traductions demandées sur la branche source de cette demande de fusion. |
La livraison via une demande de fusion nécessite une branche source accessible en écriture dans le dépôt où l’application est installée. L’application ignore les forks et refuse d’écrire ces résultats directement sur la branche par défaut.
L’application traite les opérations sur le dépôt de manière séquentielle et filtre les commits qu’elle génère pour éviter qu’ils déclenchent des traductions à répétition. Lorsqu’aucune source configurée n’a changé ou que les cibles couvrent déjà le travail demandé, une exécution peut se terminer sans diff. Le contrôle associé en explique le résultat ; la régénération forcée sert à remplacer les traductions sélectionnées, pas à donner l’impression qu’une exécution sans modification est active.
Exiger une approbation avant d’engager des dépenses pour une exécution #
github.safety.requireApproval vaut false par défaut. Définissez-le sur true dans la configuration de la branche par défaut si une personne doit autoriser l’exécution avant le début de la traduction. Pour les push sur la branche par défaut, le contrôle propose les boutons Approuver et Refuser. Pour les demandes de fusion, l’application publie un commentaire auquel une personne habilitée à effectuer la relecture répond avec /lingo approve.
Lorsque l’approbation est requise, l’échec de la création du contrôle d’audit bloque le workflow. Résolvez le problème de création du contrôle ou d’accès avant de tenter à nouveau l’approbation.
Toute commande /lingo translate, avec ou sans motifs glob de fichiers, autorise le travail demandé et contourne cette approbation préalable. Vérifiez le périmètre des fichiers et des langues avant de la publier.
Exécuter des commandes sur une demande de fusion #
Publiez un commentaire sur une demande de fusion ouverte dont la branche appartient au dépôt où l’application est installée et n’est pas la branche par défaut. L’application lit la première ligne du commentaire qui commence par /lingo. Elle utilise la langue source, les options de fichiers et les langues cibles définies dans la configuration de la branche source de la demande de fusion, ainsi que le moteur et les paramètres de sécurité de la branche par défaut. Seule une personne disposant d’un accès en écriture au dépôt peut lancer la traduction.
| Commande | Effet |
|---|---|
/lingo ou /lingo help | Répond en affichant la liste des commandes. |
/lingo translate | Traduit les modifications du contenu source de cette demande de fusion et conserve les traductions inchangées. Remplace la proposition de traduction encore en attente depuis le dernier push. |
/lingo translate --locales fr,es | Traduit les modifications du contenu source de cette demande de fusion uniquement pour les langues indiquées. |
/lingo translate <glob>... | Crée les fichiers cibles manquants pour les sources configurées qui correspondent aux motifs glob. |
/lingo translate <glob>... --force | Régénère les cibles correspondantes en remplaçant les traductions existantes. --force nécessite au moins un motif glob. |
/lingo translate [<glob>...] --key <pattern> | Retraduit les clés nommées correspondantes dans les traductions existantes. |
/lingo approve | Approuve la proposition de traduction en attente sur cette demande de fusion. |
Sans motifs glob ni --key, une commande s’appuie sur les fichiers modifiés par la demande de fusion ; elle s’exécute donc même si le traitement des demandes de fusion est désactivé dans la configuration. Avec des motifs glob, elle s’appuie sur les fichiers de la branche, indépendamment des modifications de la demande de fusion. Les motifs glob sont relatifs à la racine du dépôt, respectent la casse et ne ciblent que les fichiers sélectionnés par un pattern configuré. --locales accepte une liste séparée par des virgules. Les codes sont comparés aux langues cibles configurées sans distinction de casse, et la réponse signale tout code qui ne correspond à aucune d’elles.
Remplissage rétroactif d’un fichier ou d’une langue sélectionnés et Retraduire des clés avec du contexte détaillent les syntaxes utilisant des motifs glob et des clés.
Remplissage rétroactif d’un fichier ou d’une langue sélectionnés #
Publiez une commande ciblée sur une demande de fusion pour demander la traduction d’un fichier configuré dans une langue donnée :
/lingo translate locales/en/checkout.json --locales frPour les formats utilisant un fichier distinct par langue, cette commande crée le fichier cible français s’il manque. Elle ne complète pas les clés manquantes dans un fichier cible existant. L’ajout de --force régénère la sortie sélectionnée sans réutiliser la cible existante et peut donc remplacer des modifications humaines acceptées. Limitez la sélection de fichiers et de langues, puis relisez le diff obtenu.
Les catalogues de chaînes Xcode et les fichiers CSV conservent le contenu source et cible dans un même fichier. Une commande simple exécutée sur un périmètre défini complète les entrées manquantes pour chaque langue et conserve les entrées existantes, même celles dont le contenu source a changé. Utilisez /lingo translate sans motif de fichier pour traduire les modifications du contenu source dans la demande de fusion ; cette opération peut remplacer les traductions existantes des entrées concernées, y compris les retouches humaines. Ajoutez --force avec une sélection restreinte de fichiers et de langues si vous souhaitez régénérer les traductions existantes. Une commande forcée de l’application reconstruit le contenu sélectionné tout en conservant les langues hors du périmètre demandé. Pour les mises à jour via la CLI, suivez la procédure de correction des catalogues de chaînes ou des fichiers CSV.
Retraduire des clés avec du contexte #
Utilisez --key pour retraduire une sélection de clés nommées dans les traductions existantes. Pour les fichiers JSON et JSONC, ajoutez --context afin d’expliquer leur sens ou de fournir des consignes sur le ton et la casse pour cette exécution :
/lingo translate --key "keyname" --context "button label, keep sentence case"--context nécessite --key. Fournissez le contexte une seule fois ; il s’applique à chaque clé et à chaque langue sélectionnées dans les fichiers JSON et JSONC. Les autres formats correspondants sont traduits sans ce contexte. Répétez --key pour utiliser plusieurs motifs et ajoutez des motifs glob de fichiers ou --locales pour restreindre la demande. Sans motifs glob de fichiers, la commande sélectionne tous les fichiers sources configurés. Les clés sont sélectionnées par correspondance exacte, par préfixe ou par motif glob ; les autres traductions sont conservées. Les formats sans clés nommées et les langues sans traductions existantes sont ignorés.
Les commandes par clé de la GitHub App régénèrent aussi les chaînes sélectionnées inchangées dans les fichiers YAML et les fichiers YAML organisés par langue à la racine. Le workflow de la CLI limité aux clés applique un comportement différent pour la réutilisation des traductions de référence dans ces formats.
Gardez la commande sur une seule ligne. Encadrez le contexte contenant des espaces par des guillemets simples ou doubles ; --context="button label" fonctionne aussi. Pour inclure le même guillemet dans le texte, échappez-le avec une barre oblique inverse, par exemple --context "Use \"Save\" as a button label". Le contexte est conservé avec l’exécution pour les nouvelles tentatives et l’historique, mais il n’est pas enregistré comme consigne du moteur ni transmis aux exécutions ultérieures. Les règles existantes concernant le glossaire, les espaces réservés et le format de sortie restent applicables.
Dans un contexte entre guillemets, seuls \\ et une barre oblique inverse précédant le guillemet d’encadrement sont décodés. Les espaces réservés tels que $name et ${name}, les séquences telles que \n et la ponctuation sont conservés tels quels.
Protéger le contenu qui ne doit pas changer #
L’application prend en charge les catalogues structurés, les documents de la famille Markdown, le HTML, les sous-titres, le texte brut, les tableaux CSV, les fichiers de propriétés Java et les ressources de plateforme. La page Formats présente les différents gestionnaires. Payload ne fait pas partie des formats de fichiers que vous pouvez sélectionner pour GitHub.
Sélectionnez le HTML avec des motifs tels que pages/en/**/*.html et pages/en/**/*.htm ; les deux extensions permettent de déduire html, et un "format": "html" explicite est également accepté. La sortie HTML intègre le texte traduit et les attributs sélectionnés dans la source, tout en conservant le balisage, les commentaires et la mise en forme non modifiés. Un élément <html> explicite reçoit la langue cible dans lang ; aucune structure de document englobante n’est ajoutée aux fragments.
Sélectionnez les fichiers texte brut à l’aide d’un motif se terminant par .txt, comme metadata/en/*.txt, ou avec "format": "txt". Un fichier .txt ne peut appartenir qu’à une entrée de ce type, et une entrée avec "format": "txt" ne sélectionne que les fichiers .txt. Ainsi, un motif général comme docs/en/**/* ignore LICENSE.txt, et une entrée txt au motif général ignore les images qui se trouvent aux côtés du texte. Texte brut traduit chaque ligne directement à son emplacement.
Sélectionnez les fichiers CSV de la même manière, avec un motif se terminant par .csv, comme i18n/strings.csv, ou avec "format": "csv". Un fichier .csv ne peut appartenir qu’à une entrée de ce type, et une entrée avec "format": "csv" ne sélectionne que des fichiers .csv. CSV remplit les colonnes des langues cibles dans le fichier source.
Sélectionnez les fichiers de propriétés Java de la même manière, à l’aide d’un motif se terminant par .properties, comme src/main/resources/messages_en.properties, ou avec "format": "properties", pour qu’un motif général comme src/main/resources/**/* exclue application.properties. Une source nommée messages_en.properties reçoit des cibles telles que messages_de.properties. Propriétés Java traduit chaque valeur à son emplacement d’origine, préserve les commentaires et la mise en page, et reconnaît lockedKeys, preservedKeys, ignoredKeys et lockedPatterns comme le faisait la version précédente de la CLI.
Pour un document, sélectionnez les champs de métadonnées d’en-tête et les propriétés de composants qui contiennent du texte à traduire. Pour un catalogue de type JSON, utilisez des chemins verrouillés pour copier les valeurs sources, des chemins préservés pour conserver les valeurs cibles existantes et des chemins ignorés pour exclure des valeurs de la sortie. Ces choix permettent de réunir du texte, des identifiants et des liens dans un même catalogue sans demander au système de traduction de les traiter tous de la même façon. L’injection de langue écrit la langue cible dans le champ de sortie configuré.
Options des entrées de fichiers #
Placez les champs suivants directement sur un objet du tableau files de .lingo/config.json, et non sous options. L’application valide strictement les champs racine, les entrées de fichiers, les paramètres GitHub, les règles de composants et les objets d’injection de langue. Elle ignore la section facultative i18n et accepte des champs supplémentaires dans cette section. Le schéma lisible par machine est disponible à l’adresse GET https://api.lingo.dev/github-app/schema.json.
| Champ | Structure acceptée | Valeur par défaut ou portée |
|---|---|---|
pattern / include | Chaîne non vide relative au dépôt / tableau non vide de telles chaînes. | Au moins l’un des deux est requis ; s’il est fourni, include est prioritaire sur pattern. Les motifs ne peuvent pas commencer par / ni contenir ... |
exclude | Tableau de motifs non vides relatifs au dépôt. | Facultatif ; s’applique à cette entrée. |
format | Chaîne désignant un format configuré, y compris "html". | Peut être déduit automatiquement ; .html et .htm sélectionnent le HTML. Payload ne peut pas être sélectionné. Il ne s’agit pas d’un objet {type,options} de document. |
localeFormat | "bcp47", "underscore" ou "android". | BCP-47 par défaut en règle générale ; le format Android utilise la notation Android. |
targetPath, sourceRoot | Chaînes non vides relatives au dépôt. | Facultatifs ; doivent respecter les règles des modèles de sortie ci-dessus. |
lockedKeys, preservedKeys, ignoredKeys | Tableaux de chaînes non vides représentant des chemins de clés en notation pointée ou entre crochets. | L’absence équivaut à [] ; les effets dépendent du gestionnaire de format. Il ne s’agit pas d’options JSONPath brutes de document. |
injectLocale | Booléen ou { "enabled": boolean, "key"?: nonempty string }. | L’absence désactive l’injection ; si elle est activée, l’injection utilise language par défaut lorsque key est absent. |
translateFrontmatterFields | Tableau de chaînes non vides. | Pour les documents de la famille Markdown, l’absence sélectionne title, description ; [] n’en sélectionne aucun. |
translateComponentProps | Tableau de noms de propriétés sous forme de chaînes non vides ou d’objets avec component facultatif et un tableau props non vide obligatoire. | component est une chaîne non vide ou un tableau non vide de chaînes non vides ; son absence supprime le filtre sur les noms. Le champ vaut [] par défaut. |
Par exemple, une entrée JSON peut inclure "lockedKeys": ["meta.id"], "preservedKeys": ["links.help"], "injectLocale": { "enabled": true, "key": "meta.locale" } en plus de son pattern. Une entrée Markdoc peut sélectionner le titre d’un composant avec "translateComponentProps": [{ "component": "Callout", "props": ["title"] }]. La CLI accepte certaines valeurs vides et émet des avertissements pour certains champs inconnus que l’application refuse ; vérifiez la conformité de la configuration de l’application à ce schéma.
Inspecter la première exécution récurrente et reprendre son traitement #
Utilisez le contrôle GitHub et Exécutions de workflow pour retrouver le dépôt, la révision source, le moteur de localisation, les fichiers sélectionnés, les langues et la branche de livraison. Comparez ces éléments à la modification attendue, puis identifiez où le traitement s’est arrêté :
| Observation | Points à vérifier avant de demander davantage de travail |
|---|---|
| La configuration de la branche par défaut est absente, invalide ou désactive le workflow | Aucun contrôle GitHub ni commentaire n’est publié. Corrigez et committez le .lingo/config.json de la branche par défaut, avec les paramètres de workflow souhaités. |
| La configuration de la révision source est absente ou invalide, alors que les contrôles de la branche par défaut ont réussi | L’exécution signale l’échec du contrôle et publie un commentaire si le workflow de demande de fusion concerné le prévoit. Corrigez l’erreur signalée dans la configuration source. |
| Aucune modification source correspondante ou traductions déjà présentes | Examinez les motifs et la couverture sélectionnée ; une opération sans modification n’est pas un échec de traduction. |
| Une modification du contenu source de la PR a été manquée précédemment | Lors de la synchronisation de la PR, le workflow peut comparer les sources à la base de la PR pour récupérer le travail manqué lors de la comparaison avec la version source immédiatement précédente. Examinez ensemble la source de base, la source actuelle et la cible. |
| Une personne a modifié la cible de la PR | Pour les formats utilisant des fichiers cibles distincts, le traitement habituel des différences de la PR protège une cible modifiée par rapport à la base si l’auteur de son dernier commit n’est pas le bot. Examinez cette modification plutôt que de considérer la sortie ignorée comme du travail manquant. |
| Des commits ont été créés avant un échec ultérieur | Les résultats peuvent être committés par lots. Plusieurs commits peuvent correspondre à une seule exécution, et l’échec d’un lot ultérieur n’annule pas les commits précédents réussis. Examinez séparément les chemins livrés et les échecs restants. |
Les résultats sont regroupés en commits, avec une limite de 100 fichiers et un seuil de regroupement de 5 Mio. Un échec ultérieur peut laisser les commits précédents en place. Examinez les chemins livrés et les échecs restants avant de réessayer ou d’annuler les modifications de l’exécution.
Désactivez les déclencheurs concernés pour arrêter le travail récurrent. Révoquez l’accès au dépôt ou désinstallez l’application dans GitHub lorsqu’elle ne doit plus être autorisée à agir sur le dépôt. Les commits existants, les demandes de fusion acceptées et la consommation passée sont conservés ; gardez ou annulez le contenu livré selon le processus habituel de votre dépôt.
Collecter l’activité dans Radar #
La connexion transmet également à Radar l’activité des commits GitHub. Collecter des traductions pour la mesure décrit la configuration des événements et explique comment importer l’historique du fournisseur avant d’exécuter une mesure historique.