GitHub

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

A GitHub App da Lingo.dev integra os ficheiros traduzidos no histórico de alterações do seu repositório. Cria um commit com o conteúdo de origem e a configuração de tradução; a aplicação lê os ficheiros selecionados, traduz esses ficheiros através de um motor de localização e devolve as diferenças para a equipa analisar no GitHub.

No menu de navegação do Studio 2.5, abra Studio 2.5 → Integrações em vez de Definições → Integrações. As ligações existentes para ligar e configurar continuam a funcionar.

As alterações no ramo predefinido geram um pedido de integração com as traduções. Se ativar o processamento de pedidos de integração, as traduções são adicionadas ao ramo do próprio pedido. Esta página começa pelo workflow do ramo predefinido e separa a entrega das traduções da decisão de as integrar. Para executar a CLI no seu próprio executor, siga a receita do GitHub Actions.

Para que o seu agente de programação se possa ligar à aplicação, consulte Configurar com um agente de programação.

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

Na Lingo.dev, abra Definições → Integrações e selecione Ligar na integração com o GitHub. Associe a instalação da aplicação à sua organização e conceda acesso aos repositórios que pretende processar. Poderá ser necessária a aprovação de um administrador da organização no GitHub; o acesso aos repositórios respeita o âmbito selecionado na instalação.

Escolha um motor de localização a que tenha acesso na organização ligada. A configuração desse motor 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 a utilização do motor de localização.

Abra a ligação em Definições → Integrações para verificar a instalação e o estado da ligação. Gerir no GitHub abre as definições de acesso da instalação aos repositórios. No Studio, selecione um repositório em Ligados e utilize Execuções de workflow, em conjunto com a verificação e os commits do GitHub, para acompanhar uma alteração específica ao conteúdo de origem.

Se o Studio 2.5 estiver ativado para a sua organização, a barra lateral Conteúdo de origem apresenta os repositórios a que a instalação ligada tem acesso, sem ter de esperar por um evento do GitHub. Com um .lingo/config.json válido no ramo predefinido, pode abrir os ficheiros de origem JSON e JSONC configurados e as respetivas traduções existentes, sem criar um novo commit nem executar uma tradução. A consulta não consome créditos de tradução nem ativa a sincronização automática. Os repositórios sem configuração válida continuam visíveis; ao abrir os respetivos ficheiros, é apresentado o erro de configuração.

Crie .lingo/config.json na raiz do repositório. Este exemplo seleciona catálogos JSON em inglês em locales/en/ e gera ficheiros em francês nos caminhos locales/fr/ correspondentes. Substitua eng_example pelo ID do seu motor 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 }
  }
}

Concluir uma execução e verificar o resultado #

O exemplo exige aprovação antes de a tradução começar. Para o testar:

  1. Crie um commit com a configuração e uma pequena alteração ao conteúdo de origem no ramo predefinido, por exemplo, 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, consulte as regras de aprovação.
  3. Abra o pedido de integração com as traduções que a aplicação cria ou atualiza. Localize locales/fr/checkout.json e compare a mensagem alterada com o conteúdo de origem.
  4. Compile ou execute a aplicação com o ficheiro traduzido. Verifique a redação, as variáveis e a seleção do idioma. Depois, reveja e integre o pedido de integração de acordo com o processo habitual do seu repositório.

A aprovação no passo 2 autoriza o trabalho de tradução e o respetivo consumo. Não aprova a redação resultante nem integra o pedido de integração. Se faltarem resultados, consulte inspeção e recuperação para identificar a fase que ficou por concluir.

Adaptar a configuração à organização dos seus ficheiros #

Os padrões de origem devem selecionar apenas ficheiros de origem. Por exemplo, locales/en/**/*.json impede que os ficheiros em francês gerados sejam incluídos em pesquisas posteriores de ficheiros de origem. Os padrões são relativos ao repositório; os caminhos absolutos e .. são rejeitados. Cada entrada de ficheiro exige um pattern ou uma lista include. Uma configuração suporta até 100 entradas de ficheiro e 50 idiomas de destino distintos.

