Configurações de tradução

Esta página é a superfície de configuração: quais idiomas existem, qual modelo os traduz, quando as execuções ocorrem, onde os leitores alternam o idioma e qual é a aparência de cada URL traduzida. Como uma execução funciona na prática está explicado em Traduções com IA; se o resultado é bom está explicado em Qualidade da tradução e SEO.

A tradução automática e os controles do fluxo de trabalho de tradução fazem parte do plano pago — consulte Preços. Um projeto gratuito pode visualizar tudo nesta página, e seu idioma de origem ainda é detectado automaticamente quando o projeto se conecta. O que ele não pode fazer é alterar nada disso: os idiomas habilitados e o idioma de origem fazem parte de um único grupo limitado pelo plano, portanto, um projeto gratuito tem ambas as funcionalidades recusadas, assim como o modo de tradução e o início de uma execução.

O que pode ser configurado#

Idioma de origem do seu projeto#

O Docsbook detecta o idioma em que sua documentação está escrita, em vez de perguntar a você. Quando um projeto se conecta, ele lê o README do repositório, remove blocos de código, código embutido, imagens, links e HTML dele, e executa um identificador de idioma sobre o que resta.

As regras relevantes:

• Com menos de 50 caracteres de prosa após a remoção, ou sem uma resposta confiável, o sistema recorre a en e registra o resultado com baixa confiança, para que o painel possa identificá-lo como melhor estimativa — confirme, em vez de apresentar uma suposição como uma detecção. Uma detecção confiante é registrada com alta confiança e identificada como detectado automaticamente. Defini-lo por conta própria faz com que seja identificado como definido por você e fixa o idioma.
• O detector reconhece exatamente os quinze códigos compatíveis com o Docsbook. Um README em um idioma fora desse conjunto recorre ao fallback en.
• O idioma de origem nunca pode ser ativado como destino de tradução. Ele é removido de enabled_languages se você o informar, e uma etapa de tradução o ignora explicitamente — antes mesmo de verificar se o idioma está ativado — com o motivo is_source_language. Isso é uma proteção estrutural, não uma validação da interface: uma linha obsoleta no banco de dados ou uma chamada direta à API não pode fazer um projeto pagar para traduzir inglês para inglês.
• O inglês não é especial. Um projeto cuja documentação está escrita em alemão obtém a imagem espelhada de tudo o que foi descrito acima.

Ativando um idioma#

1. Abra seu site de documentação.
2. Float Widget → aba Tradução.
3. Marque o idioma desejado.
4. Confirme a caixa de diálogo. O processo começa em segundo plano.

Se o alternador de idioma já estiver no seu site, abri-lo e pressionar Ativar idiomas leva à mesma aba. Esse ponto de entrada aparece apenas para você, como proprietário, ou na pré-visualização de administrador — nunca para os leitores.

Ativar um idioma, por si só, não traduz nada no nível da API: update_languages define o conjunto, e run_translation_pass (ou o próprio gatilho do modo) faz o trabalho. No painel, os dois são combinados para você, portanto marcar uma caixa inicia um processo.

A caixa de diálogo apresenta primeiro o orçamento da execução#

Antes de qualquer valor ser gasto, a caixa de diálogo de confirmação mostra quantas páginas ainda não foram traduzidas do total, o custo estimado e o saldo restante. Se a execução não couber no saldo, ela informa qual parte da documentação o seu saldo cobre e oferece uma recarga — e Traduzir o que couber é uma opção real: as páginas que couberem são traduzidas agora e o restante é processado automaticamente quando o saldo permitir.

A estimativa é calculada com base no modelo selecionado, portanto o orçamento e a cobrança referem-se ao mesmo modelo. Isso precisa ser dito explicitamente porque antes não era assim: a estimativa usava o preço de um modelo, enquanto a execução usava outro.

Escolhendo o modelo de tradução#

Configurações ▸ Traduções ▸ Modelo de tradução seleciona o modelo, e essa é deliberadamente uma configuração diferente daquela em que o chat do leitor é executado — traduzir prosa e responder a uma pergunta com ferramentas são tarefas diferentes, e uma medição que altera uma delas não tem motivo para alterar a outra.

Não selecione nada e você obterá o padrão marcado como (default) no seletor, atualmente GPT-5.6 Luna. Cada opção mostra seu preço por 1 milhão de tokens, portanto um modelo mais barato faz o saldo render por mais páginas, enquanto um modelo mais potente está a um clique de distância quando um idioma apresenta problemas de leitura. Somente os modelos do catálogo do Docsbook são aceitos no modo gerenciado, porque os gastos são cobrados pelo preço publicado do modelo e um modelo não reconhecido seria cobrado a uma taxa que nunca foi apresentada a você.

Se você trouxer sua própria chave de API de tradução, o modelo se tornará um campo de texto livre nesse cartão, e a execução será cobrada pelo seu próprio provedor, em vez do saldo do seu projeto. Trazer sua própria chave não desbloqueia a tradução em um projeto gratuito: o acesso é uma decisão do plano, não uma questão de custo.

Escolha quando as traduções são executadas#

No modo Automático, o Docsbook consulta seu repositório em vez de reagir a um webhook: um espaço de trabalho é verificado aproximadamente a cada 15 minutos, e apenas quatro espaços de trabalho são examinados por ciclo, portanto espere que uma atualização comece dentro desse intervalo, e não no instante em que você faz o push. As páginas que ficaram atrasadas são traduzidas antes das páginas que nunca foram traduzidas — uma tradução desatualizada está informando ativamente ao leitor algo que sua documentação já não diz, enquanto uma tradução ausente recorre ao original e apenas deixa de ajudar.

