GitHub

Traduce el contenido de tu repositorio con la GitHub App y mantén tanto los cambios de origen como las traducciones disponibles para revisión.

La GitHub App de Lingo.dev incorpora los archivos traducidos al historial de cambios de tu repositorio. Registras el contenido de origen y la configuración de traducción; la aplicación lee los archivos seleccionados, los traduce mediante un motor de localización y devuelve las diferencias para que tu equipo las revise 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 tienes siguen funcionando.

Los cambios en la rama predeterminada generan una solicitud de cambios de traducción. Si habilitas el procesamiento de solicitudes de cambios, las traducciones se incorporan a la rama de esa solicitud. Esta página comienza con el flujo de trabajo de la rama predeterminada y distingue entre la entrega de las traducciones y la decisión de fusionarlas. Para ejecutar la CLI en tu propio ejecutor, usa la receta 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 Configuración → Integraciones y selecciona Conectar para GitHub. Conecta la instalación de la aplicación a tu organización y otorga acceso a los repositorios que quieras que procese. Es posible que un administrador de la organización de GitHub deba 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 instalación de GitHub autorizan el trabajo en los repositorios; los permisos de Lingo.dev autorizan el uso del motor de localización.

Abre la conexión en Configuración → Integraciones para revisar la instalación y el estado de la conexión. Administrar en GitHub abre la configuración de acceso a los repositorios de la instalación. En Studio, selecciona un repositorio en Conectados y usa Ejecuciones de flujo de trabajo, junto con la comprobación de GitHub y los cambios registrados, para hacer seguimiento de un cambio específico del 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 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 registrar un nuevo cambio ni ejecutar una traducción. Explorar los archivos 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 dentro de locales/en/ y genera archivos en francés en las rutas locales/fr/ correspondientes. Reemplaza eng_example por el ID de tu motor de localización:

