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

Instale o aplicativo do GitHub#

1. Na Lingo.dev, abra sua organização.
2. Acesse Studio > All integrations.
3. No card do GitHub, clique em Install on GitHub.
4. No GitHub, escolha a conta ou organização em que você quer instalar o app.
5. Escolha Todos os repositórios ou Selecionar apenas repositórios.
6. Clique em Instalar.

O GitHub leva você de volta ao Lingo.dev, para a tela Connect GitHub:

1. Escolha a organização do Lingo.dev por meio da qual esta conta do GitHub faz a localização. A última organização que você abriu já vem selecionada.
2. Clique em Connect.
3. Quando aparecer GitHub connected, clique em View integration para abrir a conexão.

A conexão aparece na barra lateral do Studio, em Connected. A aba Configurações mostra a Conta, o Tipo de conta, a Instalação, os Repositórios e se a Conexão está funcionando. A aba Execuções de workflow lista cada execução feita pelo aplicativo, com o repositório e se ela foi iniciada por um push ou por um pull request.

Para adicionar ou remover repositórios depois, abra a aba Configurações da conexão e use Manage on GitHub: o acesso aos repositórios sempre é definido no GitHub, na própria instalação.

Se você solicitou a instalação em vez de instalá-la, o Lingo.dev mostra Installation requested: um administrador da organização no GitHub precisa aprová-la. Depois disso, o GitHub leva você de volta para a tela Connect GitHub para concluir a configuração. O administrador pode revisar a solicitação no GitHub, em Configurações > GitHub Apps da organização. O GitHub também mostra solicitações de aplicativos pendentes para os 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
    }
  }
}

Use a CLI para salvar a configuração do repositório. Execute os comandos abaixo nesta ordem:

1. Execute npx @lingo.dev/cli init para salvar o idioma de origem, os idiomas de destino e os padrões de arquivos em .lingo/config.json.
2. Execute npx @lingo.dev/cli login para fazer login e salvar suas credenciais localmente em ~/.lingo/credentials.json.
3. Execute npx @lingo.dev/cli link para escolher uma organização e uma engine. Isso adiciona orgId e engineId a .lingo/config.json.

O comando init não salva a seção github. Se precisar dela, copie-a do exemplo acima. Consulte o guia de início rápido da CLI.

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.

Os Catálogos de Strings são a exceção. Como um único arquivo .xcstrings reúne todos os idiomas, o caminho de destino é igual ao caminho de origem — o app grava cada idioma nesse mesmo arquivo e nunca adiciona um diretório de idioma nem um nome de arquivo.

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 traduzir alterações no conteúdo de origem, criar arquivos de destino ausentes ou retraduzir chaves selecionadas.

Traduza as alterações no conteúdo de origem do pull request, preservando as traduções que não mudaram:

/lingo translate

Para criar arquivos de destino ausentes, informe padrões glob de arquivos:

/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 ...

Com padrões glob de arquivos explícitos e sem --key, /lingo translate <glob>... é executado no modo de criação de arquivos ausentes. Nesse modo, cria apenas os arquivos de destino que faltam na branch do PR. Adicione --force quando quiser gerar novamente os arquivos de destino já existentes.

Retraduzir chaves selecionadas#

Use --key para atualizar chaves nomeadas selecionadas sem substituir as demais traduções, incluindo edições aceitas em outras chaves.

/lingo translate locales/en.json --key "auth.login" --locales fr,es

Os padrões de chaves aceitam correspondências exatas, prefixos e padrões glob:

Repita --key para selecionar vários padrões. Coloque entre aspas os padrões de chaves que contêm espaços. Os padrões glob de arquivos e --locales limitam o escopo da solicitação; sem padrões glob de arquivos, todos os arquivos de origem configurados são selecionados.

/lingo translate --key "auth.*" --key "checkout.submit" --locales fr

A tradução restrita a chaves requer um formato com chaves nomeadas e uma tradução existente para cada idioma de destino selecionado. Formatos sem chaves nomeadas e idiomas sem traduções existentes são ignorados. Para criar primeiro os arquivos de destino ausentes, execute /lingo translate <glob>... sem --key. Adicionar --force a um comando restrito a chaves não amplia a seleção de chaves nem substitui as demais traduções.

Definir um contexto próprio para uma execução#

Adicione --context para explicar o significado de uma chave selecionada ou orientar o tom e o uso de maiúsculas e minúsculas:

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

--context requer --key. Informe o contexto uma única vez; ele se aplica a todas as chaves e idiomas selecionados nessa execução. O contexto fica salvo com a execução para novas tentativas e consultas ao histórico, mas não altera as regras ou instruções salvas da engine nem é herdado por execuções posteriores. As regras existentes de glossário, marcadores de posição e formato de saída continuam valendo.

Mantenha o comando em uma única linha. Coloque o contexto entre aspas simples ou duplas se ele contiver espaços; --context="button label" também funciona. Para incluir no texto o mesmo tipo de aspas usado para delimitá-lo, use uma barra invertida como caractere de escape:

/lingo translate --key "checkout.submit" --context "Use \"Save\" as a button label"

No contexto entre aspas, apenas \\ e a barra invertida antes das aspas delimitadoras são decodificados. Marcadores de posição como $name e ${name}, sequências como \n e sinais de pontuação são mantidos literalmente.

Formatos compatíveis#

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

• JSON (.json)
• JSONC (.jsonc)
• Markdown (.md)
• MDX (.mdx)
• Markdoc
• Catálogo de Strings do Xcode (.xcstrings)

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

Catálogos de Strings do Xcode#

Um Catálogo de Strings do Xcode reúne todos os idiomas em um único arquivo .xcstrings, então o app o traduz no próprio arquivo, em vez de criar um arquivo para cada idioma. O caminho de destino é igual ao caminho de origem: cada idioma de destino é gravado no mesmo arquivo, ao lado do idioma de origem e de quaisquer idiomas já traduzidos. Aponte o padrão de origem diretamente para o catálogo e defina sourceLocale como seu idioma de desenvolvimento:

{
  "sourceLocale": "en",
  "targetLocales": ["es-MX", "fr-CA", "pt-BR"],
  "files": [{ "pattern": "**/*.xcstrings" }]
}

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.

O push que adiciona .lingo/config.json traduz apenas os arquivos de origem que correspondem aos padrões e foram alterados nesse push. Os arquivos de origem existentes que não foram alterados precisam ser processados separadamente para preencher as traduções ausentes. Para criar os arquivos de destino que faltam, abra uma solicitação de pull a partir de uma ramificação no mesmo repositório, e não de um fork. Adicione um comentário com /lingo translate <glob> na solicitação de pull.

Próximos passos#