GitHub

Traduza o conteúdo do repositório com o GitHub App e mantenha as alterações na origem e as traduções disponíveis para revisão.

Com o GitHub App da Lingo.dev, os arquivos traduzidos passam a fazer parte do histórico de alterações do seu repositório. Você faz commit do conteúdo de origem e de uma configuração de tradução; o aplicativo lê os arquivos selecionados, traduz esses arquivos com um engine de localização e retorna um diff que a equipe pode analisar no GitHub.

No menu de navegação do Studio 2.5, acesse Studio 2.5 → Integrações em vez de Configurações → Integrações. Os links de conexão e configuração existentes continuam funcionando.

Alterações na branch padrão geram um pull request de tradução. Se você ativar o processamento de pull requests, as traduções serão adicionadas à branch do próprio pull request. Esta página começa pelo workflow da branch padrão e trata a entrega das traduções separadamente da decisão de mesclá-las. Para executar a CLI no seu próprio executor, use a receita do GitHub Actions.

Para que seu agente de programação possa se conectar ao aplicativo, consulte Configurar com um agente de programação.

Conecte o repositório e a configuração de tradução #

Na Lingo.dev, abra Configurações → Integrações e selecione Conectar para o GitHub. Conecte a instalação do aplicativo à sua organização e conceda acesso aos repositórios que ele deve processar. Pode ser necessária a aprovação de um administrador da organização no GitHub; o acesso aos repositórios respeita o escopo selecionado na instalação.

Escolha um engine de localização ao qual você tenha acesso na organização conectada. A configuração dele define os modelos, o glossário, as regras, a voz e o comportamento de revisão aplicável. As permissões da instalação no GitHub autorizam o trabalho no repositório; as permissões da Lingo.dev autorizam o uso do engine de localização.

Abra a conexão em Configurações → Integrações para verificar a instalação e o estado da conexão. Gerenciar no GitHub abre as configurações de acesso da instalação aos repositórios. No Studio, selecione um repositório em Conectado e use Execuções de workflow, junto com a verificação do GitHub e os commits, para acompanhar uma alteração específica no conteúdo de origem.

Se o Studio 2.5 estiver ativado para sua organização, a barra lateral Conteúdo de origem lista os repositórios que a instalação conectada pode acessar, sem precisar esperar por um evento do GitHub. Com um .lingo/config.json válido na branch padrão, você pode abrir os arquivos de origem JSON e JSONC configurados e suas traduções existentes sem fazer um novo commit nem executar uma tradução. A navegação não consome créditos de tradução nem ativa a sincronização automática. Repositórios sem configuração válida continuam visíveis; ao abrir seus arquivos, o erro de configuração é exibido.

Crie .lingo/config.json na raiz do repositório. Este exemplo seleciona catálogos JSON em inglês em locales/en/ e gera arquivos em francês nos caminhos locales/fr/ correspondentes. Substitua eng_example pelo ID do seu engine de localização:

json
{
  "engineId": "eng_example",
  "sourceLocale": "en",
  "targetLocales": ["fr"],
  "files": [
    {
      "pattern": "locales/en/**/*.json",
      "format": "json"
    }
  ],
  "github": {
    "workflows": {
      "onPushToDefaultBranch": { "enabled": true },
      "onPullRequest": { "enabled": false }
    },
    "safety": { "requireApproval": true }
  }
}

Conclua uma execução e confira o resultado #

O exemplo exige aprovação antes do início da tradução. Para testá-lo:

  1. Faça commit da configuração e de uma pequena alteração no conteúdo de origem na branch padrão, como uma mensagem em locales/en/checkout.json.
  2. Abra a verificação pendente do GitHub e aprove a execução. Se a aprovação não estiver disponível, confira as regras de aprovação.
  3. Abra o pull request de tradução criado ou atualizado pelo aplicativo. Localize locales/fr/checkout.json e compare a mensagem alterada com o conteúdo de origem.
  4. Compile ou execute o aplicativo com o arquivo traduzido. Confira o texto, as variáveis e a seleção de idioma. Depois, revise e mescle o pull request seguindo o processo habitual do repositório.

A aprovação na etapa 2 autoriza o trabalho de tradução e o consumo correspondente. Ela não aprova o texto resultante nem mescla o pull request. Se algum resultado estiver faltando, consulte inspeção e recuperação para identificar a etapa incompleta.

