App de GitHub

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

Requisitos previos#

Antes de instalar la app, asegúrate de contar con:

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

Conecta 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 donde quieres instalar la app.
6. Elige All repositories o Only select repositories.
7. Haz clic en Install.

Después de la instalación, Lingo.dev muestra la cuenta de GitHub conectada y los repositorios en Settings > GitHub (App). Usa Manage repositories on GitHub desde esa misma tarjeta de configuración cuando necesites agregar 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 dentro de la configuración de la organización.

Agrega la configuración del repositorio#

Crea .lingo/config.json en el repositorio donde instalaste 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 archivos#

Los patrones files apuntan a archivos fuente (idioma predeterminado). La app compara los archivos modificados con estos patrones y solo procesa los archivos fuente compatibles que coincidan.

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

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

Los patrones no pueden comenzar con / ni contener ...

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

Opciones de archivo#

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

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

{
  "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 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 fuente están en messages/en.json, configura "sourceLocale": "en".

Cuando la ruta de origen contiene un directorio de idioma, la app reemplaza ese directorio. Cuando la ruta de origen es un archivo con nombre de idioma, la app reemplaza 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 predeterminada#

Cuando se agrega o modifica un archivo fuente coincidente en la rama predeterminada, la app lo traduce y hace commit de los archivos localizados en:

lingo/translations/<default-branch>

Luego abre o actualiza un pull request desde esa rama de traducciones hacia la rama predeterminada. Si la rama de traducciones ya existe, se le agregan nuevos commits.

Si en ese mismo push se agrega o modifica un archivo de destino, la app considera que ese archivo ya fue atendido y lo incluye en el PR de traducción en lugar de sobrescribirlo.

Pull requests#

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

La app no escribe en ramas de PR provenientes de forks ni escribe en la rama predeterminada a partir de un comentario en un PR. Los pull requests deben estar abiertos para que la app pueda hacer commit de las traducciones.

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

Actualizaciones incrementales y recuperación#

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

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

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 un paso de aprobación humana antes de que se ejecuten las traducciones automáticas.

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

/lingo approve

Los comandos con alcance limitado de /lingo translate no requieren esta aprobació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 los patrones de archivos fuente configurados en files. Igual que los patrones de configuración, los globs del comando no pueden comenzar con / ni contener ...

De forma predeterminada, /lingo translate se ejecuta en modo de completado: solo crea archivos de destino que faltan en la rama del PR. Agrega --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 sucede cuando una ejecución escribiría más de 100 archivos en un solo commit o más de 5 MB de contenido traducido en un solo commit.

Cuando eso 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é pasa cuando no hay coincidencias#

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

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

Siguientes pasos#