Tradução

O Docsbook publica sua documentação em quinze códigos de idioma. Você não precisa escrever, armazenar ou manter arquivos de tradução: basta ativar um idioma, e o Docsbook traduz as páginas diretamente do Markdown já presente no seu repositório, publica cada idioma em seu próprio caminho de URL e traduz novamente uma página quando um commit a altera.

Documentação traduzida por máquina geralmente é um risco — identificadores de código distorcidos, terminologia que varia entre páginas, traduções que se deterioram silenciosamente quando o conteúdo de origem avança e URLs de localidade que prejudicam sua presença nas pesquisas em vez de ampliá-la. O restante desta seção explica como o pipeline do Docsbook lida especificamente com cada um desses problemas e quais limitações ainda permanecem.

O que abrir um idioma proporciona#

Três coisas concretas, todas as quais você pode verificar por conta própria.

Um conjunto separado de URLs com que uma consulta nesse idioma pode corresponder. Cada idioma é um caminho de URL distinto, renderizado como HTML estático, listado no seu sitemap e com sua própria entrada hreflang. Uma página somente em inglês não pode corresponder a uma consulta em espanhol, por melhor que seja sua classificação; uma página em espanhol pode. A própria orientação do Google é que páginas traduzidas são como você se torna elegível para esse público — não um problema de conteúdo duplicado — e o Docsbook cria o cluster hreflang por página, e não por site, para que o cluster que publica seja aceito pelo Google. O mecanismo e a forma como ele falha quando é implementado sem cuidado estão em Qualidade da tradução e SEO.

Pesquisa no site que funciona no idioma do leitor. Quando uma página é traduzida, o texto traduzido é indexado para pesquisa de texto completo sob o código desse idioma, não apenas o original em inglês. Um leitor que pesquisa em alemão encontra páginas em alemão.

Documentação que um assistente pode citar nesse idioma. O mesmo HTML estático que um rastreador lê é recuperado por um assistente de IA. A tradução amplia a cobertura de GEO para os idiomas que você abre, pois agora existe uma página nesse idioma para ser citada.

Quanto custa#

Esforço. Ativar um idioma consiste em marcar uma caixa de seleção e confirmar em uma caixa de diálogo. Não há etapa de exportação, arquivos .po, chaves nem conta de fornecedor. Corrigir uma frase específica depois disso é uma edição no painel de Traduções ou uma chamada upload_translation — consulte o fluxo de correção.

Dinheiro. Traduzir consome o saldo de IA do seu projeto; exibir uma página já traduzida para um leitor não custa nada. Uma página é dividida em seções identificadas pelo hash do conteúdo, portanto editar um parágrafo faz com que essa seção seja retraduzida, enquanto o restante é reutilizado do cache. O Docsbook informa o custo da execução antes da confirmação e interrompe o processo, em vez de gastar além do saldo, quando ele se esgota. A tradução automática e as ferramentas do fluxo de trabalho de tradução fazem parte do plano pago — consulte Preços.

Atenção. Este é o custo que a maioria das equipes subestima. A tradução automática de prosa técnica é boa o suficiente para ser publicada, mas não boa o suficiente para ser ignorada: a deriva terminológica e a tradução excessiva de termos específicos do domínio são os modos de falha documentados, e as políticas de spam do Google consideram a tradução automática não revisada um risco para o seu site, não um ato neutro. Qualidade da tradução e SEO explica o que o Docsbook mede, o que não mede e o que você deve revisar.

Nesta seção#

Limites e questões em aberto#

• Quinze códigos de idioma, e apenas estes. en, es, fr, de, pt, it, ru, zh, ja, ko, ar, hi, tr, pl, nl. Um deles é o idioma de origem do próprio projeto, que nunca é um destino de tradução — portanto, um projeto em inglês tem quatorze destinos. Variantes regionais (pt-BR em comparação com pt-PT, zh-Hans em comparação com zh-Hant) não são opções separadas.
• O Docsbook não publica nenhuma pontuação de qualidade da tradução. Não há nenhuma métrica BLEU, COMET ou avaliação humana para suas páginas, e esta documentação não afirma que exista uma. O que o produto mede é cobertura e atualidade — quantas páginas existem em cada idioma e quantas foram traduzidas a partir da versão atual da fonte. Considere “a tradução é boa” como uma avaliação a ser feita por você, com base nas evidências em Qualidade da tradução e SEO.
• A tradução automática é um recurso pago, assim como a configuração de idiomas relacionada a ela. Um projeto gratuito vê as configurações e tem seu idioma de origem detectado automaticamente quando se conecta, mas não pode alterar os idiomas habilitados nem o idioma de origem, definir o modo de tradução ou executar uma rodada. Consulte Preços.
• O pipeline traduz páginas Markdown do seu repositório. Ele não é um sistema de localização de strings da interface, nem traduz as descrições de campos de uma especificação OpenAPI.

Relacionado#

• SEO — o que o Docsbook emite para os motores de busca em cada página, traduzida ou não
• GEO — ser citado por um assistente de IA em vez de ser classificado
• Relatório de países dos visitantes — quais regiões chegam para as quais você ainda não traduz
• Conteúdo & Configuração — como as páginas chegam ao Docsbook em primeiro lugar