Por predefinição, o idioma de origem indicado num caminho determina onde são guardados os ficheiros de destino. Quando os caminhos não incluem um idioma, defina targetPath: [locale] indica o idioma de destino e [path] indica o caminho de origem após a remoção do prefixo opcional sourceRoot. Por exemplo, para francês, sourceRoot: "content" e targetPath: "translations/[locale]/[path]" mapeiam content/help/start.md para translations/fr/help/start.md. Um modelo baseado em padrões glob precisa de ambos os marcadores de posição. sourceRoot requer targetPath e tem de ser um prefixo dos caminhos de origem selecionados. Os formatos que reúnem vários idiomas num único ficheiro, como os catálogos de cadeias de texto do Xcode e CSV, não aceitam modelos de saída, pois as traduções permanecem no ficheiro original.

Utilize localeFormat quando a aplicação precisar de códigos de idioma BCP-47, separados por sublinhados ou no formato Android nos caminhos. Por predefinição, os recursos Android utilizam qualificadores Android. Confirme que o primeiro caminho de saída é compatível com o carregador da aplicação antes de adicionar mais idiomas.

Escolher quando traduzir e onde guardar os resultados #

O processamento de envios para o ramo predefinido está ativado por predefinição. O processamento de pedidos de integração está desativado por predefinição e tem de ser ativado explicitamente na configuração.

Adicione um .lingo/config.json válido ao ramo predefinido através de um commit antes de ativar o processamento de pedidos de integração. A aplicação lê o ID do motor, github.workflows e github.safety a partir dessa revisão de confiança do ramo predefinido. As alterações a essas definições num pedido de integração não autorizam a utilização de outro motor nem alteram a política de aprovação da própria execução. O idioma de origem, a seleção de ficheiros e os idiomas de destino são obtidos da revisão que está a ser traduzida.

GatilhoEntrega da tradução
Envio para o ramo predefinidoCria commits em lingo/translations/<default-branch> e abre ou atualiza um pedido de integração para o ramo predefinido.
Workflow de pedidos de integração ativadoCria commits com os resultados da tradução no ramo de origem do pedido de integração.
Comando de tradução num pedido de integraçãoGrava os resultados da tradução solicitada no ramo de origem desse pedido de integração.

A entrega em pedidos de integração exige um ramo de origem que permita escrita no repositório em que a aplicação está instalada. A aplicação ignora bifurcações e recusa gravar estes resultados diretamente no ramo predefinido.

A aplicação processa o trabalho do repositório em série e filtra os commits que ela própria gera para evitar que desencadeiem traduções repetidamente. Quando nenhum ficheiro de origem configurado foi alterado ou as traduções de destino já cobrem o trabalho solicitado, uma execução pode terminar sem diferenças. A respetiva 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.

Exigir aprovação antes de uma execução gerar custos #

github.safety.requireApproval tem o valor predefinido false. Defina o valor como true na configuração do ramo predefinido quando for necessário autorizar uma execução antes de a tradução começar. Nos envios para o ramo predefinido, a verificação apresenta os controlos Aprovar e Recusar. Nos pedidos de integração, a aplicação publica um comentário ao qual uma pessoa autorizada a fazer a revisão responde com /lingo approve.

Quando é exigida aprovação, uma falha na criação da verificação de auditoria bloqueia o workflow. Corrija o problema de criação da verificação ou de acesso antes de voltar a tentar aprovar.

Qualquer comando /lingo translate, com ou sem padrões glob de ficheiros, autoriza o trabalho que solicita e dispensa esta aprovação preliminar. Verifique os ficheiros e idiomas abrangidos antes de o publicar.

Executar comandos num pedido de integração #

Adicione um comentário a um pedido de integração aberto cujo ramo pertença ao repositório em que a aplicação está instalada e não seja o ramo predefinido. A aplicação lê a primeira linha do comentário que começa por /lingo. Utiliza o idioma de origem, as opções de ficheiros e os idiomas de destino da configuração do ramo de origem do pedido de integração, juntamente com o motor e as definições de segurança do ramo predefinido. Só quem tem acesso de escrita ao repositório pode iniciar a tradução.