Adapte a configuração à organização dos seus arquivos #

Os padrões de origem devem selecionar apenas arquivos de origem. Por exemplo, locales/en/**/*.json exclui os arquivos gerados em francês das buscas posteriores por arquivos de origem. Os padrões são relativos ao repositório; caminhos absolutos e .. são rejeitados. Cada entrada de arquivo exige um pattern ou uma lista include. Uma configuração aceita até 100 entradas de arquivo e 50 idiomas de destino distintos.

Por padrão, o idioma de origem no caminho determina onde os arquivos de destino são salvos. Quando os caminhos não contêm um idioma, defina targetPath: [locale] fornece o idioma de destino, e [path] fornece o caminho de origem após a remoção do prefixo opcional sourceRoot. Por exemplo, sourceRoot: "content" e targetPath: "translations/[locale]/[path]" mapeiam content/help/start.md para translations/fr/help/start.md para o francês. Um modelo baseado em padrões glob precisa dos dois marcadores. sourceRoot exige targetPath e deve aparecer como prefixo dos caminhos de origem selecionados. Formatos que reúnem vários idiomas em um único arquivo, como catálogos de strings do Xcode e CSV, não aceitam modelos de saída, pois as traduções permanecem no arquivo original.

Use localeFormat quando o aplicativo precisar de códigos de idioma no padrão BCP-47, separados por sublinhados ou na notação do Android nos caminhos. Os recursos do Android usam qualificadores do Android por padrão. Confira se o primeiro caminho de saída é compatível com o carregador do aplicativo antes de adicionar mais idiomas.

Escolha quando executar a tradução e onde gravar os resultados #

O processamento de pushes na branch padrão fica ativado por padrão. Já o processamento de pull requests fica desativado por padrão e precisa ser ativado explicitamente na configuração.

Faça commit de um .lingo/config.json válido na branch padrão antes de ativar o processamento de pull requests. O aplicativo lê o ID do engine, github.workflows e github.safety dessa revisão confiável da branch padrão. Alterações nessas configurações em um pull request não autorizam outro engine nem mudam a política de aprovação da própria execução. O idioma de origem, a seleção de arquivos e os idiomas de destino vêm da revisão que está sendo traduzida.

GatilhoEntrega da tradução
Push na branch padrãoFaz commits em lingo/translations/<default-branch> e abre ou atualiza um pull request para a branch padrão.
Workflow de pull request ativadoFaz commit das traduções na branch de origem do pull request.
Comando de tradução em um pull requestGrava as traduções solicitadas na branch de origem desse pull request.

A entrega por pull request exige uma branch de origem que permita gravação no repositório em que o aplicativo está instalado. O aplicativo ignora forks e não permite gravar essa saída diretamente na branch padrão.

O aplicativo processa o trabalho do repositório em sequência e filtra os commits que ele mesmo gera para evitar que acionem a tradução repetidamente. Quando nenhum arquivo de origem configurado mudou ou os destinos já cobrem o trabalho solicitado, uma execução pode terminar sem um diff. A verificação explica o resultado; a regeneração forçada serve para substituir traduções selecionadas, não para fazer uma execução sem alterações parecer ativa.

Exija aprovação antes de gerar custos em uma execução #

github.safety.requireApproval tem false como valor padrão. Defina esse valor como true na configuração da branch padrão quando for necessário autorizar uma execução antes do início da tradução. Pushes na branch padrão exibem os controles Aprovar e Negar na verificação. Para pull requests, o aplicativo publica um comentário, e um revisor autorizado responde com /lingo approve.

Quando a aprovação é obrigatória, uma falha na criação da verificação de auditoria bloqueia o workflow. Corrija a criação da verificação ou o acesso antes de tentar aprovar novamente.

Qualquer comando /lingo translate, com ou sem globs de arquivo, autoriza o trabalho solicitado e dispensa essa aprovação preliminar. Confira o escopo de arquivos e idiomas antes de publicá-lo.

Execute comandos em um pull request #

Publique um comentário em um pull request aberto cuja branch pertença ao repositório em que o aplicativo está instalado e não seja a branch padrão. O aplicativo lê a primeira linha do comentário que começa com /lingo. Ele usa o idioma de origem, as opções de arquivo e os idiomas de destino da configuração da branch de origem do pull request, junto com o engine e as configurações de segurança da branch padrão. Apenas quem tem acesso de gravação no repositório pode iniciar a tradução.

