GitHub
Traduce el contenido del repositorio con la GitHub App y conserva la posibilidad de revisar tanto los cambios de origen como las traducciones.
La GitHub App de Lingo.dev incorpora los archivos traducidos al historial de cambios de tu repositorio. Guarda el contenido de origen y la configuración de traducción en un commit; la aplicación lee los archivos seleccionados, los traduce mediante un motor de localización y devuelve una comparación de cambios que el equipo puede revisar en GitHub.
En el menú de navegación de Studio 2.5, abre Studio 2.5 → Integraciones en lugar de Configuración → Integraciones. Los enlaces de conexión y configuración que ya tenías siguen funcionando.
Los cambios en la rama predeterminada generan una solicitud de incorporación con las traducciones. Si habilitas el procesamiento de solicitudes de incorporación, las traducciones se añaden a la rama de esa solicitud. Esta página empieza por el flujo de trabajo de la rama predeterminada y distingue entre la entrega de traducciones y la decisión de fusionarlas. Para ejecutar la CLI en tu propio ejecutor, utiliza la guía de GitHub Actions.
Para que tu agente de programación pueda conectarse a la aplicación, consulta Configuración con un agente de programación.
Conecta el repositorio y la configuración de traducción #
En Lingo.dev, abre Ajustes → Integraciones y selecciona Conectar para GitHub. Vincula la instalación de la aplicación a tu organización y concede acceso a los repositorios que quieras que procese. Puede que un administrador de la organización de GitHub tenga que aprobar la instalación; el acceso a los repositorios depende del alcance seleccionado para esa instalación.
Elige un motor de localización al que tengas acceso en la organización conectada. Su configuración define los modelos, el glosario, las reglas, la voz y el comportamiento de revisión aplicable. Los permisos de la instalación de GitHub autorizan el trabajo en el repositorio; los permisos de Lingo.dev autorizan el uso del motor de localización.
Abre la conexión en Ajustes → Integraciones para revisar la instalación y el estado de la conexión. Gestionar en GitHub abre los ajustes de acceso a los repositorios de la instalación. En Studio, selecciona un repositorio en Conectados y utiliza Ejecuciones del flujo de trabajo, junto con la comprobación de GitHub y los commits, para seguir un cambio concreto en el contenido de origen.
Si Studio 2.5 está habilitado para tu organización, la barra lateral Contenido de origen muestra los repositorios a los que puede acceder la instalación conectada, sin esperar a un evento de GitHub. Con un .lingo/config.json válido en la rama predeterminada, puedes abrir los archivos de origen JSON y JSONC configurados y sus traducciones existentes sin crear un nuevo commit ni ejecutar una traducción. Explorar el contenido no consume créditos de traducción ni habilita la sincronización automática. Los repositorios sin una configuración válida siguen siendo visibles; al abrir sus archivos, se muestra el error de configuración.
Crea .lingo/config.json en la raíz del repositorio. Este ejemplo selecciona catálogos JSON en inglés en locales/en/ y genera archivos en francés en las rutas locales/fr/ correspondientes. Sustituye eng_example por el ID de tu motor de localización:
{
"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 }
}
}Completa y revisa una ejecución #
El ejemplo exige aprobación antes de iniciar la traducción. Para probarlo:
- Crea un commit en la rama predeterminada con la configuración y un pequeño cambio en el contenido de origen, como un mensaje en
locales/en/checkout.json. - Abre la comprobación pendiente de GitHub y aprueba la ejecución. Si la aprobación no está disponible, consulta las reglas de aprobación.
- Abre la solicitud de incorporación de traducciones que crea o actualiza la aplicación. Busca
locales/fr/checkout.jsony compara el mensaje modificado con el original. - Compila o ejecuta la aplicación con el archivo traducido. Comprueba la redacción, las variables y la selección de idioma; después, revisa y fusiona la solicitud de incorporación siguiendo el proceso habitual de tu repositorio.
La aprobación del paso 2 autoriza el trabajo de traducción y el consumo que genera. No aprueba la redacción resultante ni fusiona la solicitud de incorporación. Si faltan resultados, consulta inspección y recuperación para identificar la fase que no se ha completado.
Adapta la configuración a la estructura de tus archivos #
Los patrones de origen deben seleccionar únicamente archivos de origen. Por ejemplo, locales/en/**/*.json excluye los archivos en francés generados de las búsquedas posteriores de archivos de origen. Los patrones son relativos al repositorio; se rechazan las rutas absolutas y ... Cada entrada de archivo requiere un pattern o una lista include. Una configuración admite hasta 100 entradas de archivos y 50 idiomas de destino distintos.
Por defecto, el idioma de origen indicado en una ruta determina dónde se guardan los archivos de destino. Si las rutas no contienen un idioma, configura targetPath: [locale] proporciona el idioma de destino y [path] proporciona la ruta de origen tras eliminar el prefijo opcional sourceRoot. Por ejemplo, sourceRoot: "content" y targetPath: "translations/[locale]/[path]" asignan content/help/start.md a translations/fr/help/start.md para el francés. Una plantilla basada en patrones glob necesita ambos marcadores de posición. sourceRoot requiere targetPath y debe figurar como prefijo de las rutas de origen seleccionadas. Los formatos que reúnen varios idiomas en un único archivo, como los catálogos de cadenas de Xcode y CSV, no admiten plantillas de salida porque las traducciones se guardan en el archivo original.
Utiliza localeFormat cuando la aplicación necesite códigos de idioma BCP-47, separados por guiones bajos o con la notación de Android en las rutas. Los recursos de Android utilizan los calificadores de Android de forma predeterminada. Comprueba que la primera ruta de salida sea compatible con el cargador de la aplicación antes de añadir más idiomas.
Elige cuándo se ejecuta la traducción y dónde se guarda #
El procesamiento de los envíos a la rama predeterminada está habilitado por defecto. El procesamiento de solicitudes de incorporación está deshabilitado por defecto y debe habilitarse explícitamente en la configuración.
Guarda un .lingo/config.json válido en un commit de la rama predeterminada antes de habilitar el trabajo en solicitudes de incorporación. La aplicación lee el ID del motor, github.workflows y github.safety de esa revisión de confianza de la rama predeterminada. Los cambios en esos ajustes dentro de una solicitud de incorporación no autorizan un motor distinto ni modifican la política de aprobación de su propia ejecución. El idioma de origen, la selección de archivos y los idiomas de destino proceden de la revisión que se está traduciendo.
| Desencadenante | Entrega de traducciones |
|---|---|
| Envío a la rama predeterminada | Crea commits en lingo/translations/<default-branch> y abre o actualiza una solicitud de incorporación a la rama predeterminada. |
| Flujo de trabajo de solicitudes de incorporación habilitado | Guarda las traducciones generadas en commits en la rama de origen de la solicitud de incorporación. |
| Comando de traducción en una solicitud de incorporación | Escribe las traducciones solicitadas en la rama de origen de esa solicitud de incorporación. |
La entrega en solicitudes de incorporación requiere una rama de origen con acceso de escritura en el repositorio de la instalación. La aplicación omite las bifurcaciones y no permite escribir estos resultados directamente en la rama predeterminada.
La aplicación procesa el trabajo del repositorio de forma secuencial y filtra los commits que genera para evitar que activen la traducción repetidamente. Si no ha cambiado ningún archivo de origen configurado o los destinos ya cubren el trabajo solicitado, una ejecución puede terminar sin diferencias. La comprobación explica el resultado; la regeneración forzada sirve para sustituir las traducciones seleccionadas, no para hacer que una ejecución sin cambios parezca activa.
Exige aprobación antes de generar gastos en una ejecución #
github.safety.requireApproval tiene el valor predeterminado false. Establécelo en true en la configuración de la rama predeterminada cuando alguien deba autorizar una ejecución antes de que empiece la traducción. Los envíos a la rama predeterminada muestran los controles Aprobar y Denegar en la comprobación. En las solicitudes de incorporación, la aplicación publica un comentario y una persona autorizada para la revisión responde con /lingo approve.
Cuando se exige aprobación, un fallo al crear la comprobación de auditoría bloquea el flujo de trabajo. Resuelve el problema de creación de la comprobación o de acceso antes de volver a intentar la aprobación.
Cualquier comando /lingo translate, con o sin patrones glob de archivos, autoriza el trabajo que solicita y omite esta aprobación previa. Comprueba los archivos y los idiomas que abarca antes de publicarlo.
Ejecuta comandos en una solicitud de incorporación #
Publica un comentario en una solicitud de incorporación abierta cuya rama pertenezca al repositorio de la instalación y no sea la rama predeterminada. La aplicación lee la primera línea del comentario que empieza por /lingo. Utiliza el idioma de origen, las opciones de archivos y los idiomas de destino de la configuración de la rama de origen de la solicitud de incorporación, junto con el motor y los ajustes de seguridad de la rama predeterminada. Solo quien tenga acceso de escritura al repositorio puede iniciar la traducción.
| Comando | Efecto |
|---|---|
/lingo o /lingo help | Responde con la lista de comandos. |
/lingo translate | Traduce los cambios en el contenido de origen de esta solicitud de incorporación y conserva las traducciones sin cambios. Sustituye la propuesta de traducción que siga pendiente desde el último envío. |
/lingo translate --locales fr,es | Traduce los cambios en el contenido de origen de esta solicitud de incorporación solo para los idiomas indicados. |
/lingo translate <glob>... | Crea los archivos de destino que faltan para los archivos de origen configurados que coinciden con los patrones glob. |
/lingo translate <glob>... --force | Regenera los destinos coincidentes y sustituye las traducciones existentes. --force requiere al menos un patrón glob. |
/lingo translate [<glob>...] --key <pattern> | Vuelve a traducir las claves con nombre coincidentes en las traducciones existentes. |
/lingo approve | Aprueba la propuesta de traducción pendiente en esta solicitud de incorporación. |
Sin patrones glob ni --key, un comando trabaja con los archivos modificados por la solicitud de incorporación, por lo que se ejecuta incluso si el procesamiento de solicitudes de incorporación está deshabilitado en la configuración. Con patrones glob, trabaja con los archivos de la rama, independientemente de lo que haya modificado la solicitud de incorporación. Los patrones glob son relativos a la raíz del repositorio, distinguen entre mayúsculas y minúsculas y solo abarcan archivos seleccionados por un pattern configurado. --locales acepta una lista separada por comas. Los códigos se comparan con los idiomas de destino configurados sin distinguir entre mayúsculas y minúsculas, y la respuesta señala cualquier código que no coincida con ninguno de ellos.
Completar un archivo o idioma seleccionado y Volver a traducir claves con contexto explican en detalle las variantes con patrones glob y claves.
Completa un archivo o idioma seleccionado #
Publica un comando de alcance limitado en una solicitud de incorporación para solicitar un archivo y un idioma configurados:
/lingo translate locales/en/checkout.json --locales frEn los formatos con un archivo independiente por idioma, esto crea el archivo de destino en francés que falta. No completa las claves que faltan dentro de un archivo de destino existente. Añadir --force regenera los resultados seleccionados sin reutilizar el destino existente, por lo que puede sustituir cambios manuales aceptados. Limita la selección de archivos e idiomas y después revisa las diferencias resultantes.
Los catálogos de cadenas de Xcode y los archivos CSV guardan el contenido de origen y de destino en un mismo archivo. Un comando normal con un ámbito definido rellena las entradas de idioma que faltan y conserva las existentes, incluidas aquellas cuyo texto de origen ha cambiado. Usa /lingo translate sin un patrón de archivos para traducir los cambios del texto de origen en la solicitud de incorporación de cambios; esto puede sustituir las traducciones existentes de las entradas modificadas, incluso las editadas por personas. Añade --force con una selección acotada de archivos e idiomas cuando quieras regenerar las traducciones existentes. Un comando forzado de la aplicación reconstruye el contenido seleccionado y conserva los idiomas que quedan fuera del ámbito solicitado. Para actualizar el contenido mediante la CLI, sigue el procedimiento de corrección de Catálogos de cadenas o CSV.
Vuelve a traducir claves con contexto #
Utiliza --key para volver a traducir claves con nombre seleccionadas en traducciones existentes. En los archivos JSON y JSONC, añade --context para explicar su significado o dar indicaciones sobre el tono y el uso de mayúsculas y minúsculas en esta ejecución:
/lingo translate --key "keyname" --context "button label, keep sentence case"--context requiere --key. Proporciona el contexto una sola vez; se aplica a todas las claves e idiomas seleccionados en los archivos JSON y JSONC. Los demás formatos coincidentes se traducen sin ese contexto. Repite --key para varios patrones y utiliza patrones glob de archivos o --locales para limitar la solicitud. Sin patrones glob de archivos, el comando selecciona todos los archivos de origen configurados. Las claves coinciden de forma exacta, por prefijo o por patrón glob; las traducciones no relacionadas se conservan. Se omiten los formatos sin claves con nombre y los idiomas sin traducciones existentes.
Los comandos de claves de la GitHub App también regeneran las cadenas seleccionadas sin cambios en YAML y en YAML con idiomas en la raíz. El flujo de trabajo de la CLI limitado a claves reutiliza la versión base de forma distinta en esos formatos.
Escribe el comando en una sola línea. Utiliza comillas simples o dobles alrededor del contexto que contenga espacios; --context="button label" también funciona. Para incluir el mismo tipo de comilla dentro del texto, escápala con una barra invertida, por ejemplo --context "Use \"Save\" as a button label". El contexto se conserva con la ejecución para los reintentos y el historial, pero no se guarda como instrucciones del motor ni se hereda en ejecuciones posteriores. Las reglas existentes de glosario, marcadores de posición y formato de salida siguen aplicándose.
Dentro del contexto entre comillas, solo se descodifican \\ y una barra invertida delante de la comilla que lo delimita. Los marcadores de posición como $name y ${name}, las secuencias como \n y la puntuación se conservan tal cual.
Protege el contenido que no debe cambiar #
La aplicación admite catálogos estructurados, documentos de la familia Markdown, HTML, subtítulos, texto sin formato, tablas CSV, archivos de propiedades de Java y recursos de plataforma. Formatos describe los procesadores de cada formato. Payload no se puede seleccionar como formato de archivo en GitHub.
Selecciona HTML con patrones como pages/en/**/*.html y pages/en/**/*.htm; ambas extensiones permiten inferir html y también se acepta un "format": "html" explícito. Salida HTML inserta el texto traducido y los atributos seleccionados en el origen, conservando el marcado, los comentarios y el formato que no se modifican. Un elemento <html> explícito recibe el idioma de destino en lang; no se añaden estructuras envolventes de documento a los fragmentos.
Selecciona archivos de texto sin formato con un patrón que termine en .txt, como metadata/en/*.txt, o con "format": "txt". Un archivo .txt solo corresponde a una entrada de ese tipo, y una entrada con "format": "txt" solo selecciona archivos .txt. Por eso, un patrón amplio como docs/en/**/* omite LICENSE.txt, y una entrada amplia de tipo txt omite las imágenes que acompañan al texto. Texto sin formato traduce cada línea en su ubicación original.
Selecciona los archivos CSV del mismo modo: con un patrón que termine en .csv, como i18n/strings.csv, o con "format": "csv". Un archivo .csv solo puede pertenecer a una entrada de este tipo, y una entrada con "format": "csv" solo selecciona archivos .csv. CSV rellena las columnas de los idiomas de destino en el archivo de origen.
Selecciona los archivos de propiedades de Java del mismo modo, con un patrón que termine en .properties, como src/main/resources/messages_en.properties, o con "format": "properties", para que un patrón genérico como src/main/resources/**/* omita application.properties. Un archivo de origen llamado messages_en.properties tiene archivos de destino como messages_de.properties. Propiedades de Java traduce cada valor en su ubicación original, conserva los comentarios y el formato, y reconoce lockedKeys, preservedKeys, ignoredKeys y lockedPatterns igual que la CLI anterior.
En un documento, selecciona los campos de metadatos de cabecera y las propiedades de los componentes que contienen texto traducible. En un catálogo de tipo JSON, utiliza rutas bloqueadas para copiar valores de origen, rutas conservadas para mantener valores de destino existentes y rutas ignoradas para omitir valores en la salida. Estas opciones permiten incluir texto junto con identificadores y enlaces en un catálogo sin pedir al traductor que los trate todos por igual. La inyección de idioma escribe el idioma de destino en el campo de salida configurado.
Opciones de las entradas de archivos #
Coloca los siguientes campos directamente en un objeto de .lingo/config.json, dentro de su matriz files, no dentro de options. La aplicación valida estrictamente los campos raíz, las entradas de archivos, los ajustes de GitHub, las reglas de componentes y los objetos de inyección de idioma. Ignora la sección opcional i18n y acepta campos adicionales dentro de ella. El esquema legible por máquina está disponible en GET https://api.lingo.dev/github-app/schema.json.
| Campo | Estructura admitida | Valor predeterminado o alcance |
|---|---|---|
pattern / include | Cadena no vacía relativa al repositorio / matriz no vacía de esas cadenas. | Se requiere al menos uno; si se proporciona include, tiene prioridad sobre pattern. Los patrones no pueden empezar por / ni contener ... |
exclude | Matriz de patrones no vacíos relativos al repositorio. | Opcional; se aplica a esta entrada. |
format | Cadena que indica el formato configurado, incluido "html". | Inferencia opcional; .html y .htm seleccionan HTML. Payload no se puede seleccionar. No es un objeto {type,options} de documento. |
localeFormat | "bcp47", "underscore" o "android". | El valor predeterminado habitual es BCP-47; el formato Android utiliza la notación de Android. |
targetPath, sourceRoot | Cadenas no vacías relativas al repositorio. | Opcional; sigue las reglas de plantillas de salida indicadas arriba. |
lockedKeys, preservedKeys, ignoredKeys | Matrices de cadenas no vacías de rutas de claves con notación de puntos o corchetes. | Si se omiten, equivalen a []; los efectos dependen del procesador del formato. No son opciones JSONPath aplicadas directamente al documento. |
injectLocale | Booleano o { "enabled": boolean, "key"?: nonempty string }. | Si se omite, la inyección queda deshabilitada; si está habilitada y no hay key, utiliza language de forma predeterminada. |
translateFrontmatterFields | Matriz de cadenas no vacías. | En los documentos de la familia Markdown, si se omite, se seleccionan title, description; [] no selecciona ninguno. |
translateComponentProps | Matriz de cadenas no vacías con nombres de propiedades u objetos con component opcional y una matriz props obligatoria no vacía. | component es una cadena no vacía o una matriz no vacía de cadenas no vacías; si se omite, se elimina el filtro de nombres. El campo tiene el valor predeterminado []. |
Por ejemplo, una entrada JSON puede incluir "lockedKeys": ["meta.id"], "preservedKeys": ["links.help"], "injectLocale": { "enabled": true, "key": "meta.locale" } junto con su pattern. Una entrada Markdoc puede seleccionar el título de un componente con "translateComponentProps": [{ "component": "Callout", "props": ["title"] }]. La CLI acepta algunos valores vacíos y muestra advertencias sobre algunos campos desconocidos que la aplicación rechaza; valida la configuración de la aplicación con este esquema.
Inspecciona y recupera la primera ejecución recurrente #
Utiliza la comprobación de GitHub y Ejecuciones del flujo de trabajo para localizar el repositorio, la revisión de origen, el motor de localización, los archivos seleccionados, los idiomas y la rama de entrega. Compáralos con el cambio que esperabas y después identifica dónde se detuvo el procesamiento:
| Observación | Qué comprobar antes de solicitar más trabajo |
|---|---|
| Falta la configuración de la rama predeterminada, no es válida o deshabilita el flujo de trabajo | No se publica ninguna comprobación ni comentario en GitHub. Corrige el .lingo/config.json de la rama predeterminada, incluidos los ajustes previstos del flujo de trabajo, y guarda los cambios en un commit. |
| Falta la configuración de la revisión de origen o no es válida tras superar las comprobaciones de la rama predeterminada | La ejecución informa de una comprobación fallida y, en el flujo de PR correspondiente, publica un comentario. Corrige el error notificado en la configuración de origen. |
| No hay cambios de origen coincidentes o la cobertura ya existe | Examina los patrones y la cobertura seleccionada; una ejecución que no realiza cambios no es una traducción fallida. |
| Un cambio de origen de la PR que se pasó por alto anteriormente | Al sincronizar la PR, el flujo de trabajo puede comparar con la base de la PR para recuperar trabajo que se pasó por alto al comparar con la versión de origen inmediatamente anterior. Examina conjuntamente el origen base, el origen actual y el destino. |
| Una persona editó el destino de la PR | En los formatos con archivos de destino independientes, el procesamiento habitual de los cambios de la PR protege un destino modificado respecto a la base cuando el autor de su último commit no es el bot. Examina esa edición en lugar de considerar los resultados omitidos como trabajo pendiente. |
| Ya hay commits cuando se produce un fallo posterior | Los resultados pueden guardarse en commits por lotes. Varios commits pueden pertenecer a una misma ejecución, y el fallo de un lote posterior no revierte los commits anteriores completados correctamente. Revisa por separado las rutas entregadas y los fallos pendientes. |
Los resultados se agrupan en commits con un límite de 100 archivos y un umbral de agrupación de 5 MiB. Un fallo posterior puede dejar intactos los commits anteriores. Revisa las rutas entregadas y los fallos pendientes antes de reintentar o revertir la ejecución.
Deshabilita los desencadenantes correspondientes para detener el trabajo recurrente. Revoca el acceso al repositorio o desinstala la aplicación en GitHub cuando ya no deba tener autorización para actuar en el repositorio. Los commits existentes, las solicitudes de incorporación aceptadas y el consumo anterior se mantienen; conserva o revierte el contenido entregado siguiendo el proceso habitual de tu repositorio.
Recopila actividad en Radar #
La conexión también proporciona a Radar la actividad de commits de GitHub. Recopilar traducciones para su medición explica la configuración de eventos y cómo importar el historial del proveedor antes de ejecutar una medición histórica.