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
│   ├── hi/            # Hindi
│   ├── pt-BR/         # Brazilian Portuguese
│   └── zh-Hans/       # Simplified Chinese
├── src/               # React components and pages
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   ├── landing/       # Homepage HTML + CSS (English source; locale copies in landing/i18n/)
│   ├── pages/         # Additional pages (homepage shell, 404)
│   └── theme/         # Swizzled theme (navbar)
├── static/            # Static assets (images, files)
├── docusaurus.config.ts  # Docusaurus configuration
├── sidebars.ts        # Sidebar navigation configuration
└── package.json       # Dependencies and scripts

Internacionalização (i18n)​

A documentação usa o sistema i18n integrado do Docusaurus com inglês como localidade 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 usuário (do tema do Docusaurus e de componentes personalizados) para arquivos de tradução JSON. O script pnpm translate (de documentation/, que delega para a raiz do repositório) executa o ai-i18n-tools para traduzir markdown, JSON, SVGs e o HTML da landing page de acordo com ai-i18n-tools.config.json.

A página inicial da documentação é src/landing/landing.html encapsulada por src/pages/index.tsx. Edite o arquivo HTML para alterar o texto; as cópias de cada localidade ficam em src/landing/i18n/ e são geradas por pnpm i18n:translate:docs.

important

Edite apenas arquivos em docs/, a origem da landing page src/landing/landing.html e os arquivos JSON de origem em i18n/en-GB/. O markdown traduzido em i18n/{other-locales}/ e as cópias da landing page em src/landing/i18n/ são gerados e não devem ser editados manualmente.

Localidades Suportadas​

LocalidadeIdiomaDiretório
en-GBInglê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/
hiHindii18n/hi/docusaurus-plugin-content-docs/current/
pt-BRPortuguês Brasileiroi18n/pt-BR/docusaurus-plugin-content-docs/current/
zh-HansChinês Simplificadoi18n/zh-Hans/docusaurus-plugin-content-docs/current/

Traduzir a Documentação​

A documentação usa um sistema de tradução alimentado por 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, português brasileiro, hindi e chinês simplificado.

Como Funciona a Tradução​

  1. Strings de interface do Docusaurus: pnpm write-translations extrai strings de tema/personalizadas em i18n/en/*.json.
  2. Tradução por IA (OpenRouter; configuração em ai-i18n-tools.config.json na raiz do repositório): de documentation/, pnpm translate executa o script i18n:translate da raiz (strings de interface, SVGs, markdown/JSON do Docusaurus e modelos de notificação padrão) em documentation/i18n/, src/locales/ e src/locales/templates/ conforme configurado.
  3. Compilação: pnpm build gera HTML estático para todas as localidades em documentation/build/.

Executando Tradução​

cd documentation
pnpm translate          # Same as repo root: i18n:translate (ui + svg + docs + json)
pnpm translate:docs
pnpm translate:json
pnpm translate:svg
pnpm translate:ui
pnpm translate:status

Os sinalizadores CLI são definidos por ai-i18n-tools; execute pnpm exec ai-i18n-tools --help a partir da raiz do repositório ou consulte Translation Workflow.

Substituições de Tradução Manual​

Edite documentation/glossary-user.csv (e opcionalmente limpe entradas obsoletas em .translation-cache/ na raiz do repositório), depois execute novamente o comando pnpm translate:* relevante.

Comandos Comuns​

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

Desenvolvimento​

Inicie o servidor de desenvolvimento com hot-reload para uma localidade específica:

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/duplistatus/ (ou na próxima porta disponível). O caminho /duplistatus/ corresponde ao baseUrl do GitHub Pages e aos links do botão Ajuda no aplicativo.

Compilação​

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

cd documentation
pnpm build

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

Servir Compilação de Produção​

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

cd documentation
pnpm serve

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

Outros Comandos Úteis​

  • pnpm clear - Limpar cache do Docusaurus
  • pnpm typecheck - Executar verificação de tipo TypeScript
  • pnpm write-heading-ids - Escrever âncoras de título {/* #id */} explícitas no markdown usando sintaxe de comentário MDX do Docusaurus (execute a partir de documentation/ para links estáveis entre traduções). O CLI ignora títulos h1, que o Docusaurus usa como rótulos da barra lateral.

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 package.json atual e adiciona um badge de versão
  • Copia conteúdo de documentation/docs/intro.md
  • Converte admonições do Docusaurus (nota, dica, aviso, etc.) para alertas no estilo GitHub
  • Converte todos os links relativos do Docusaurus para URLs absolutas de documentação do GitHub (https://wsj-br.github.io/duplistatus/...)
  • Converte caminhos de imagem 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 brutas absolutas do GitHub
  • Converte links de documento relativos para URLs blob absolutas do GitHub
  • 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 "# Versão xxxx" para "# Notas de Lançamento - Versão xxxxx"
  • Converte links markdown relativos para URLs absolutas de documentação do GitHub (https://wsj-br.github.io/duplistatus/...)
  • Converte caminhos de imagem 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 screenshots para documentação​

pnpm take-screenshots

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

Este script captura automaticamente screenshots da aplicação para fins de documentação. Ele:

  • Após verificações de env e saúde, executa pnpm exec playwright install para que os navegadores do Playwright estejam presentes
  • Inicia um navegador headless (Playwright Chromium)
  • Faz login como administrador e usuário regular
  • Navega por várias páginas (painel, detalhes do servidor, configurações, etc.)
  • Captura screenshots em diferentes tamanhos de viewport
  • Salva screenshots em documentation/static/assets/ (inglês) ou documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets (outras localidades)

Requisitos:

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

Opções: --locale limita screenshots a uma ou mais localidades (separadas por vírgula). Se omitido, todas as localidades são capturadas. Localidades válidas: en-GB, de, fr, es, pt-BR, hi, zh-Hans. 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-GB
# Multiple locales:
pnpm take-screenshots --locale en-GB,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 você tiver o token, armazene-o no armazenamento de credenciais do Git (por exemplo, usando git config credential.helper store ou o gerenciador de credenciais do seu sistema).

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

pnpm run deploy

Isso compilará a documentação e a enviará 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 Translation Workflow.

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/
  • Ativos estáticos: documentation/static/
  • Página inicial: 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 disponibilizá-lo 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 locales

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 write-heading-ids para gerar IDs de cabeçalho (âncoras)
  5. Execute pnpm translate para traduzir a nova página para todos os locales
  6. Compile e teste: pnpm build

Ativos Estáticos​

  • Imagens: Coloque em documentation/static/img/ e faça referência com /img/filename.png em markdown
  • Downloads/PDFs: Coloque em documentation/static/ e faça referência com /filename.pdf
  • Ativos por locale: Se um ativo precisar ser específico do locale (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 locale padrão em inglês e em um outro locale para garantir que as traduções apareçam corretamente.