json
{
  "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 una ejecución y revisa los resultados #

El ejemplo requiere aprobación antes de iniciar la traducción. Para probarlo:

  1. Registra la configuración y un pequeño cambio del contenido de origen en la rama predeterminada, como un mensaje en locales/en/checkout.json.
  2. Abre la comprobación pendiente de GitHub y aprueba la ejecución. Si la aprobación no está disponible, revisa las reglas de aprobación.
  3. Abre la solicitud de cambios de traducción que la aplicación cree o actualice. Busca locales/fr/checkout.json y compara el mensaje modificado con el contenido de origen.
  4. Compila o ejecuta la aplicación con el archivo traducido. Comprueba la redacción, las variables y la selección del idioma; luego revisa y fusiona la solicitud de cambios mediante 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 cambios. Si faltan resultados, consulta inspección y recuperación para identificar la etapa incompleta.

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 generados en francés 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 únicos.

De forma predeterminada, el idioma de origen en una ruta determina dónde se guardan los archivos de destino. Si las rutas no contienen un idioma, configura targetPath: [locale] indica el idioma de destino y [path] indica la ruta de origen después de quitar 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 aparecer como prefijo en las rutas de origen seleccionadas. Los formatos que reúnen varios idiomas en un solo archivo, como los catálogos de cadenas de Xcode y CSV, no admiten plantillas de salida porque las traducciones se mantienen dentro del archivo original.

Usa localeFormat cuando la aplicación necesite códigos de idioma en formato BCP-47, separados por guiones bajos o con la notación de Android en las rutas. Los recursos de Android usan los calificadores de Android de forma predeterminada. Verifica que la primera ruta de salida sea compatible con el cargador de la aplicación antes de agregar 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 de forma predeterminada. El procesamiento de solicitudes de cambios está deshabilitado de forma predeterminada y debe habilitarse explícitamente en la configuración.

Registra un .lingo/config.json válido en la rama predeterminada antes de habilitar el trabajo en solicitudes de cambios. La aplicación lee el ID del motor, github.workflows y github.safety de esa revisión confiable de la rama predeterminada. Los cambios en esos ajustes dentro de una solicitud de cambios no autorizan un motor diferente 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 provienen de la revisión que se está traduciendo.

DesencadenanteEntrega de traducciones
Envío a la rama predeterminadaRegistra los cambios en lingo/translations/<default-branch> y abre o actualiza una solicitud de cambios hacia la rama predeterminada.
Flujo de trabajo de solicitudes de cambios habilitadoRegistra los resultados de traducción en la rama de origen de la solicitud de cambios.
Comando de traducción en una solicitud de cambiosEscribe los resultados de traducción solicitados en la rama de origen de esa solicitud de cambios.

La entrega en solicitudes de cambios requiere una rama de origen que permita escritura en el repositorio donde está instalada la aplicació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 en secuencia y filtra los cambios que ella misma registra para que no activen la traducción repetidamente. Cuando no ha cambiado ningún archivo de origen configurado o los destinos ya cubren el trabajo solicitado, una ejecución puede terminar sin diferencias. Su comprobación explica el resultado; la regeneración forzada sirve para reemplazar 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 iniciar la traducción. Los envíos a la rama predeterminada muestran los controles Aprobar y Denegar en la comprobación. En las solicitudes de cambios, la aplicación publica un comentario y una persona autorizada para revisar responde con /lingo approve.

Cuando se requiere aprobación, un error 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 preliminar. Verifica el alcance de los archivos y los idiomas antes de publicarlo.

Ejecuta comandos en una solicitud de cambios #

Publica un comentario en una solicitud de cambios abierta cuya rama pertenezca al repositorio donde está instalada la aplicación y no sea la rama predeterminada. La aplicación lee la primera línea del comentario que comienza con /lingo. Usa 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 cambios, junto con el motor y los ajustes de seguridad de la rama predeterminada. Solo alguien con acceso de escritura al repositorio puede iniciar una traducción.

ComandoEfecto
/lingo o /lingo helpResponde con la lista de comandos.
/lingo translateTraduce los cambios del contenido de origen de esta solicitud de cambios y conserva las traducciones sin modificaciones. Reemplaza la propuesta de traducción que siga pendiente desde el último envío.
/lingo translate --locales fr,esTraduce los cambios del contenido de origen de esta solicitud de cambios solo para los idiomas indicados.
/lingo translate <glob>...Crea los archivos de destino faltantes para los archivos de origen configurados que coincidan con los patrones glob.
/lingo translate <glob>... --forceRegenera los destinos coincidentes y reemplaza las traducciones existentes. --force requiere al menos un patrón glob.
/lingo translate [<glob>...] --key <pattern>Vuelve a traducir las claves con nombre que coincidan en las traducciones existentes.
/lingo approveAprueba la propuesta de traducción pendiente en esta solicitud de cambios.

Sin patrones glob ni --key, un comando trabaja con los archivos modificados por la solicitud de cambios, por lo que se ejecuta incluso cuando el procesamiento de solicitudes de cambios 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 cambios. Los patrones glob son relativos a la raíz del repositorio, distinguen entre mayúsculas y minúsculas y solo abarcan los 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 con alcance limitado en una solicitud de cambios para solicitar un archivo y un idioma configurados:

text
/lingo translate locales/en/checkout.json --locales fr

En los formatos con un archivo separado por idioma, esto crea el archivo de destino en francés que falta. No completa las claves faltantes dentro de un archivo de destino existente. Agregar --force regenera la salida seleccionada sin reutilizar el destino existente, por lo que puede reemplazar ediciones humanas aceptadas. Limita la selección de archivos e idiomas y luego 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 básico con un alcance definido completa las entradas de idioma faltantes y conserva las existentes, incluso si su contenido de origen cambió. Usa /lingo translate sin un patrón de archivo para traducir los cambios del contenido de origen en la solicitud de incorporación de cambios; esto puede reemplazar las traducciones existentes de las entradas modificadas, incluidas las ediciones manuales. Agrega --force con una selección limitada 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 alcance 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 #

Usa --key para volver a traducir las claves con nombre seleccionadas en las traducciones existentes. En los archivos JSON y JSONC, agrega --context para explicar su significado o dar indicaciones sobre el tono y el uso de mayúsculas y minúsculas en esta ejecución:

text
/lingo translate --key "keyname" --context "button label, keep sentence case"

--context requiere --key. Proporciona el contexto una sola vez; se aplica a cada clave e idioma seleccionados en los archivos JSON y JSONC. Los demás formatos coincidentes se traducen sin ese contexto. Repite --key para varios patrones y usa 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 que no han cambiado en YAML y en YAML con el idioma en la raíz. El flujo de trabajo de la CLI con alcance por claves reutiliza la versión base de manera diferente en esos formatos.

Mantén el comando en una sola línea. Usa comillas simples o dobles alrededor del contexto que contenga espacios; --context="button label" también funciona. Para incluir la misma 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 decodifican \\ y una barra invertida antes de la comilla delimitadora. 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 cómo se procesa cada formato. Payload no es un formato de archivo que se pueda seleccionar 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. La salida HTML incorpora el texto traducido y los atributos seleccionados en el origen, conservando el marcado, los comentarios y el formato que no se modificaron. Un elemento <html> explícito recibe el idioma de destino en lang; a los fragmentos no se les agregan contenedores de documento.

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 pertenece a una entrada de ese tipo, y una entrada con "format": "txt" selecciona únicamente archivos .txt. Por eso, un patrón amplio como docs/en/**/* omite LICENSE.txt, y una entrada amplia de txt omite las imágenes que están junto al texto. Texto sin formato traduce cada línea en su ubicación original.

Selecciona los archivos CSV de la misma manera: con un patrón que termine en .csv, como i18n/strings.csv, o con "format": "csv". Un archivo .csv solo pertenece a una entrada de ese tipo, y una entrada con "format": "csv" selecciona únicamente archivos .csv. CSV completa las columnas de los idiomas de destino en el archivo de origen.

Selecciona los archivos de propiedades de Java de la misma forma, con un patrón que termine en .properties, como src/main/resources/messages_en.properties, o con "format": "properties", para que un patrón amplio como src/main/resources/**/* omita application.properties. Un archivo de origen llamado messages_en.properties genera archivos de destino como messages_de.properties. Propiedades de Java traduce cada valor en su ubicación original, conserva los comentarios y la estructura, y reconoce lockedKeys, preservedKeys, ignoredKeys y lockedPatterns tal como lo hacía la CLI anterior.

Para un documento, selecciona los campos de metadatos iniciales y las propiedades de componentes que contengan texto traducible. Para un catálogo de tipo JSON, usa rutas bloqueadas para copiar los valores de origen, rutas preservadas para conservar los valores de destino existentes y rutas ignoradas para omitir valores de la salida. Estas opciones permiten que un catálogo contenga texto junto con identificadores y enlaces sin pedirle al traductor que los trate todos de la misma manera. 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 del arreglo files de .lingo/config.json, no dentro de options. La aplicación valida estrictamente los campos raíz, las entradas de archivos, la configuración 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 esa sección. El esquema legible por máquina está disponible en GET https://api.lingo.dev/github-app/schema.json.

CampoEstructura aceptadaValor predeterminado o alcance
pattern / includeCadena no vacía relativa al repositorio / arreglo no vacío de esas cadenas.Se requiere al menos uno; si se proporciona include, tiene prioridad sobre pattern. Los patrones no pueden comenzar con / ni contener ...
excludeArreglo de patrones no vacíos relativos al repositorio.Opcional; se aplica a esta entrada.
formatCadena que indica el formato configurado, incluido "html".Inferencia opcional; .html y .htm seleccionan HTML. Payload no se puede seleccionar. Esto no es un objeto {type,options} de documento.
localeFormat"bcp47", "underscore" o "android".El valor predeterminado habitual es BCP-47; el formato Android usa la notación de Android.
targetPath, sourceRootCadenas no vacías relativas al repositorio.Opcional; sigue las reglas de plantillas de salida indicadas arriba.
lockedKeys, preservedKeys, ignoredKeysArreglos de cadenas no vacías de rutas de claves con notación de puntos o corchetes.Omitirlas equivale a []; los efectos dependen del controlador del formato. Estas no son opciones JSONPath directas del documento.
injectLocaleBooleano o { "enabled": boolean, "key"?: nonempty string }.Omitirlo deshabilita la inyección; si está habilitada, usa language de forma predeterminada cuando falta key.
translateFrontmatterFieldsArreglo de cadenas no vacías.En documentos de la familia Markdown, omitirlo selecciona title, description; [] no selecciona ninguno.
translateComponentPropsArreglo de cadenas no vacías con nombres de propiedades u objetos con component opcional y un arreglo props obligatorio y no vacío.component es una cadena no vacía o un arreglo no vacío de cadenas no vacías; omitirlo 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 emite 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 #

Usa la comprobación de GitHub y Ejecuciones de flujo de trabajo para identificar 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 luego identifica dónde se detuvo el procesamiento:

ObservaciónQué comprobar antes de solicitar más trabajo
Falta la configuración de la rama predeterminada, no es válida o deshabilita el flujo de trabajoNo se publica ninguna comprobación ni comentario de GitHub. Corrige y registra el .lingo/config.json de la rama predeterminada, incluidos los ajustes previstos del flujo de trabajo.
Falta la configuración de la revisión de origen o no es válida después de superar las comprobaciones de la rama predeterminadaLa ejecución muestra una comprobación fallida y, para el flujo de PR aplicable, un comentario. Corrige el error indicado en la configuración de origen.
No hay cambios de origen coincidentes o la cobertura ya existeRevisa los patrones y la cobertura seleccionada; una operación sin cambios no es una traducción fallida.
Un cambio de origen de una PR omitido anteriormenteAl sincronizar la PR, el flujo de trabajo puede comparar con la base de la PR para recuperar trabajo omitido en la comparación con la versión de origen inmediatamente anterior. Revisa juntos el origen base, el origen actual y el destino.
Una persona editó el destino de la PREn los formatos con archivos de destino separados, el procesamiento habitual de las diferencias de la PR protege un destino modificado respecto de la base cuando el autor de su último cambio registrado no es el bot. Revisa esa edición en lugar de considerar los resultados omitidos como trabajo faltante.
Se registraron algunos cambios antes de un error posteriorLos resultados pueden registrarse en lotes. Varios registros de cambios pueden pertenecer a una misma ejecución, y un lote posterior fallido no revierte los cambios anteriores registrados correctamente. Revisa por separado las rutas entregadas y los errores restantes.

Los resultados se agrupan en registros de cambios con un límite de 100 archivos y un umbral de agrupación de 5 MiB. Un error posterior puede dejar intactos los cambios registrados antes. Revisa las rutas entregadas y los errores restantes antes de reintentar o revertir la ejecución.

Deshabilita los desencadenantes aplicables para detener el trabajo recurrente. Revoca el acceso a los repositorios o desinstala la aplicación en GitHub cuando ya no deba tener autorización sobre ellos. Los cambios registrados existentes, las solicitudes de cambios aceptadas y el consumo previo se mantienen; conserva o revierte el contenido entregado mediante el proceso habitual de tu repositorio.

Recopila actividad en Radar #

La conexión también proporciona a Radar la actividad de cambios registrados en GitHub. Recopilar traducciones para medición describe la configuración de eventos y cómo importar el historial del proveedor antes de realizar una medición histórica.