Pular para o conteúdo principal

Ferramentas de Documentação

A documentação é construída usando Docusaurus e está localizada na pasta documentation. A documentação é hospedada em GitHub Pages e não está mais incluída na imagem do contêiner Docker.

Estrutura de Pastas​

documentation/
├── docs/              # Documentation markdown files (English source)
│   ├── api-reference/
│   ├── development/
│   ├── installation/
│   ├── migration/
│   ├── release-notes/
│   └── user-guide/
├── i18n/              # Translations (auto-generated by translation workflow)
│   ├── de/            # German
│   ├── es/            # Spanish
│   ├── fr/            # French
│   └── pt-BR/         # Brazilian Portuguese
├── src/               # React components and pages
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   └── pages/         # Additional pages (e.g., 404)
├── static/            # Static assets (images, files)
├── docusaurus.config.ts  # Docusaurus configuration
├── sidebars.ts        # Sidebar navigation configuration
├── package.json       # Dependencies and scripts
└── .intlayer/         # Intlayer generated UI translation files (auto-generated)

Internacionalização (i18n)​

A documentação usa o sistema de internacionalização integrado do Docusaurus, com inglês como idioma padrão. O conteúdo traduzido fica em i18n/{locale}/docusaurus-plugin-content-docs/current/, espelhando a estrutura da pasta docs/.

  • Arquivos de origem: docs/**/*.md (Inglês)
  • Arquivos traduzidos: i18n/{locale}/docusaurus-plugin-content-docs/current/**/*.md
  • Traduções de interface: i18n/{locale}/docusaurus-theme-classic/*.json e outros arquivos JSON
  • Capturas de tela localizadas: i18n/{locale}/docusaurus-plugin-content-docs/current/**/assets, geradas por pnpm take-screenhots no diretório base.

O comando pnpm write-translations extrai strings de interface (do tema Docusaurus e componentes personalizados) para arquivos JSON de tradução. O script pnpm translate usa IA para traduzir tanto a documentação markdown quanto os arquivos JSON de interface.

important

Edite apenas arquivos em docs/ e os arquivos JSON de origem em i18n/en/. Os arquivos markdown traduzidos em i18n/{other-locales}/ são gerados automaticamente e não devem ser editados manualmente.

Locais Suportados​

IdiomaLínguaDiretório
enInglês (padrão)docs/ (origem)
deAlemãoi18n/de/docusaurus-plugin-content-docs/current/
esEspanholi18n/es/docusaurus-plugin-content-docs/current/
frFrancêsi18n/fr/docusaurus-plugin-content-docs/current/
pt-BRPortuguês Brasileiroi18n/pt-BR/docusaurus-plugin-content-docs/current/

Traduzir a Documentação​

A documentação usa um sistema de tradução com IA para traduzir tanto o conteúdo (arquivos markdown) quanto as strings de interface (do Docusaurus e componentes personalizados). O conteúdo de origem está em inglês (docs/), e as traduções são geradas para alemão, francês, espanhol e português brasileiro.

Como a Tradução Funciona​

  1. Extração de strings de interface: pnpm write-translations extrai strings traduzíveis da interface do Docusaurus e componentes personalizados para arquivos JSON em i18n/en/

  2. Tradução de conteúdo: pnpm translate usa OpenRouter AI para traduzir:

    • Arquivos markdown de docs/ → i18n/{locale}/docusaurus-plugin-content-docs/current/
    • Strings de interface JSON de i18n/en/ → i18n/{locale}/
    • Arquivos SVG de static/img/duplistatus*.svg (traduz texto dentro de SVGs e exporta para PNG via Inkscape)

  3. Compilação: pnpm build gera HTML estático para todos os idiomas em build/ (um subdiretório por idioma)

Executando Tradução​

cd documentation
pnpm translate                       # Translate everything to all locales
pnpm translate --force               # force the translation of all files
pnpm translate --locale fr           # Translate only to French
pnpm translate --no-svg              # Skip SVG translation
pnpm translate --path docs/intro.md  # Translate specific file
pnpm translate:status                # Show the status of translation of all files

Para opções detalhadas, gerenciamento de cache, solução de problemas e sistema de glossário, consulte Fluxo de Trabalho de Tradução.

Substituições Manuais de Tradução​

Se você precisar ajustar manualmente uma tradução:

  1. adicione os termos ao glossary-user.csv
  2. exclua as entradas de cache para esses termos usando a ferramenta de edição de cache baseada na web
  3. execute novamente a tradução com pnpm translate --force