ComandoEfeito
/lingo ou /lingo helpResponde com a lista de comandos.
/lingo translateTraduz as alterações no conteúdo de origem deste pull request e mantém as traduções que não mudaram. Substitui uma proposta de tradução ainda pendente desde o último push.
/lingo translate --locales fr,esTraduz as alterações no conteúdo de origem deste pull request apenas para os idiomas listados.
/lingo translate <glob>...Cria os arquivos de destino ausentes para os arquivos de origem configurados que correspondem aos globs.
/lingo translate <glob>... --forceRegenera os destinos correspondentes, substituindo as traduções existentes. --force exige pelo menos um glob.
/lingo translate [<glob>...] --key <pattern>Traduz novamente as chaves nomeadas correspondentes nas traduções existentes.
/lingo approveAprova a proposta de tradução pendente neste pull request.

Sem globs ou --key, um comando usa os arquivos alterados pelo pull request e, por isso, é executado mesmo quando o processamento de pull requests está desativado na configuração. Com globs, ele usa os arquivos da branch, independentemente do que o pull request alterou. Os globs são relativos à raiz do repositório, diferenciam maiúsculas de minúsculas e só abrangem arquivos selecionados por um pattern configurado. --locales recebe uma lista separada por vírgulas. A correspondência dos códigos com os idiomas de destino configurados não diferencia maiúsculas de minúsculas, e a resposta informa os códigos que não correspondem a nenhum deles.

Preencher um arquivo ou idioma selecionado e Traduzir chaves novamente com contexto explicam em detalhes as formas com globs e chaves.

Preencha um arquivo ou idioma selecionado #

Publique um comando com escopo delimitado em um pull request para solicitar um arquivo e um idioma configurados:

text
/lingo translate locales/en/checkout.json --locales fr

Para formatos com um arquivo separado por idioma, esse comando preenche um arquivo de destino em francês que esteja faltando. Ele não preenche chaves ausentes em um arquivo de destino existente. Adicionar --force regenera a saída selecionada sem reutilizar o destino existente, o que pode substituir edições humanas já aceitas. Restrinja a seleção de arquivos e idiomas e revise o diff resultante.

Os catálogos de strings do Xcode e os arquivos CSV mantêm o conteúdo de origem e de destino em um único arquivo. Um comando simples com escopo definido preenche as entradas de idioma ausentes e preserva as existentes, inclusive aquelas cujo texto de origem mudou. Use /lingo translate sem um padrão de arquivo para traduzir as alterações no texto de origem presentes na solicitação de integração; isso pode substituir as traduções existentes dessas entradas alteradas, inclusive edições feitas por pessoas. Adicione --force com uma seleção restrita de arquivos e idiomas quando quiser gerar novamente as traduções existentes. Um comando forçado do aplicativo reconstrói o conteúdo selecionado, preservando os idiomas fora do escopo solicitado. Para atualizar pela CLI, siga o procedimento de correção de Catálogos de strings ou CSV.

Traduza chaves novamente com contexto #

Use --key para traduzir novamente as chaves nomeadas selecionadas nas traduções existentes. Para arquivos JSON e JSONC, adicione --context para explicar o significado delas ou orientar esta execução sobre o tom e o uso de maiúsculas e minúsculas:

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

--context exige --key. Forneça o contexto uma única vez; ele se aplica a todas as chaves e idiomas selecionados nos arquivos JSON e JSONC. Outros formatos correspondentes são traduzidos sem esse contexto. Repita --key para usar vários padrões e use globs de arquivo ou --locales para restringir a solicitação. Sem globs de arquivo, o comando seleciona todos os arquivos de origem configurados. A correspondência das chaves pode ser exata, por prefixo ou por glob; as traduções não relacionadas são preservadas. Formatos sem chaves nomeadas e idiomas sem traduções existentes são ignorados.

Os comandos por chave do GitHub App também regeneram as strings selecionadas que não mudaram em YAML e YAML com raiz por idioma. O workflow da CLI com escopo por chave tem um comportamento diferente de reutilização da versão de referência nesses formatos.

