App GitHub

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

Pré-requisitos#

Antes de instalar a app, confirme que tem:

• Uma organização Lingo.dev com a funcionalidade de integração com o GitHub ativada
• Um motor de localização nessa organização
• Acesso de administrador à organização ou ao repositório GitHub que quer ligar

Ligar a App GitHub#

1. Na Lingo.dev, abra a sua organização.
2. Vá a Definições.
3. Encontre GitHub (App) na secção de integrações.
4. Clique em Ligar na linha GitHub (App).
5. No GitHub, escolha a conta ou organização onde quer instalar a app.
6. Escolha Todos os repositórios ou Apenas repositórios selecionados.
7. Clique em Instalar.

Depois da instalação, a Lingo.dev mostra a conta GitHub ligada e os repositórios em Definições > GitHub (App). Use Gerir repositórios no GitHub no mesmo cartão de definições sempre que precisar de adicionar ou remover repositórios mais tarde.

Se o seu pedido de instalação estiver à espera de aprovação, um administrador do GitHub pode revê-lo no GitHub, na área Definições > GitHub Apps da organização. O GitHub também mostra pedidos de app pendentes aos proprietários da organização nas respetivas definições.

Adicionar a configuração do repositório#

Crie .lingo/config.json no repositório onde instalou a 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 ficheiros#

Os padrões files apontam para ficheiros de origem (idioma predefinido). A app verifica os ficheiros alterados com base nestes padrões e processa apenas os ficheiros de origem suportados que correspondam.

Os padrões são relativos ao repositório, sensíveis a maiúsculas e minúsculas, e podem usar:

• * para corresponder dentro de um segmento de caminho
• **/ para corresponder a qualquer profundidade de diretórios

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

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

Opções de ficheiro#

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

As entradas translateComponentProps são ou 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 com nome:

{
  "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 ficheiros localizados são gravados#

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

Use o nome completo do diretório ou do ficheiro como código de idioma. Por exemplo, se os ficheiros de origem estiverem em docs/en-US/, defina "sourceLocale": "en-US" e 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, a app substitui esse diretório. Quando o caminho de origem é um ficheiro com nome de idioma, a app substitui o nome do ficheiro. Se nenhum destes padrões existir, a app coloca o ficheiro traduzido num novo diretório do idioma de destino ao lado do ficheiro de origem.

Workflows#

Push para a branch predefinida#

Quando um ficheiro de origem correspondente é adicionado ou alterado na branch predefinida, a app traduz esse ficheiro e faz commit dos ficheiros localizados para:

lingo/translations/<default-branch>

Depois, abre ou atualiza um pull request dessa branch de traduções para a branch predefinida. Se a branch de traduções já existir, os novos commits são acrescentados a essa branch.

Se um ficheiro de destino for adicionado ou alterado no mesmo push, a app trata esse ficheiro como já processado e inclui-o no PR de tradução em vez de o substituir.

Pull requests#

Quando github.workflows.onPullRequest.enabled é true, a app verifica as alterações do pull request à procura de ficheiros de origem correspondentes. Faz commit dos ficheiros traduzidos diretamente na branch do PR.

A app não escreve em branches de PRs com fork e não escreve na branch predefinida a partir de um comentário de PR. Os pull requests têm de estar abertos para a app fazer commit das traduções.

Nos PRs, a Lingo.dev atualiza um comentário do PR com os ficheiros traduzidos e quaisquer falhas.

Atualizações incrementais e recuperação#

Para ficheiros de destino existentes, a app traduz apenas as alterações de origem que consegue detetar, em vez de regenerar o ficheiro completo. Para novos ficheiros de destino, cria o ficheiro localizado para cada idioma de destino configurado.

Se uma localização anterior de PR não tiver incluído uma alteração de origem ou tiver falhado antes de atualizar o ficheiro de destino, a sincronização seguinte do PR pode recuperar comparando a origem do PR com a origem da branch base e traduzindo a alteração em falta.

Se um ficheiro de origem já não existir no commit que está a ser processado, a app ignora-o.

Modo de aprovação#

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

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

/lingo approve

Os comandos /lingo translate com âmbito definido não exigem esta etapa de aprovação.

Comando manual de PR#

Use /lingo num comentário de pull request para preencher traduções em falta ou forçar traduções para ficheiros 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 tem de estar numa linha própria. Os globs são comparados com ficheiros que também correspondam aos padrões de origem files configurados. Tal como os padrões da configuração, os globs do comando não podem começar por / nem conter ...

Por predefinição, /lingo translate é executado em modo de preenchimento: cria apenas os ficheiros de destino que estão em falta na branch do PR. Adicione --force quando quiser regenerar ficheiros de destino existentes.

Formatos suportados#

A App GitHub deteta estes formatos a partir da extensão do ficheiro:

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

Os documentos OpenAPI escritos em YAML também são suportados, mas não são detetados automaticamente. Defina "format": "yaml-openapi" no padrão de ficheiro:

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

Atualizações de grande dimensão#

A app pode dividir a saída da tradução por vários commits. Isto acontece quando uma execução escreveria mais de 100 ficheiros num único commit ou mais de 5 MB de conteúdo de ficheiros traduzidos num ú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 em falta, a app ignora o repositório silenciosamente. Quando a configuração passa a existir, uma configuração inválida cria um check run com falha e, nos PRs, um comentário com o erro de validação.

Se nenhum ficheiro alterado corresponder aos seus padrões de origem, a app conclui sem escrever traduções. Para /lingo translate, o bot responde com uma explicação breve, como não haver ficheiros correspondentes, não haver idiomas correspondentes ou todos os ficheiros de destino já existirem.

Próximos passos#