Qualidade da tradução e SEO

Esta é a página onde a afirmação é verificada. Ela aborda o que o Docsbook realmente mede sobre uma tradução, como corrigir uma, o que os mecanismos de pesquisa e os assistentes de IA fazem com a documentação traduzida e — no final — o que a tradução automática ainda faz de errado na prosa técnica, com uma fonte.

O que o Docsbook mede e o que ele não mede#

O Docsbook não publica nenhuma pontuação de qualidade da tradução. Não há nenhuma métrica BLEU, COMET, TER ou avaliação humana para suas páginas, e esta documentação não inventará uma. Em vez disso, o produto mede cobertura e atualidade: se uma página existe em um idioma e se foi criada a partir da versão da fonte que está publicada no momento.

Essa é uma afirmação mais restrita do que "nossas traduções são boas", e é a que pode ser verificada.

Cobertura e atualização#

Cada tradução armazenada mantém o SHA do blob Git do arquivo de origem a partir do qual foi feita. A cobertura é calculada lendo a árvore do seu repositório em HEAD e comparando por caminho:

A cobertura é (current + manual) / total. Um idioma está sincronizado quando behind e missing são ambos zero. Quando não é possível ler seu repositório, a cobertura é null — nunca um zero afirmativo —, portanto uma leitura do GitHub limitada por taxa nunca pode marcar em vermelho um idioma saudável.

Lendo isso#

• No painel. Cada idioma tem sua própria página: uma porcentagem de cobertura sobre uma barra dividida pelo tipo de lacuna, o commit em que sua documentação está atualmente, uma barra de progresso ao vivo indicando quem iniciou a execução em andamento, as últimas doze execuções coloridas de acordo com a forma como cada uma terminou e — quando uma execução foi interrompida antes do fim — o motivo em palavras. Abaixo disso, seus commits, do mais recente para o mais antigo, cada um com um veredito sobre a situação de suas páginas nesse idioma, para que “a reescrita dos preços foi publicada na terça-feira” seja algo que você possa verificar, em vez de um nome de arquivo que precise decifrar.
• Por meio do MCP. get_translation_status retorna exatamente isto para cada idioma: current / behind / missing / manual / orphaned, a porcentagem, in_sync, se há uma execução em andamento e até onde ela avançou, e o que a última execução fez — incluindo qual execução do agente a iniciou. A própria descrição da ferramenta orienta o chamador a lê-la antes de run_translation_pass, porque traduzir novamente um idioma que já está alinhado com a fonte custa dinheiro e não muda nada.
• Por webhook. translation.needed é acionado quando uma página em um idioma habilitado está prestes a ser traduzida, translation.completed quando ela é efetivamente publicada, e translation.outdated quando uma tradução fica atrás da fonte. translation.completed é acionado somente quando a página foi realmente persistida, portanto um listener que reindexa um CMS nunca é informado sobre uma tradução que não existe.

A única métrica que é uma comparação, não uma medição#

A métrica de Economia no painel de Traduções calcula quanto um tradutor humano teria cobrado pelos mesmos caracteres, a uma taxa de $5,00 por 1.000 caracteres, menos o custo efetivo da tradução por IA. Duas observações sobre ela:

• Ela é calculada por caractere, não por palavra, deliberadamente. A contagem de palavras é uma propriedade do idioma de destino — chinês e japonês não têm palavras delimitadas por espaços em branco — portanto, uma métrica por palavra fica próxima de zero justamente para os idiomas que deveria medir.
• É um contrafactual, não uma fatura. Ninguém recebeu nenhum dos dois valores. A taxa é uma constante fixa no Docsbook, não um orçamento que você recebeu. Interprete o valor como uma ordem de grandeza.

Posso corrigir uma tradução, e a correção será preservada?#

Você pode corrigir uma, e a correção fica protegida contra ser sobrescrita por uma execução posterior — essa parte é garantida pela própria gravação no banco de dados. Se os leitores receberão então o seu texto corrigido é uma questão separada, e a resposta honesta está abaixo.

Como corrigir uma. Edite a tradução no painel Traduções ou envie-a com upload_translation. Os uploads chegam como rascunho; list_pending_translations mostra os rascunhos e approve_translation publica um deles. Editar o conteúdo de uma tradução marca a linha como um upload manual.