ComandoEfeito
/lingo ou /lingo helpResponde com a lista de comandos.
/lingo translateTraduz as alterações ao conteúdo de origem deste pedido de integração e mantém as traduções que não foram alteradas. Substitui qualquer proposta de tradução ainda pendente do último envio.
/lingo translate --locales fr,esTraduz as alterações ao conteúdo de origem deste pedido de integração apenas para os idiomas indicados.
/lingo translate <glob>...Cria os ficheiros de destino em falta para os ficheiros de origem configurados que correspondem aos padrões glob.
/lingo translate <glob>... --forceRegenera os destinos correspondentes, substituindo as traduções existentes. --force exige pelo menos um padrão glob.
/lingo translate [<glob>...] --key <pattern>Volta a traduzir as chaves com nome correspondentes nas traduções existentes.
/lingo approveAprova a proposta de tradução pendente neste pedido de integração.

Sem padrões glob ou --key, um comando utiliza os ficheiros alterados pelo pedido de integração, pelo que é executado mesmo quando o processamento de pedidos de integração está desativado na configuração. Com padrões glob, utiliza os ficheiros do ramo, independentemente das alterações do pedido de integração. Os padrões glob são relativos à raiz do repositório, distinguem maiúsculas de minúsculas e abrangem apenas ficheiros selecionados por um pattern configurado. --locales aceita uma lista separada por vírgulas. A correspondência entre os códigos e os idiomas de destino configurados não distingue maiúsculas de minúsculas, e a resposta assinala qualquer código que não corresponda a nenhum deles.

Preencher traduções em falta num ficheiro ou idioma selecionado e Voltar a traduzir chaves com contexto explicam em detalhe as variantes com padrões glob e com chaves.

Preencher traduções em falta num ficheiro ou idioma selecionado #

Publique um comando de âmbito limitado num pedido de integração para solicitar a tradução de um ficheiro e de um idioma configurados:

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

Nos formatos com um ficheiro separado por idioma, este comando cria o ficheiro de destino em francês que está em falta. Não preenche chaves em falta num ficheiro de destino existente. Adicionar --force regenera os resultados selecionados sem reutilizar o conteúdo de destino existente, pelo que pode substituir alterações humanas já aceites. Limite a seleção de ficheiros e idiomas e, em seguida, reveja as diferenças resultantes.

Os catálogos de cadeias de texto do Xcode e os ficheiros CSV mantêm o conteúdo de origem e de destino num único ficheiro. Um comando simples com âmbito definido preenche as entradas de idioma em falta e preserva as existentes, mesmo quando o respetivo texto de origem foi alterado. Utilize /lingo translate sem um padrão de ficheiros para traduzir as alterações ao texto de origem no pedido de integração; esta operação pode substituir as traduções existentes das entradas alteradas, incluindo alterações feitas por pessoas. Adicione --force com uma seleção restrita de ficheiros e idiomas quando pretender gerar novamente as traduções existentes. Um comando forçado da aplicação reconstrói o conteúdo selecionado, preservando os idiomas fora do âmbito solicitado. Para atualizar através da CLI, siga o procedimento de correção de Catálogos de cadeias de texto ou CSV.

Voltar a traduzir chaves com contexto #

Utilize --key para voltar a traduzir chaves com nome selecionadas nas traduções existentes. Nos ficheiros JSON e JSONC, adicione --context para explicar o significado dessas chaves ou dar orientações sobre o tom e a utilização de maiúsculas e minúsculas nesta execução:

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

--context exige --key. Forneça o contexto uma única vez; será aplicado a todas as chaves e idiomas selecionados nos ficheiros JSON e JSONC. Os restantes formatos correspondentes são traduzidos sem esse contexto. Repita --key para vários padrões e utilize padrões glob de ficheiros ou --locales para restringir o pedido. Sem padrões glob de ficheiros, o comando seleciona todos os ficheiros de origem configurados. A correspondência das chaves pode ser exata, por prefixo ou por padrão glob; as traduções não relacionadas são preservadas. Os formatos sem chaves com nome e os idiomas sem traduções existentes são ignorados.

