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-Latn/       # Hindi (Roman)
│   ├── pt-BR/         # Brazilian Portuguese
│   └── zh-Hans/       # Simplified Chinese
├── 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

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 de tradução JSON. O script pnpm translate (de documentation/, delega para a raiz do repositório) executa ai-i18n-tools para traduzir markdown, JSON e SVGs conforme ai-i18n-tools.config.json.

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​

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/
hi-LatnHindi (Romano)i18n/hi-Latn/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 utiliza um sistema de tradução com IA para traduzir tanto o conteúdo (arquivos markdown) quanto 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 do Brasil, Hindi (Romano) e Chinês Simplificado.

Como a Tradução Funciona​

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

Executando Tradução​

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

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

Substituições Manuais de Tradução​

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 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 o cache do Docusaurus
  • pnpm typecheck - Executar verificação de tipos do TypeScript
  • pnpm write-heading-ids - Escrever âncoras de títulos explícitas {#id} no markdown usando as regras do Docusaurus (execute a partir de documentation/ para obter links estáveis 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 selo de versão
  • Copia o conteúdo de documentation/docs/intro.md
  • Converte advertências do Docusaurus (note, tip, warning, etc.) para alertas no estilo GitHub
  • Converte todos os links relativos do Docusaurus para URLs absolutas da documentação do GitHub (https://wsj-br.github.io/duplistatus/...)
  • Converte caminhos de imagens de /img/ para documentation/static/img/ para compatibilidade com o GitHub
  • Remove o bloco IMPORTANT de migração e adiciona uma seção de 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 o Docker Hub (converte imagens e links para URLs absolutos, converte alertas do GitHub para formato baseado em emojis)
  • Gera as 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 absolutos)

Atualizar README para Docker Hub​

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

  • Copia README.md para README_dockerhub.md
  • Converte caminhos de imagens relativos para URLs absolutas raw do GitHub
  • Converte links de documentos relativos para URLs absolutas blob do GitHub
  • Converte alertas no estilo GitHub ([!NOTE], [!WARNING], etc.) para formato baseado em emojis para melhor compatibilidade com o 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 as notas de lançamento do GitHub ao ser executado. Ele:

  • Lê as notas de lançamento de documentation/docs/release-notes/VERSION.md (onde a VERSÃO é extraída de package.json)
  • Altera o título de "# Version xxxx" para "# Release Notes - Version xxxxx"
  • Converte links markdown relativos para URLs absolutas da documentação do GitHub (https://wsj-br.github.io/duplistatus/...)
  • Converte caminhos de imagens para URLs raw do GitHub (https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...) para exibição correta nas descrições de lançamento
  • Trata caminhos relativos com prefixo ../
  • Mantém 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 capturas de tela do aplicativo para fins de documentação. Ele:

  • Inicia um navegador sem interface gráfica (Playwright Chromium)
  • Faz login como administrador e usuário regular
  • Navega por várias páginas (painel, detalhes do servidor, configurações, etc.)
  • Tira capturas de tela em diferentes tamanhos de viewport
  • Salva as capturas de tela 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 em execução em http://localhost:8666
  • O navegador Playwright Chromium deve estar instalado (execute pnpm take-screenshots:install uma vez, que executa playwright install chromium)
  • 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 capturas de tela 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-Latn, 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 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 na 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 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 write-heading-ids para gerar IDs de títulos (âncoras)
  5. Execute pnpm translate para traduzir a nova página para todos os idiomas
  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.