Por que ela sobrevive a uma execução. As execuções automáticas gravam por meio de um upsert do banco de dados cuja cláusula de conflito só sobrescreve linhas cuja origem é docsbook_ai. Uma linha marcada como upload manual é ignorada por essa gravação, e a cobertura a contabiliza como manual — um estado que nunca está "atrasado", porque a atualidade de uma página escrita por uma pessoa é uma decisão dessa pessoa, não de uma comparação de hashes. Substituir uma tradução de IA ativa dessa forma também retorna replaced_ai_translation: true ao chamador, para que um agente possa avisar a uma pessoa que acabou de substituir algo que os leitores já estavam vendo.

Em análise. A documentação do Docsbook afirmou que, depois que você envia uma correção, "o Docsbook passa a fornecer a sua versão". O que é verificável: a linha corrigida é armazenada, nunca é sobrescrita por uma execução automática posterior (a cláusula de conflito do upsert só grava sobre linhas cuja origem é docsbook_ai) e é contabilizada como manual na cobertura, em vez de estar desatualizada. O que não é: que ela seja fornecida aos leitores. Analisando o código como ele está, três pontos indicam o contrário. A página voltada ao leitor lê uma tradução do cache quente e, em caso de ausência, das linhas armazenadas filtradas por origin = 'docsbook_ai'. O mesmo filtro decide se uma localidade pertence ao agrupamento hreflang desta página e se sua URL entra no sitemap. E o caminho de invalidação do cache afirma explicitamente que as linhas manuais e externas "nunca gravam chaves de página do Redis SSR", portanto também não há uma cópia em cache para a primeira leitura encontrar. Uma linha enviada manualmente ou editada à mão não corresponde a nada disso. Não publicamos nenhuma medição de uma página corrigida sendo fornecida, e o mecanismo, conforme escrito, não prevê que isso aconteça — portanto, trate os uploads manuais como uma forma de proteger uma página contra uma nova tradução e de alimentar um pipeline externo, não como uma forma de mudar o que um leitor vê. Se uma frase específica estiver errada para você hoje, a correção confiável é alterar a página de origem e deixar que a execução a traduza novamente.

Esse é exatamente o tipo de afirmação que nossa regra de evidências exige que marquemos, em vez de simplesmente excluí-la.

O que os mecanismos de pesquisa fazem com a documentação traduzida#

URLs separadas por idioma e um cluster hreflang por página#

Cada idioma tem seu próprio caminho de URL — nunca um subdomínio, nunca um parâmetro de consulta. Além disso, cada página de documentação emite um conjunto hreflang como alternates <link rel="alternate">, além de x-default e en apontando para a URL no idioma original.

A regra que faz isso funcionar é a reciprocidade, e ela é aplicada por página, não por site:

O Docsbook constrói o canonical e os alternates a partir da mesma função que roteia a URL, portanto o endereço anunciado é aquele que responde com 200, e não um que redireciona — um canonical que aponta para um redirecionamento é resolvido pelo Google descartando a página.

Mais um mecanismo se baseia na mesma regra. O Google afirma claramente que "usa o conteúdo visível da sua página para determinar o idioma" e que "não usamos nenhuma informação de idioma no nível do código, como atributos lang ou a URL" — portanto, uma página totalmente traduzida que ainda envia um <title> em inglês está transmitindo seu sinal mais forte na página no idioma errado. O Docsbook recupera o título do HTML traduzido que já armazenou, lendo o próprio <h1> traduzido dessa página, sem nenhuma chamada adicional ao modelo. A meta description é deliberadamente mantida como a original nesse caso: inventar uma tradução para ela não é algo que uma compilação de metadados possa fazer, e um título correto sobre uma descrição no idioma original é melhor do que ambos estarem errados.

Por que cada uma dessas regras é a correta#

Observe o que a penúltima linha implica sobre tags válidas: es-419 é uma tag BCP 47 perfeitamente válida — a W3C a usa como exemplo prático — e o Google explicitamente não a aceita em hreflang. Tag de idioma válida e valor hreflang válido não são o mesmo conjunto.

A tradução automática viola as regras do Google?#

Não — e a resposta é mais específica do que qualquer um dos lados do argumento habitual, por isso vale a pena entendê-la exatamente.

Páginas traduzidas não são duplicatas. O Google estabelece o limite em uma frase: "As versões localizadas de uma página só são consideradas duplicatas se o conteúdo principal da página permanecer sem tradução." Uma página totalmente traduzida é uma página distinta. Uma URL de localidade que exibe o corpo original é uma duplicata — e é por isso que os canônicos do Docsbook direcionam esse caso para o original, em vez de publicá-lo como uma alternativa. E, sobre duplicação em geral, a posição histórica do Google é que "Conteúdo duplicado em um site não é motivo para tomar medidas contra esse site, a menos que pareça que a intenção do conteúdo duplicado seja enganar e manipular os resultados dos mecanismos de pesquisa" (Desmistificando a penalidade por conteúdo duplicado, 2008).