Os comandos de chaves da GitHub App também regeneram as cadeias de texto selecionadas que não foram alteradas em YAML e em YAML com idiomas na raiz. O workflow da CLI limitado a chaves tem um comportamento diferente de reutilização da versão de referência para esses formatos.

Mantenha o comando numa única linha. Coloque entre aspas simples ou duplas o contexto que contenha espaços; --context="button label" também funciona. Para incluir no texto uma aspa igual à usada como delimitador, coloque uma barra invertida antes dela, por exemplo --context "Use \"Save\" as a button label". O contexto é mantido com a execução para novas tentativas e para o histórico, mas não é guardado como instruções do motor nem herdado por execuções posteriores. As regras existentes do glossário, dos marcadores de posição e do formato de saída continuam a aplicar-se.

No contexto entre aspas, apenas \\ e uma barra invertida antes da aspa delimitadora são descodificados. Os marcadores de posição como $name e ${name}, as sequências como \n e a pontuação mantêm o seu valor literal.

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

A aplicação é compatível com catálogos estruturados, documentos da família Markdown, HTML, legendas, texto simples, tabelas CSV, ficheiros de propriedades Java e recursos de plataforma. A secção Formatos descreve os processadores de cada formato. Payload não é um formato de ficheiro que possa selecionar no GitHub.

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

Selecione ficheiros de texto simples com um padrão que termine em .txt, como metadata/en/*.txt, ou com "format": "txt". Um ficheiro .txt só pode pertencer a uma entrada desse tipo, e uma entrada com "format": "txt" seleciona apenas ficheiros .txt. Assim, um padrão abrangente como docs/en/**/* ignora LICENSE.txt, e uma entrada abrangente com txt ignora as imagens que se encontram junto do texto. Texto simples traduz cada linha no respetivo local.

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

Selecione os ficheiros de propriedades Java da mesma forma, com um padrão que termine em .properties, como src/main/resources/messages_en.properties, ou com "format": "properties", para que um padrão abrangente como src/main/resources/**/* ignore application.properties. Um ficheiro de origem com o nome messages_en.properties dá origem a ficheiros de destino como messages_de.properties. O processador de propriedades Java traduz cada valor no respetivo local, preserva os comentários e a formatação e faz a correspondência de lockedKeys, preservedKeys, ignoredKeys e lockedPatterns, tal como a CLI anterior.

Num documento, selecione os campos dos metadados iniciais e as propriedades dos componentes que contêm texto traduzível. Num catálogo semelhante a JSON, utilize caminhos bloqueados para copiar os valores de origem, caminhos preservados para manter os valores de destino existentes e caminhos ignorados para omitir valores da saída. Estas opções permitem que um catálogo contenha texto, identificadores e ligações 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 das entradas de ficheiro #

Coloque os campos seguintes diretamente num objeto da matriz files de .lingo/config.json, e não dentro de options. A aplicação valida rigorosamente os campos de raiz, as entradas de ficheiro, as definições do GitHub, as regras de componentes e os objetos de injeção de idioma. Ignora a secção opcional i18n e aceita campos adicionais nessa secção. O esquema legível por máquina está disponível em GET https://api.lingo.dev/github-app/schema.json.