Os agentes definem o modo com a ferramenta MCP set_translation_mode:

// auto: Docsbook follows new commits and re-translates the pages they changed
set_translation_mode({ workspace_id: 42, mode: "auto" })
 
// external: nothing runs here; your pipeline listens for translation.needed
set_translation_mode({ workspace_id: 42, mode: "external", external_webhook_url: "https://example.com/hooks/translate" })

No modo external, você recebe um evento translation.needed, executa seu próprio pipeline e publica o resultado novamente com upload_translation. Definir external sem nunca ter fornecido uma URL de webhook é recusado, em vez de ser aceito silenciosamente.

Posicionamento do seletor de idioma#

O seletor pode aparecer na barra lateral, no cabeçalho ou em ambos. O posicionamento no cabeçalho é uma configuração própria do espaço de trabalho; a barra lateral também pode ser configurada para mostrar o seletor apenas em dispositivos móveis, de modo que um cabeçalho amplo no desktop o exiba e o layout estreito não o repita.

Escolha uma opção. Exibir o mesmo controle duas vezes na mesma tela é desnecessário. Configure-o em Opções do cabeçalho ou em Controle da barra lateral.

Um site sem idiomas habilitados não exibe nenhum seletor, em vez de exibir um controle com uma única opção.

O URL de uma página traduzida#

A localidade é sempre um segmento do caminho, nunca um subdomínio. Não existe https://fr.docsbook.io/…, e um subdomínio simples de idioma é servido intencionalmente como 404, para que não se torne um segundo endereço para o mesmo conteúdo.

https://<user>.docsbook.io/<repo>/<path>          → your source language
https://<user>.docsbook.io/fr/<repo>/<path>       → French
https://<user>.docsbook.io/ja/<repo>/<path>       → Japanese

Num domínio personalizado, o segmento do repositório desaparece e a localidade mantém o seu lugar no início:

https://docs.example.com/<path>                   → your source language
https://docs.example.com/fr/<path>                → French

Duas consequências que vale a pena conhecer:

• Um espaço de trabalho com um domínio personalizado é canónico nesse domínio, não no seu espelho docsbook.io — tanto para páginas traduzidas como para as originais. Misturar os dois publicaria uma página cujos vizinhos hreflang apontariam para um local diferente do seu próprio URL canónico.
• /en/… existe, mas não é uma página separada. O inglês é servido de forma idêntica em /<repo>/<path> e /en/<repo>/<path>, e a forma com prefixo declara a forma sem prefixo como canónica, fazendo com que o par se torne uma única página indexável em vez de competir consigo próprio.

Alguns sites alojados no Docsbook — a própria documentação do produto e projetos de demonstração — são servidos no domínio raiz, com a localidade depois do segmento do repositório (https://docsbook.io/<repo>/fr/<path>). O Docsbook gera o URL canónico e hreflang desses sites a partir da mesma função que os encaminha, pelo que o URL anunciado é sempre aquele que responde com 200, em vez de uma redireção.

Desativar um idioma#

Desmarque-o na aba Tradução ou use o interruptor na própria página desse idioma. Nenhuma confirmação é solicitada, porque nada é destruído:

• As traduções armazenadas são mantidas. Reativar o idioma não gera uma nova cobrança pelas páginas que não foram alteradas — apenas páginas novas e editadas são traduzidas, portanto reativar um idioma usado anteriormente é quase instantâneo e praticamente gratuito.
• A página de relatórios desse idioma também é mantida, então a resposta à pergunta "devo reativá-lo?" pode ser obtida com base nos leitores e no custo que ele já teve.
• Os leitores que acessarem a URL do idioma desativado serão enviados para a versão no idioma de origem.

Limites#

• Quinze códigos, sem variantes regionais. pt abrange o Brasil e Portugal com um único conjunto de páginas; zh abrange as formas simplificada e tradicional com um único conjunto. A coluna de idioma armazenada permite cinco caracteres, portanto códigos como pt-BR podem ser armazenados, mas nada no produto os produz ou disponibiliza.
• O modo automático é uma sondagem, não um webhook. Um push é capturado na próxima verificação e, com uma frota ocupada, o intervalo entre as verificações de um workspace pode ultrapassar 15 minutos. Se nada tiver verificado seu projeto em cerca de uma hora, o painel por idioma chama a verificação de atrasada, em vez de fingir que ela está no prazo.
• O seletor de idioma é o único controle de idioma voltado para os leitores. O Docsbook não redireciona os leitores por Accept-Language nem usa roteamento geográfico; um leitor que não tenha expressado nenhuma preferência recebe o padrão configurado do site.
• A escolha do modelo é feita por workspace, não por idioma. Não é possível traduzir japonês com um modelo mais avançado do que o usado para polonês dentro de um mesmo projeto.

Relacionado#

• Traduções por IA — o que uma execução faz a uma página e o que é protegido do modelo
• Qualidade da tradução e SEO — cobertura, atualização, correções, hreflang e canônicos
• Layout do cabeçalho e navegação — colocando o seletor no cabeçalho
• Layout e configuração da barra lateral — colocando-o na barra lateral em vez disso
• Relatório de países dos visitantes — quais regiões chegam que você ainda não traduz