A antiga regra de que "tradução automática é spam" deixou de existir. As políticas de spam do Google não contêm nenhum item sobre tradução automática — as expressões "machine translation" e "automatically translated" não aparecem na página. O que existe é o abuso de conteúdo em escala, definido como "criar grandes quantidades de conteúdo não original que ofereça pouco ou nenhum valor aos usuários, independentemente de como é criado". A palavra traduzir aparece apenas em um exemplo de cópia de conteúdo nessa mesma política: "Copiar feeds, resultados de pesquisa ou outro conteúdo para gerar muitas páginas (inclusive por meio de transformações automatizadas, como substituir por sinônimos, traduzir ou usar outras técnicas de ofuscação), quando pouco valor é oferecido aos usuários". O changelog do Google registra a atualização em 11 de junho de 2025: "Removemos uma seção da nossa documentação multilíngue sobre o uso de robots.txt para bloquear todas as páginas traduzidas automaticamente", "Para alinhar com a atualização da nossa política de spam de março de 2024" (Atualizações da documentação do Search Central).

A posição atual depende da qualidade, não do método. Quando perguntado diretamente se a tradução automática prejudica o posicionamento, Gary Illyes respondeu "se a tradução automática for de baixa qualidade, talvez" e recomendou que os sites "garantam que uma pessoa nativa desses idiomas revise (e talvez corrija) as traduções". Na mesma sessão, John Mueller observou que "não há nenhuma marcação especial que você possa adicionar às suas páginas" para declarar que uma tradução foi feita por máquina, que o teste é saber se "as páginas estão bem traduzidas", que "uma boa localização é muito mais do que apenas uma tradução de palavras e frases" e que uma saída de baixa qualidade é um caso em que "você poderia simplesmente incluir a meta tag robots noindex nelas" (Google SEO Office Hours, junho de 2024).

A interpretação prática para uma equipe de documentação:

• O que é penalizado é o volume sem valor, não a ferramenta. Traduzir cem páginas de documentação de que seus leitores realmente precisam não é abuso de conteúdo em escala; gerar páginas de localidades que ninguém solicitou é.
• A revisão é a variável mencionada pelo Google. O Docsbook oferece as ferramentas — a página de cobertura por idioma, list_pending_translations com approve_translation e o modo external para encaminhar cada página pelo seu próprio pipeline antes da publicação — e não obriga você a usá-las. O modo auto publica à medida que avança. Escolha conscientemente.
• A revisão útil mais econômica não é revisar todas as páginas. São as páginas que geram mais impacto: o início rápido, qualquer conteúdo relacionado a preços, as páginas mais acessadas nas suas análises para esse idioma e qualquer página em que uma instrução traduzida incorretamente prejudique a configuração do leitor. Se um idioma apresenta uma leitura ruim e você não pretende corrigi-la, noindex é uma resposta válida.

O que os assistentes de IA fazem com eles#

Nada de especial, e esse é o objetivo. Um mecanismo generativo recupera o mesmo HTML estático que um crawler lê. Abrir um idioma cria páginas nesse idioma para um assistente recuperar e citar quando a pergunta é feita nesse idioma — algo que um corpus somente no idioma original não pode fazer. O Docsbook também indexa o texto traduzido para pesquisa de texto completo no site usando o código desse idioma, de modo que um leitor que pesquisa em alemão encontre páginas em alemão em vez da fonte em inglês. Consulte GEO para saber o que é adicionado à própria página.

Limitações — o que a tradução automática ainda traduz incorretamente em documentação técnica#

Leve esta seção tão a sério quanto o restante da página.