CampoEstrutura aceitePredefinição ou âmbito
pattern / includeCadeia de texto não vazia relativa ao repositório / matriz não vazia dessas cadeias de texto.É necessário pelo menos um; quando fornecido, include tem prioridade sobre pattern. Os padrões não podem começar por / nem conter ...
excludeMatriz de padrões não vazios relativos ao repositório.Opcional; aplica-se a esta entrada.
formatCadeia de texto que indica o formato configurado, incluindo "html".Pode ser inferido se for omitido; .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".A predefinição habitual é BCP-47; o formato Android implica a representação Android.
targetPath, sourceRootCadeias de texto não vazias relativas ao repositório.Opcional; siga as regras dos modelos de saída indicadas acima.
lockedKeys, preservedKeys, ignoredKeysMatrizes de cadeias de texto não vazias com caminhos de chaves em notação de pontos ou parênteses retos.Se for omitido, assume []; os efeitos dependem do processador do formato. Não se trata das opções JSONPath do documento em bruto.
injectLocaleBooleano ou { "enabled": boolean, "key"?: nonempty string }.Se for omitido, a injeção fica desativada; quando ativada, assume language por predefinição se key estiver ausente.
translateFrontmatterFieldsMatriz de cadeias de texto não vazias.Nos documentos da família Markdown, a omissão seleciona title, description; [] não seleciona nenhum.
translateComponentPropsMatriz de cadeias de texto não vazias com nomes de propriedades ou de objetos com component opcional e uma matriz props obrigatória e não vazia.component é uma cadeia de texto não vazia ou uma matriz não vazia de cadeias de texto não vazias; a omissão remove o filtro de nomes. O valor predefinido do campo é [].

Por exemplo, uma entrada JSON pode incluir "lockedKeys": ["meta.id"], "preservedKeys": ["links.help"], "injectLocale": { "enabled": true, "key": "meta.locale" } juntamente com 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 a aplicação rejeita; valide a configuração da aplicação com base neste esquema.

Inspecionar e recuperar a primeira execução recorrente #

Utilize a verificação do GitHub e Execuções de workflow para identificar o repositório, a revisão de origem, o motor de localização, os ficheiros selecionados, os idiomas e o ramo de entrega. Compare estes elementos com a alteração esperada e identifique onde o processamento parou:

ObservaçãoO que verificar antes de solicitar mais trabalho
A configuração do ramo predefinido está em falta, é inválida ou desativa o workflowNão é publicada qualquer verificação ou comentário no GitHub. Corrija o .lingo/config.json do ramo predefinido e crie um commit com essa correção, incluindo as definições de workflow pretendidas.
A configuração da revisão de origem está em falta ou é inválida, apesar de as verificações do ramo predefinido terem sido concluídas com êxitoA execução apresenta uma verificação com falha e, no workflow de PR aplicável, um comentário. Corrija o erro indicado na configuração de origem.
Não há alterações de origem correspondentes ou as traduções já cobrem o trabalho solicitadoInspecione os padrões e a cobertura selecionada; uma execução sem alterações não é uma tradução falhada.
Uma alteração 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 que a comparação com o conteúdo de origem imediatamente anterior não detetou. Inspecione em conjunto o conteúdo de origem de base, o conteúdo de origem atual e o destino.
Uma pessoa editou o destino do PRNos formatos com ficheiros de destino separados, o processamento habitual das diferenças do PR protege um destino alterado face à base quando o autor do commit mais recente não é o robô. Inspecione essa alteração em vez de considerar os resultados ignorados como trabalho em falta.
Foram criados alguns commits antes de uma falha posteriorOs resultados podem ser gravados em commits por lotes. Vários commits podem pertencer à mesma execução, e a falha de um lote posterior não reverte os commits anteriores bem-sucedidos. Reveja separadamente os caminhos entregues e as falhas restantes.

Os resultados são agrupados em commits com um limite de 100 ficheiros e um limiar de agrupamento de 5 MiB. Uma falha posterior pode deixar os commits anteriores intactos. Reveja os caminhos entregues e as falhas restantes antes de repetir ou reverter a execução.

Desative os gatilhos aplicáveis para interromper o trabalho recorrente. Revogue o acesso ao repositório ou desinstale a aplicação no GitHub quando esta já não deva ter autorização para atuar no repositório. Os commits existentes, os pedidos de integração aceites e o consumo anterior mantêm-se; mantenha ou reverta o conteúdo entregue de acordo com o processo habitual do seu repositório.

Recolher atividade no Radar #

A ligação também fornece ao Radar a atividade de commits do GitHub. Recolher traduções para medição descreve a configuração dos eventos e explica como importar o histórico do fornecedor antes de executar uma medição histórica.