GitHub App

O GitHub App da Lingo.dev configura a localização contínua de um repositório usando .lingo/config.json.

Pré-requisitos#

Antes de instalar o app, confirme se você tem:

• Uma organização na Lingo.dev com o recurso de integração com GitHub habilitado
• Um engine de localização nessa organização
• Acesso de administrador à organização ou ao repositório do GitHub que você quer conectar

Conecte o GitHub App#

1. Na Lingo.dev, abra sua organização.
2. Vá até Configurações.
3. Encontre GitHub (App) na seção de integrações.
4. Clique em Conectar na linha GitHub (App).
5. No GitHub, escolha a conta ou organização em que você quer instalar o app.
6. Escolha Todos os repositórios ou Selecionar apenas repositórios.
7. Clique em Instalar.

Após a instalação, a Lingo.dev mostra a conta do GitHub conectada e os repositórios em Configurações > GitHub (App). Use Gerenciar repositórios no GitHub no mesmo cartão de configurações quando precisar adicionar ou remover repositórios depois.

Se sua solicitação de instalação estiver aguardando aprovação, um administrador do GitHub pode revisá-la no GitHub, na área Configurações > GitHub Apps da organização. O GitHub também mostra solicitações de apps pendentes aos proprietários da organização nas configurações da organização.

Adicione a configuração do repositório#

Crie .lingo/config.json no repositório em que você instalou o 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
    }
  }
}

Padrões de arquivos#

Os padrões files apontam para arquivos de origem (idioma padrão). O app verifica os arquivos alterados com base nesses padrões e processa apenas os arquivos de origem compatíveis que corresponderem a eles.

Os padrões são relativos ao repositório, diferenciam maiúsculas de minúsculas e podem usar:

• * para corresponder dentro de um segmento do caminho
• **/ para corresponder a qualquer nível de diretório

Os padrões não podem começar com / nem conter ...

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

Opções de arquivo#

Cada entrada em files pode incluir opções além do próprio pattern. Todas são opcionais, e cada uma se aplica apenas a determinados formatos.

As entradas de translateComponentProps podem ser um nome de prop, que se aplica a essa prop em qualquer componente ou tag, ou um objeto que limita as props a componentes ou tags nomeados:

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

Onde os arquivos localizados são gravados#

O app deriva cada caminho de destino a partir do caminho de origem e dos códigos de idioma definidos na sua configuração:

Use o nome completo do diretório ou do arquivo como código do idioma. Por exemplo, se os arquivos de origem estiverem em docs/en-US/, defina "sourceLocale": "en-US", não "en". Se as strings de origem estiverem em messages/en.json, defina "sourceLocale": "en".

Quando o caminho de origem contém um diretório de idioma, o app substitui esse diretório. Quando o caminho de origem é um arquivo com nome de idioma, o app substitui o nome do arquivo. Se nenhum desses padrões existir, o app coloca o arquivo traduzido em um novo diretório do idioma de destino ao lado do arquivo de origem.

Workflows#

Push para a branch padrão#

Quando um arquivo de origem correspondente é adicionado ou alterado na branch padrão, o app o traduz e faz commit dos arquivos localizados em:

lingo/translations/<default-branch>

Em seguida, ele abre ou atualiza um pull request dessa branch de traduções de volta para a branch padrão. Se a branch de traduções já existir, novos commits são acrescentados a ela.

Se um arquivo de destino for adicionado ou alterado no mesmo push, o app entende que esse arquivo já foi tratado e o leva para o PR de tradução em vez de sobrescrevê-lo.

Pull requests#

Quando github.workflows.onPullRequest.enabled é true, o app verifica as alterações do pull request em busca de arquivos de origem correspondentes. Ele faz commit dos arquivos traduzidos diretamente na branch do PR.

O app não grava em branches de PRs vindos de forks e não grava na branch padrão a partir de um comentário em PR. Os pull requests precisam estar abertos para que o app faça commit das traduções.

Nos PRs, a Lingo.dev atualiza um comentário no PR com os arquivos traduzidos e eventuais falhas.

Atualizações incrementais e recuperação#

Para arquivos de destino existentes, o app traduz apenas as alterações na origem que consegue detectar, em vez de regenerar o arquivo inteiro. Para novos arquivos de destino, ele cria o arquivo localizado para cada idioma de destino configurado.

Se uma localização anterior em PR deixou passar uma alteração na origem ou falhou antes de atualizar o arquivo de destino, a próxima sincronização do PR pode recuperar isso comparando a origem do PR com a origem da branch base e traduzindo a alteração que faltou.

Se um arquivo de origem não existir mais no commit que está sendo processado, o app o ignora.

Modo de aprovação#

Defina github.safety.requireApproval como true quando quiser uma etapa de aprovação humana antes da execução das traduções automáticas.

Em pushes para a branch padrão, a verificação da Lingo.dev mostra as ações Approve e Deny. Em pull requests, o app publica um comentário com a proposta de tradução; responda com:

/lingo approve

Comandos /lingo translate com escopo definido não exigem essa etapa de aprovação.

Comando manual de PR#

Use /lingo em um comentário de pull request para preencher traduções ausentes ou forçar traduções de arquivos específicos.

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

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

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

Referência de comandos:

O comando deve estar em sua própria linha. Os globs são comparados com arquivos que também correspondem aos padrões de origem files configurados. Assim como os padrões da configuração, os globs do comando não podem começar com / nem conter ...

Por padrão, /lingo translate é executado no modo de preenchimento: ele cria apenas os arquivos de destino que estiverem ausentes na branch do PR. Adicione --force quando quiser regenerar arquivos de destino existentes.

Formatos compatíveis#

O GitHub App detecta estes formatos pela extensão do arquivo:

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

Documentos OpenAPI em YAML também são compatíveis, mas não são detectados automaticamente. Defina "format": "yaml-openapi" no padrão de arquivo:

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

Atualizações grandes#

O app pode dividir a saída da tradução em vários commits. Isso acontece quando uma execução gravaria mais de 100 arquivos em um único commit ou mais de 5 MB de conteúdo traduzido em um único commit.

Quando isso acontece, as mensagens de commit incluem o número do lote, por exemplo:

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

O que acontece quando nada corresponde#

Se .lingo/config.json estiver ausente, o app ignora o repositório em silêncio. Depois que a configuração existir, uma configuração inválida gera uma verificação com falha e, em PRs, um comentário com o erro de validação.

Se nenhum arquivo alterado corresponder aos seus padrões de origem, o app conclui sem gravar traduções. Para /lingo translate, o bot responde com uma explicação curta, como nenhum arquivo correspondente, nenhum idioma correspondente ou todos os arquivos de destino já existentes.

Próximos passos#