Mantenha o comando em uma única linha. Coloque o contexto entre aspas simples ou duplas quando ele contiver espaços; --context="button label" também funciona. Para incluir a mesma aspa no texto, use uma barra invertida como escape, por exemplo --context "Use \"Save\" as a button label". O contexto fica associado à execução para novas tentativas e histórico, mas não é salvo como instruções do engine nem herdado por execuções posteriores. As regras existentes de glossário, placeholders e formato de saída continuam valendo.

No contexto entre aspas, apenas \\ e a barra invertida antes da aspa delimitadora são decodificados. Placeholders como $name e ${name}, sequências como \n e sinais de pontuação permanecem literais.

Proteja o conteúdo que não deve mudar #

O aplicativo oferece suporte a catálogos estruturados, documentos da família Markdown, HTML, legendas, texto simples, tabelas CSV, arquivos de propriedades Java e recursos de plataforma. A seção Formatos descreve os processadores de cada formato. Payload não é uma opção de formato de arquivo no GitHub.

Selecione HTML com padrões como pages/en/**/*.html e pages/en/**/*.htm; ambas as extensões permitem inferir html, e um "format": "html" explícito também é aceito. A saída HTML aplica o texto traduzido e os atributos selecionados ao conteúdo de origem, preservando a marcação não alterada, os comentários e a formatação. Um elemento <html> explícito recebe o idioma de destino em lang; fragmentos não recebem elementos adicionais de estrutura de documento.

Selecione arquivos de texto simples usando um padrão que termine em .txt, como metadata/en/*.txt, ou usando "format": "txt". Um arquivo .txt só pode pertencer a uma entrada desse tipo, e uma entrada com "format": "txt" seleciona apenas arquivos .txt. Por isso, um padrão abrangente como docs/en/**/* ignora LICENSE.txt, e uma entrada abrangente txt ignora as imagens que estão junto ao texto. Texto simples traduz cada linha no local em que ela se encontra.

Selecione os arquivos CSV da mesma forma: com um padrão que termine em .csv, como i18n/strings.csv, ou com "format": "csv". Um arquivo .csv só pode pertencer a uma entrada desse tipo, e uma entrada com "format": "csv" seleciona apenas arquivos .csv. CSV preenche as colunas dos idiomas de destino no arquivo de origem.

Selecione arquivos de propriedades Java da mesma forma, usando um padrão que termine em .properties, como src/main/resources/messages_en.properties, ou usando "format": "properties" para que um padrão amplo como src/main/resources/**/* ignore application.properties. Um arquivo de origem chamado messages_en.properties gera arquivos de destino como messages_de.properties. Propriedades Java traduz cada valor no próprio arquivo, preserva os comentários e a formatação e reconhece lockedKeys, preservedKeys, ignoredKeys e lockedPatterns, assim como a CLI anterior.

Para um documento, selecione os campos de frontmatter e as propriedades de componentes que contêm texto traduzível. Para um catálogo semelhante a JSON, use caminhos bloqueados para copiar valores de origem, caminhos preservados para manter valores de destino existentes e caminhos ignorados para omitir valores da saída. Essas opções permitem reunir texto, identificadores e links em um catálogo sem pedir ao tradutor que trate tudo da mesma forma. A injeção de idioma grava o idioma de destino no campo de saída configurado.

Opções de entrada de arquivo #

Coloque os campos a seguir diretamente em um objeto do array files de .lingo/config.json, não dentro de options. O aplicativo valida rigorosamente os campos da raiz, as entradas de arquivo, as configurações do GitHub, as regras de componentes e os objetos de injeção de idioma. Ele ignora a seção opcional i18n e aceita campos adicionais dentro dela. O esquema legível por máquina está disponível em GET https://api.lingo.dev/github-app/schema.json.