Comandos Comuns​

Todos os comandos devem ser executados a partir do diretório documentation:

Desenvolvimento​

Inicie o servidor de desenvolvimento com hot-reload para um idioma específico:

cd documentation
pnpm start:en    # English (default)
pnpm start:fr    # French
pnpm start:de    # German
pnpm start:es    # Spanish
pnpm start:pt-br # Brazilian Portuguese

O site estará disponível em http://localhost:3000 (ou na próxima porta disponível).

Compilar​

Construir o site de documentação para produção:

cd documentation
pnpm build

Isto gera arquivos HTML estáticos no diretório documentation/build.

Servir Build de Produção​

Visualize a compilação de produção localmente:

cd documentation
pnpm serve

Isso serve o site construído a partir do diretório documentation/build.

Outros Comandos Úteis​

  • pnpm clear - Limpar cache do Docusaurus
  • pnpm typecheck - Executar verificação de tipos do TypeScript
  • pnpm write-heading-ids - Gerar IDs de cabeçalho no formato interno do Docusaurus (não modifica arquivos markdown)
  • pnpm heading-ids - Adicionar IDs de âncora explícitos {#id} a todos os cabeçalhos markdown (modifica arquivos; garante IDs consistentes entre traduções)

Gerando README.md​

O arquivo README.md do projeto é gerado automaticamente a partir de documentation/docs/intro.md para manter o README do repositório GitHub sincronizado com a documentação do Docusaurus.

Para gerar ou atualizar o arquivo README.md:

./scripts/generate-readme-from-intro.sh

Este script:

  • Extrai a versão atual de package.json e adiciona um badge de versão
  • Copia conteúdo de documentation/docs/intro.md
  • Converte admonições do Docusaurus (note, tip, warning, etc.) para alertas no estilo GitHub
  • Converte todos os links relativos do Docusaurus para URLs absolutas do GitHub docs (https://wsj-br.github.io/duplistatus/...)
  • Converte caminhos de imagens de /img/ para documentation/static/img/ para compatibilidade com GitHub
  • Remove o bloco IMPORTANT de migração e adiciona uma seção Informações de Migração com um link para a documentação do Docusaurus
  • Gera um sumário usando doctoc
  • Gera README_dockerhub.md com formatação compatível com Docker Hub (converte imagens e links para URLs absolutas, converte alertas do GitHub para formato baseado em emoji)
  • Gera notas de lançamento do GitHub (RELEASE_NOTES_github_VERSION.md) a partir de documentation/docs/release-notes/VERSION.md (converte links e imagens para URLs absolutas)

Atualizar README para Docker Hub​

O script generate-readme-from-intro.sh gera automaticamente README_dockerhub.md com formatação compatível com Docker Hub. Ele:

  • Copia README.md para README_dockerhub.md
  • Converte caminhos de imagem relativos para URLs absolutas do GitHub raw
  • Converte links de documento relativos para URLs absolutas do GitHub blob
  • Converte alertas no estilo GitHub ([!NOTE], [!WARNING], etc.) para formato baseado em emoji para melhor compatibilidade com Docker Hub
  • Garante que todas as imagens e links funcionem corretamente no Docker Hub

Gerar Notas de Lançamento do GitHub​

O script generate-readme-from-intro.sh gera automaticamente notas de lançamento do GitHub quando executado. Ele:

  • Lê as notas de lançamento de documentation/docs/release-notes/VERSION.md (onde VERSION é extraído de package.json)
  • Altera o título de "# Version xxxx" para "# Release Notes - Versão xxxxx"
  • Converte links markdown relativos para URLs absolutas de documentação do GitHub (https://wsj-br.github.io/duplistatus/...)
  • Converte caminhos de imagens para URLs brutas do GitHub (https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...) para exibição adequada em descrições de lançamento
  • Trata caminhos relativos com prefixo ../
  • Preserva URLs absolutas (http:// e https://) inalteradas
  • Cria RELEASE_NOTES_github_VERSION.md na raiz do projeto

Exemplo:

# This will generate both README.md and RELEASE_NOTES_github_VERSION.md
./scripts/generate-readme-from-intro.sh

O arquivo de notas de lançamento gerado pode ser copiado e colado diretamente na descrição de lançamento do GitHub. Todos os links e imagens funcionarão corretamente no contexto de lançamento do GitHub.

Capturar capturas de tela para documentação​

pnpm take-screenshots

Ou execute diretamente: pnpm take-screenshots (use --env-file=.env se precisar de variáveis de ambiente).

Este script tira automaticamente screenshots do aplicativo para fins de documentação. Ele:

  • Inicia um navegador headless (Puppeteer)
  • Faz login como admin e usuário regular
  • Navega por várias páginas (painel, detalhes do servidor, configurações, etc.)
  • Tira screenshots em diferentes tamanhos de viewport
  • Salva screenshots em documentation/static/assets/ (Inglês) ou documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets (outros idiomas)

Requisitos:

  • O servidor de desenvolvimento deve estar rodando em http://localhost:8666
  • As variáveis de ambiente devem ser definidas, adicione estas ao seu arquivo .env ou exporte-as:
    • ADMIN_PASSWORD: Senha para conta de admin
    • USER_PASSWORD: Senha para conta de usuário regular

Opções: --locale limita capturas de tela para uma ou mais localidades (separadas por vírgula). Se omitido, todas as localidades são capturadas. Localidades válidas: en, de, fr, es, pt-BR. Use -h ou --help para imprimir o uso.

Exemplo:

export ADMIN_PASSWORD="your-admin-password"
export USER_PASSWORD="your-user-password"
pnpm take-screenshots
# All locales (default):
pnpm take-screenshots
# Single locale:
pnpm take-screenshots --locale en
# Multiple locales:
pnpm take-screenshots --locale en,de,pt-BR

Implantando a Documentação​

Para implantar a documentação no GitHub Pages, você precisará gerar um Token de Acesso Pessoal do GitHub. Acesse GitHub Personal Access Tokens e crie um novo token com o escopo repo.

Quando tiver o token, armazene-o no repositório de credenciais do Git (por exemplo, usando git config credential.helper store ou o gerenciador de credenciais do seu sistema).

Então, para implantar a documentação no GitHub Pages, execute o seguinte comando a partir do diretório documentation:

pnpm run deploy

Isso irá compilar a documentação e enviá-la para o branch gh-pages do repositório, e a documentação estará disponível em https://wsj-br.github.io/duplistatus/.

Trabalhando com Documentação​

Para o fluxo de trabalho de tradução completo (gerenciamento de glossário, tradução por IA, gerenciamento de cache), consulte Fluxo de Trabalho de Tradução.

Arquivos de Origem​

  • Conteúdo da documentação: Arquivos markdown em inglês em documentation/docs/
  • Traduções da interface: Arquivos JSON em inglês em documentation/i18n/en/ (gerados automaticamente por pnpm write-translations)
  • Navegação da barra lateral: documentation/sidebars.ts
  • Configuração do Docusaurus: documentation/docusaurus.config.ts
  • Componentes React personalizados: documentation/src/components/
  • Recursos estáticos: documentation/static/
  • Página inicial principal: documentation/docs/intro.md (fonte para gerar README.md)

Adicionando Novos Componentes​

  1. Crie seu componente React em documentation/src/components/
  2. Exporte-o de documentation/src/theme/MDXComponents.js para torná-lo disponível em MDX
  3. Se o componente incluir strings de interface traduzíveis, execute pnpm write-translations para extraí-las
  4. Execute pnpm translate para traduzir as novas strings para todos os idiomas

Adicionando Novas Páginas de Documentação​

  1. Crie um novo arquivo .md em documentation/docs/ (ou em um subdiretório)
  2. Adicione-o à barra lateral em documentation/sidebars.ts
  3. Execute pnpm write-translations para atualizar a estrutura dos arquivos de tradução
  4. Execute pnpm heading-ids para gerar IDs de cabeçalho (âncoras)
  5. Execute pnpm translate para traduzir a nova página para todos os locais
  6. Compile e teste: pnpm build

Recursos Estáticos​

  • Imagens: Coloque em documentation/static/img/ e referencie com /img/filename.png no markdown
  • Downloads/PDFs: Coloque em documentation/static/ e referencie com /filename.pdf
  • Recursos por idioma: Se um recurso precisar ser específico de um idioma (por exemplo, capturas de tela), coloque-o em documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets/

Compilar e Testar​

cd documentation
pnpm build            # Builds all locales
pnpm serve            # Preview the built site locally
pnpm start:en         # Development server for English
pnpm start:pt-br      # Development server for Portuguese

Sempre teste suas alterações pelo menos no idioma inglês padrão e em outro idioma para garantir que as traduções apareçam corretamente.