Docusaurus

O pacote translate-projects-docusaurus traduz as páginas de documentação, o blog, as páginas React (code.json) e os textos do tema de um site Docusaurus, e os grava na estrutura i18n/ que o Docusaurus já entende.

Requisitos

• Node.js 20 ou superior.
• Um site Docusaurus 3 com o script write-translations no package.json (já vem no template oficial).
• Um projeto e um API token do Translate Projects. Veja Primeiros passos.

1. Instale o pacote

Terminal

npm i -D translate-projects-docusaurus

2. Ative os idiomas no Docusaurus

Adicione os idiomas em docusaurus.config.js e o seletor de idioma na barra de navegação:

docusaurus.config.js

export default {
  i18n: {
    defaultLocale: 'es',
    locales: ['es', 'en', 'pt-BR', 'fr'],
    localeConfigs: {
      es: { label: 'Español' },
      en: { label: 'English' },
      'pt-BR': { label: 'Português (Brasil)' },
      fr: { label: 'Français' },
    },
  },
  themeConfig: {
    navbar: {
      items: [{ type: 'localeDropdown', position: 'right' }],
    },
  },
};

3. Escreva seus textos na pasta translate/

Mova suas pastas docs/ e blog/ para translate/. A partir de agora você edita apenas translate/: o pacote gera docs/, blog/ e i18n/ a cada execução.

Terminal

mkdir translate
mv docs blog translate/

Estrutura

translate/
├── docs/
│   └── intro.md
└── blog/
    └── 2025-01-01-bienvenida.md

Coloque entre chaves duplas cada texto que quiser traduzir. O que não estiver marcado (código, links, nomes) é copiado sem alterações:

translate/docs/intro.md

---
title: {{Primeros pasos}}
---

# {{Bienvenido a mi proyecto}}

{{Este párrafo se traduce.}} [{{Ver ejemplo}}](https://example.com)

• Escreva o texto colado às chaves, sem espaços no início nem no fim.
• Para escrever chaves literais (por exemplo, as variáveis do i18next em um bloco de código), coloque uma barra invertida na frente. Elas não são enviadas para tradução e a barra desaparece no resultado: \{{lng}} → {{lng}}.
• Fora dos blocos de código, o MDX não aceita chaves soltas: não deixe chaves duplas sem fechar.

4. Configure a tradução

Crie translate.config.mjs na raiz do site. O API token é lido da variável de ambiente TRANSLATE_PROJECTS_API_KEY:

translate.config.mjs

export default {
  sourceLang: 'es', // Idioma base: o idioma padrão do projeto
  targetLangs: ['en', 'pt-BR', 'fr'], // Idiomas a gerar
  apiKey: process.env.TRANSLATE_PROJECTS_API_KEY,
};

E o script em package.json:

package.json

{
  "scripts": {
    "translate": "translate-projects-docusaurus"
  }
}

Opções

Opção	Padrão	Descrição
sourceLang	—	Idioma base (obrigatório).
targetLangs	—	Idiomas a gerar (obrigatório).
apiKey	—	API token do projeto.
force	false	Ignora o cache e traduz tudo novamente (igual a --force).
docs	{ enable: true, baseDir: './translate/docs', outputDir: './docs' }	Documentação.
blog	{ enable: true, baseDir: './translate/blog', outputDir: './blog' }	Blog. Desative se o seu site não tiver blog.
react	{ enable: true }	Textos das suas páginas React (i18n/<lang>/code.json).
theme	{ enable: true, ignoreKeys: [] }	Textos do tema (barra de navegação e rodapé). Em ignoreKeys ficam as chaves que não são traduzidas.
config	{ outputDir: './i18n' }	Pasta i18n do Docusaurus.

5. Traduza

Terminal

export TRANSLATE_PROJECTS_API_KEY=tu_token
npm run translate

Depois compile o site com todos os idiomas:

Terminal

npm run build
npm run serve

Arquivos que são gerados

Origem	Idioma base	Outros idiomas
translate/docs/**	docs/**	i18n/<lang>/docusaurus-plugin-content-docs/current/**
translate/blog/**	blog/**	i18n/<lang>/docusaurus-plugin-content-blog/**
i18n/<base>/code.json	—	i18n/<lang>/code.json
i18n/<base>/docusaurus-theme-classic/*.json	—	i18n/<lang>/docusaurus-theme-classic/*.json

As imagens e demais arquivos que não são texto são copiados para cada idioma. Se você fizer deploy a partir do repositório, inclua docs/, blog/ e i18n/ no deploy ou execute a tradução antes do build.

Pré-visualização enquanto você escreve

O modo --dev monitora translate/ e atualiza o idioma base instantaneamente, sem chamar a API:

Terminal 1

npx docusaurus start --locale es

Terminal 2

npx translate-projects-docusaurus --dev

Cache e --force

Somente os arquivos alterados são traduzidos; uma segunda execução sem alterações não traduz nada. Para traduzir tudo novamente:

Terminal

npx translate-projects-docusaurus --force

Mais detalhes em Cache e erros.

Erros comuns

• Token inválido (401): verifique TRANSLATE_PROJECTS_API_KEY. Nenhum arquivo é gravado nem apagado.
• Falta a chave de IA (MISSING_API_KEY): configure o provedor, o modelo e a chave no projeto. Enquanto isso, os textos ficam no idioma base.
• Tradução parcial: os textos que faltam permanecem no idioma base, o comando termina com código 1 e são solicitados novamente na próxima execução.
• O build falha com Invalid translation file: há um JSON vazio ou quebrado em i18n/. Apague-o e execute npm run write-translations -- --locale <lang>.
• Aparecem chaves duplas na página traduzida: o texto tinha espaços dentro das chaves ou eram chaves literais sem \.

Grátis

🚀 Automatize suas traduções de graça

Translate Projects é gratuito. Você cria seu projeto, conecta a chave do seu provedor de IA e paga apenas a ele pelo que gastar.

• Sem planos nem cartão de crédito: Todos os recursos estão disponíveis desde o primeiro dia.
• Use sua própria IA: Claude, OpenAI, DeepSeek ou Gemini. Sua chave é armazenada criptografada.
• Rede de traduções compartilhada: Se um texto já foi traduzido, você o recebe instantaneamente sem gastar sua chave.
• Painel de administração: Revise e edite todas as suas traduções em um único lugar.

Criar conta grátis →

Suporte

Estamos aqui para ajudar você

Se você tiver alguma dúvida, precisar de ajuda ou quiser contribuir, não hesite em entrar em contato comigo. Estou à sua disposição para apoiá-lo no que precisar.

• Site: neiderruiz.com
• GitHub: @neiderruiz
• Twitter: @neiderruiz
• YouTube: Neider Ruiz

Apoie o Projeto

Se este projeto foi útil para você, convido você a me pagar um café. Seu apoio me ajuda a continuar melhorando e criando conteúdo de valor. Obrigado por estar aqui! ☕