CampoEstrutura aceitaPadrão ou escopo
pattern / includeString não vazia relativa ao repositório / array não vazio dessas strings.Pelo menos um é obrigatório; quando fornecido, include tem precedência sobre pattern. Os padrões não podem começar com / nem conter ...
excludeArray de padrões não vazios relativos ao repositório.Opcional; aplica-se a esta entrada.
formatString que especifica o formato configurado, incluindo "html".Inferência opcional; .html e .htm selecionam HTML. Payload não é selecionável. Não se trata de um objeto {type,options} de documento.
localeFormat"bcp47", "underscore" ou "android".O padrão geral é BCP-47; o formato Android usa a notação do Android.
targetPath, sourceRootStrings não vazias relativas ao repositório.Opcional; siga as regras de modelo de saída acima.
lockedKeys, preservedKeys, ignoredKeysArrays de strings não vazias que representam caminhos de chaves com notação de pontos ou colchetes.Quando omitidos, equivalem a []; os efeitos dependem do processador do formato. Não são opções JSONPath brutas de documento.
injectLocaleBooleano ou { "enabled": boolean, "key"?: nonempty string }.Quando omitido, desativa a injeção; quando ativada, a injeção usa language como padrão se key estiver ausente.
translateFrontmatterFieldsArray de strings não vazias.Para documentos da família Markdown, a omissão seleciona title, description; [] não seleciona nenhum campo.
translateComponentPropsArray de strings não vazias com nomes de propriedades ou de objetos com component opcional e um array props obrigatório e não vazio.component é uma string não vazia ou um array não vazio de strings não vazias; sua omissão remove o filtro por nome. O campo tem [] como padrão.

Por exemplo, uma entrada JSON pode incluir "lockedKeys": ["meta.id"], "preservedKeys": ["links.help"], "injectLocale": { "enabled": true, "key": "meta.locale" } junto com seu pattern. Uma entrada Markdoc pode selecionar o título de um componente com "translateComponentProps": [{ "component": "Callout", "props": ["title"] }]. A CLI aceita alguns valores vazios e emite avisos sobre alguns campos desconhecidos que o aplicativo rejeita; valide a configuração do aplicativo com base neste esquema.

Inspecione e recupere a primeira execução recorrente #

Use a verificação do GitHub e Execuções de workflow para localizar o repositório, a revisão de origem, o engine de localização, os arquivos selecionados, os idiomas e a branch de entrega. Compare esses dados com a alteração esperada e identifique onde o processamento parou:

ObservaçãoO que verificar antes de solicitar mais trabalho
A configuração da branch padrão está ausente, é inválida ou desativa o workflowNenhuma verificação ou comentário é publicado no GitHub. Corrija e faça commit do .lingo/config.json da branch padrão, incluindo as configurações de workflow desejadas.
A configuração da revisão de origem está ausente ou é inválida, mesmo após passar pelas verificações da branch padrãoA execução informa uma verificação com falha e, no fluxo de PR aplicável, também publica um comentário. Corrija o erro apontado na configuração de origem.
Nenhuma alteração de origem correspondente ou cobertura já existenteConfira os padrões e a cobertura selecionada; uma execução sem alterações não é uma falha de tradução.
Uma alteração no conteúdo de origem do PR não foi processada anteriormenteNa sincronização do PR, o workflow pode comparar o conteúdo com a base do PR para recuperar trabalho não identificado na comparação com a versão de origem imediatamente anterior. Confira em conjunto a origem na base, a origem atual e o destino.
Uma pessoa editou o destino do PRPara formatos com arquivos de destino separados, o processamento normal das diferenças do PR protege um destino alterado em relação à base quando o autor do commit mais recente não é o bot. Confira essa edição em vez de considerar a saída ignorada como trabalho pendente.
Alguns commits foram feitos antes de uma falha posteriorA saída pode ser registrada em commits por lotes. Vários commits podem pertencer à mesma execução, e a falha em um lote posterior não reverte os commits anteriores bem-sucedidos. Revise separadamente os caminhos entregues e as falhas restantes.

A saída é agrupada em commits com limite de 100 arquivos e limiar de agrupamento de 5 MiB. Uma falha posterior pode deixar os commits anteriores intactos. Revise os caminhos entregues e as falhas restantes antes de tentar novamente ou reverter a execução.

Desative os gatilhos aplicáveis para interromper o trabalho recorrente. Revogue o acesso ao repositório ou desinstale o aplicativo no GitHub quando ele não deva mais ter autorização para atuar no repositório. Os commits existentes, os pull requests aceitos e o consumo anterior permanecem; mantenha ou reverta o conteúdo entregue seguindo o processo habitual do repositório.

Colete atividades no Radar #

A conexão também envia ao Radar a atividade de commits do GitHub. Coletar traduções para medição explica a configuração dos eventos e como importar o histórico do provedor antes de executar uma medição histórica.