App de GitHub

La App de GitHub de Lingo.dev configura la localización continua de un repositorio mediante .lingo/config.json.

Requisitos previos#

Antes de instalar la app, asegúrate de tener:

• Una organización de Lingo.dev con la función de integración con GitHub activada
• Un motor de localización en esa organización
• Acceso de administrador a la organización o al repositorio de GitHub que quieras conectar

Conectar la App de GitHub#

1. En Lingo.dev, abre tu organización.
2. Ve a Settings.
3. Busca GitHub (App) en la sección de integraciones.
4. Haz clic en Connect en la fila de GitHub (App).
5. En GitHub, elige la cuenta o la organización en la que quieres instalar la app.
6. Elige All repositories o Only select repositories.
7. Haz clic en Install.

Después de instalarla, Lingo.dev muestra la cuenta de GitHub conectada y los repositorios en Settings > GitHub (App). Usa Manage repositories on GitHub desde la misma tarjeta de ajustes cuando necesites añadir o quitar repositorios más adelante.

Si tu solicitud de instalación está pendiente de aprobación, un administrador de GitHub puede revisarla en GitHub, en el área Settings > GitHub Apps de la organización. GitHub también muestra las solicitudes de apps pendientes a los propietarios de la organización en la configuración de la organización.

Añadir la configuración del repositorio#

Crea .lingo/config.json en el repositorio en el que hayas instalado la 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
    }
  }
}

Patrones de archivo#

Los patrones files apuntan a archivos fuente (idioma predeterminado). La app comprueba los archivos modificados con esos patrones y solo procesa los archivos fuente compatibles que coinciden.

Los patrones son relativos al repositorio, distinguen entre mayúsculas y minúsculas y pueden usar:

• * para coincidir dentro de un segmento de ruta
• **/ para coincidir con cualquier profundidad de directorios

Los patrones no pueden empezar por / ni contener ...

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

Opciones de archivo#

Cada entrada de files puede incluir opciones además de su pattern. Todas son opcionales y cada una solo se aplica a determinados formatos.

Las entradas translateComponentProps pueden ser un nombre de prop, que se aplica a esa prop en cualquier componente o etiqueta, o un objeto que limita las props a componentes o etiquetas concretos:

{
  "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" }
    }
  ]
}

Dónde se escriben los archivos localizados#

La app deriva cada ruta de destino a partir de la ruta de origen y de los códigos de idioma de tu configuración:

Usa el nombre completo del directorio o del archivo como código de idioma. Por ejemplo, si los archivos fuente están en docs/en-US/, configura "sourceLocale": "en-US", no "en". Si las cadenas de origen están en messages/en.json, configura "sourceLocale": "en".

Cuando la ruta de origen contiene un directorio de idioma, la app sustituye ese directorio. Cuando la ruta de origen es un archivo con nombre de idioma, la app sustituye el nombre del archivo. Si no existe ninguno de esos patrones, la app coloca el archivo traducido en un nuevo directorio del idioma de destino junto al archivo fuente.

Flujos de trabajo#

Push a la rama por defecto#

Cuando se añade o modifica un archivo fuente coincidente en la rama por defecto, la app lo traduce y hace commit de los archivos localizados en:

lingo/translations/<default-branch>

Después, abre o actualiza una pull request desde esa rama de traducciones hacia la rama por defecto. Si la rama de traducciones ya existe, se añaden nuevos commits a ella.

Si en el mismo push se añade o modifica un archivo de destino, la app considera que ese archivo ya está gestionado y lo incorpora a la PR de traducción en lugar de sobrescribirlo.

Pull requests#

Cuando github.workflows.onPullRequest.enabled es true, la app revisa los cambios de la pull request en busca de archivos fuente coincidentes. Hace commit de los archivos traducidos directamente en la rama de la PR.

La app no escribe en ramas de PR procedentes de forks ni en la rama por defecto desde un comentario en una PR. Las pull requests deben estar abiertas para que la app pueda hacer commit de las traducciones.

En las PR, Lingo.dev actualiza un comentario con los archivos traducidos y cualquier error.

Actualizaciones incrementales y recuperación#

En los archivos de destino existentes, la app traduce solo los cambios de origen que puede detectar en lugar de regenerar el archivo completo. Para los archivos de destino nuevos, crea el archivo localizado para cada idioma de destino configurado.

Si una localización anterior de una PR omitió un cambio de origen o falló antes de actualizar el archivo de destino, la siguiente sincronización de la PR puede recuperarlo comparando el origen de la PR con el origen de la rama base y traduciendo el cambio que falta.

Si un archivo fuente ya no existe en el commit que se está procesando, la app lo omite.

Modo de aprobación#

Configura github.safety.requireApproval como true cuando quieras añadir un paso de aprobación humana antes de que se ejecuten las traducciones automáticas.

En los pushes a la rama por defecto, la comprobación de Lingo.dev muestra las acciones Approve y Deny. En las pull requests, la app publica un comentario con una propuesta de traducción; responde con:

/lingo approve

Los comandos /lingo translate con alcance definido no requieren esta validación previa.

Comando manual para PR#

Usa /lingo en un comentario de pull request para completar o forzar traducciones de archivos específicos.

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

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

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

Referencia de comandos:

El comando debe ir en su propia línea. Los globs se comparan con archivos que también coinciden con tus patrones de archivos fuente files configurados. Igual que los patrones de configuración, los globs del comando no pueden empezar por / ni contener ...

Por defecto, /lingo translate se ejecuta en modo de completado: solo crea los archivos de destino que faltan en la rama de la PR. Añade --force cuando quieras regenerar archivos de destino existentes.

Formatos compatibles#

La App de GitHub detecta estos formatos a partir de la extensión del archivo:

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

Los documentos OpenAPI escritos en YAML también son compatibles, pero no se detectan automáticamente. Configura "format": "yaml-openapi" en el patrón de archivo:

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

Actualizaciones grandes#

La app puede dividir la salida de traducción en varios commits. Esto ocurre cuando una ejecución escribiría más de 100 archivos en un solo commit o más de 5 MB de contenido de archivos traducidos en un solo commit.

Cuando ocurre, los mensajes de commit incluyen el número de lote, por ejemplo:

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

Qué ocurre cuando no hay coincidencias#

Si falta .lingo/config.json, la app omite el repositorio sin avisar. Una vez que existe la configuración, una configuración no válida genera una comprobación fallida y, en las PR, un comentario con el error de validación.

Si ninguno de los archivos modificados coincide con tus patrones de origen, la app finaliza sin escribir traducciones. En el caso de /lingo translate, el bot responde con una breve explicación, por ejemplo: no hay archivos coincidentes, no hay idiomas coincidentes o todos los archivos de destino ya existen.

Siguientes pasos#