• A consistência da terminologia não é gerenciada, e este é o ponto fraco mensurável de todo o campo. O Docsbook não tem glossário, base de termos nem lista de termos que não devem ser traduzidos que você possa fornecer. A consistência vem de três fontes mais fracas: as solicitações são executadas com temperatura 0, uma seção não editada é fornecida literalmente a partir do cache e, portanto, não pode sofrer alterações, e os rótulos de navegação e o título/descrição são traduzidos como conjuntos. Duas páginas diferentes que usam o mesmo termo foram traduzidas de forma independente e podem divergir.

  O quanto isso importa foi mensurado. Moslem et al. ("Integração de terminologia de domínio na tradução automática: aproveitando modelos de linguagem grandes", WMT 2023, arXiv:2310.14451) relatam que, nos conjuntos cegos DE-EN, EN-CS e ZH-EN, "o número de termos incorporados às traduções do conjunto de dados cego aumenta de uma média de 36,67% com o modelo genérico para uma média de 72,88% ao final do processo" — "a utilização bem-sucedida dos termos praticamente dobra entre os três pares de idiomas". Leia a métrica com precisão: ela conta se o termo exigido foi usado, e 72,88% é o resultado final de um processo de quatro etapas criado para essa finalidade, não de um modelo mais forte por si só.

  A tarefa compartilhada de terminologia WMT25 quantifica o outro lado da mesma moeda. Seus dados da Faixa 1 foram produzidos pela SAP a partir de seu portal de ajuda online (EN→DE/RU/ES, 500 instâncias de teste por par de idiomas, 20 sistemas de 13 equipes), e "sistemas fortes alcançam uma precisão terminológica muito alta, acima de 97%" — somente quando o glossário correto é fornecido ao sistema no momento da inferência, que é precisamente a entrada que o Docsbook não possui. A tarefa também executa os mesmos sistemas com um dicionário aleatório e sem nenhum: o sistema líder obtém 99,1 com o glossário adequado, 49,2 com um aleatório e 44,4 sem nenhum. Em textos mais longos, relata que "os sistemas frequentemente ficam aquém" e que "a tarefa no nível de documento continua sendo mais desafiadora". Interprete isso da seguinte forma: a fidelidade terminológica é projetada, não herdada, e o Docsbook ainda não a projetou.

  A formulação geral é a mesma. A tarefa de tradução geral WMT24 (Kocmi et al.), que coletou traduções de "8 modelos de linguagem grandes (LLMs) diferentes e 4 provedores de tradução online" em 11 pares de idiomas, tem o título "A era dos LLMs chegou, mas a TA ainda não está resolvida". Seus domínios são notícias, literatura, fala e redes sociais — não documentação técnica — portanto, cite-a para "não resolvida" e cite as duas fontes acima para qualquer afirmação sobre textos de domínio. Seus conjuntos de testes realmente relatam fragilidade em terminologia, mas de forma restrita: a frase trata de uma direção e um sistema, "Para inglês-russo, o Yandex é mais fraco em entidades nomeadas e terminologia", e não é uma descoberta sobre tradução por LLMs em geral.

• Identificadores isolados em prosa são protegidos apenas por uma instrução. O código dentro de cercas e crases é removido da solicitação e restaurado byte a byte — isso é mecânico. Um nome de parâmetro escrito como prosa comum, sem crases, chega ao modelo e permanece no idioma de origem somente porque o prompt determina isso. Marcar identificadores como código é a medida de maior valor que você pode tomar para suas próprias traduções. Procuramos uma medição publicada sobre a frequência com que a tradução por LLMs distorce especificamente identificadores de código e não encontramos nenhuma; a evidência publicada mais próxima é o trabalho sobre terminologia citado acima. Considere o tamanho desse risco como não mensurado, e não como pequeno.

• O texto de imagem alt não é traduzido. Ele é um atributo HTML, e a regra que protege href e id também protege alt.

• O Docsbook não publicou nenhuma medição própria. Nenhum índice de precisão, nenhuma taxa de erro, nenhuma classificação por idioma. Se você precisar de uma para seu corpus, a maneira honesta de obtê-la é pedir que um leitor fluente revise uma amostra de suas próprias páginas — e a cobertura indica quais páginas vale a pena amostrar.

• O modelo pode mudar sem que você perceba. O modelo de tradução padrão é uma constante de configuração, e o seletor permite alterá-lo. Uma página traduzida no mês passado foi traduzida pelo modelo selecionado naquele momento; nada traduz novamente uma página porque o modelo melhorou.

• As variantes regionais não são modeladas. Um pt para o Brasil e Portugal, um zh para Simplificado e Tradicional. Para produtos em que essa distinção gera vendas, isso é uma limitação real, e não um erro de arredondamento.

Relacionado#

• Traduções por IA — o próprio pipeline: divisão em partes, proteção e tratamento de falhas
• Configurações de tradução — ativação de um idioma, o modelo, o modo e URLs de localidade
• SEO — URLs canônicas, sitemap e dados estruturados em todas as páginas
• GEO — o que torna uma página citável por um assistente
• Como o Docsbook comprova o que afirma — a regra segundo a qual esta página é escrita