Mukhya samagri par jaen

Documentation Tools

Documentation Docusaurus https://docusaurus.io/ ka istemal karke banai jati hai aur documentation folder mein sthit hai. Documentation GitHub Pages https://wsj-br.github.io/duplistatus/ par host ki jati hai aur ab Docker container image mein shamil nahin hai.

Folder Structure​

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

Internationalization (i18n)​

Documentation Docusaurus ke built-in i18n system ka istemal karti hai jismein English default locale hai. Anudit content i18n/{locale}/docusaurus-plugin-content-docs/current/ mein rehta hai, jo docs/ folder ke structure ko mirror karta hai.

  • Source files: docs/**/*.md (English)
  • Translated files: i18n/{locale}/docusaurus-plugin-content-docs/current/**/*.md
  • UI translations: i18n/{locale}/docusaurus-theme-classic/*.json aur anya JSON files
  • Localised Screenshots: i18n/{locale}/docusaurus-plugin-content-docs/current/**/assets, jo basedir mein pnpm take-screenhots dwara generate kiye gaye hain.

pnpm write-translations command UI strings (Docusaurus theme aur custom components se) ko JSON translation files mein extract karta hai. pnpm translate script (repo root mein documentation/ se, delegate karta hai) ai-i18n-tools.config.json ke anusar markdown, JSON, aur SVG ko translate karne ke liye ai-i18n-tools run karta hai.

important

Keval docs/ aur i18n/en/ mein source JSON files mein files edit karen. i18n/{other-locales}/ mein anudit markdown files auto-generate hoti hain aur unhein manually edit nahin kiya jana chahiye.

Supported Locales​

LocaleBhaashaDirectory
en-GBEnglish (Default)docs/ (source)
deGermani18n/de/docusaurus-plugin-content-docs/current/
esSpanishi18n/es/docusaurus-plugin-content-docs/current/
frFrenchi18n/fr/docusaurus-plugin-content-docs/current/
hi-LatnHindi (Roman)i18n/hi-Latn/docusaurus-plugin-content-docs/current/
pt-BRBrazilian Portuguesei18n/pt-BR/docusaurus-plugin-content-docs/current/
zh-HansSimplified Chinesei18n/zh-Hans/docusaurus-plugin-content-docs/current/

Translate the Documentation​

Dokumenteshan content (markdown File) aur UI strings (Docusaurus aur Anukoolit components se) dono ko translate karne ke liye ek AI-powered translation Pranali ka upayog karti hai. Source content English (docs/) mein hai, aur German, French, Spanish, Brazilian Portuguese, Hindi (Roman), aur Simplified Chinese ke liye translations generate kiye jaate hain.

How Translation Works​

  1. Docusaurus UI strings: pnpm write-translations theme/custom strings ko i18n/en/*.json mein extract karta hai.
  2. AI translation (OpenRouter; repo root mein ai-i18n-tools.config.json mein config): documentation/ se, pnpm translate root i18n:translate script (UI strings, SVGs, aur Docusaurus markdown/JSON) ko configured anusar documentation/i18n/ aur src/locales/ mein run karta hai.
  3. Build: pnpm build documentation/build/ ke tahat sabhi locales ke liye static HTML generate karta hai.

Running Translation​

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

CLI flags ai-i18n-tools dwara paribhashit hain; repo root se pnpm exec ai-i18n-tools --help chalayen ya Anuvad Karyapravah dekhen.

Manual Translation Overrides​

documentation/glossary-user.csv ko edit karein (aur vikalp ke taur par repo root mein .translation-cache/ ke tahat stale entries ko clear karein), phir sambandhit pnpm translate:* command ko phir se chalayein.

Common Commands​

Sabhi commands documentation directory se chalai jani chahiye:

Development​

Ek vishisht locale ke liye hot-reload ke saath development server shuru karein:

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

Site http://localhost:3000 (ya agle uplabdh port) par uplabdh hogi.

Build​

Production ke liye documentation site build karein:

cd documentation
pnpm build

Yah documentation/build directory mein static HTML file banata hai.

Serve Production Build​

Production build ko locally preview karein:

cd documentation
pnpm serve

Yah documentation/build directory se built site serve karta hai.

Other Useful Commands​

  • pnpm clear - Docusaurus cache clear karein
  • pnpm typecheck - TypeScript type checking chalayein
  • pnpm write-heading-ids - Docusaurus rules ka upyog karke markdown mein explicit {#id} heading anchors likhein (sthir links ke liye documentation/ se chalayein)

Generating README.md​

Project ki README.md file GitHub repository README ko Docusaurus documentation ke saath synchronized rakhne ke liye documentation/docs/intro.md se svayanchalit roop se generate hoti hai.

README.md file generate ya update karne ke liye:

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

Yah script:

  • package.json se vartaman sanskaran extract karta hai aur ek version badge jodta hai
  • documentation/docs/intro.md se content copy karta hai
  • Docusaurus admonitions (note, tip, warning, ityadi) ko GitHub-style alerts mein convert karta hai
  • Docusaurus ke sabhi relative links ko absolute GitHub docs URLs mein badalta hai (https://wsj-br.github.io/duplistatus/...)
  • GitHub compatibility ke liye image paths ko /img/ se documentation/static/img/ mein badalta hai
  • IMPORTANT migration block ko hatata hai aur Docusaurus docs ke link ke saath ek Migration Information section jodta hai
  • doctoc ka upyog karke table of contents generate karta hai
  • Docker Hub-compatible formatting ke saath README_dockerhub.md generate karta hai (images aur links ko absolute URLs mein badalta hai, GitHub alerts ko emoji-based format mein badalta hai)
  • GitHub release notes (RELEASE_NOTES_github_VERSION.md) ko documentation/docs/release-notes/VERSION.md se generate karta hai (links aur images ko absolute URLs mein badalta hai)

Docker Hub ke liye README update karein​

generate-readme-from-intro.sh script automatically Docker Hub-compatible formatting ke saath README_dockerhub.md generate karta hai. Yah:

  • README.md ko README_dockerhub.md mein copy karta hai
  • Relative image paths ko absolute GitHub raw URLs mein badalta hai
  • Relative document links ko absolute GitHub blob URLs mein badalta hai
  • GitHub-style alerts ([!NOTE], [!WARNING], aadi) ko Docker Hub compatibility ke liye emoji-based format mein badalta hai
  • Sunishchit karta hai ki sabhi images aur links Docker Hub par sahi se kaam karein

GitHub Release Notes generate karein​

generate-readme-from-intro.sh script run hone par automatically GitHub release notes generate karta hai. Yah:

  • Release notes ko documentation/docs/release-notes/VERSION.md se padhta hai (jahan VERSION ko package.json se extract kiya jaata hai)
  • Title ko "# Version xxxx" se "# Release Notes - Version xxxxx" mein badalta hai
  • Relative markdown links ko absolute GitHub docs URLs mein badalta hai (https://wsj-br.github.io/duplistatus/...)
  • Release descriptions mein sahi display ke liye image paths ko GitHub raw URLs mein badalta hai (https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...)
  • ../ prefix ke saath relative paths ko handle karta hai
  • Absolute URLs (http:// aur https://) ko unchanged rakhta hai
  • Project root mein RELEASE_NOTES_github_VERSION.md banata hai

Udaharan:

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

Generate kiye gaye release notes file ko seedhe GitHub release description mein copy aur paste kiya ja sakta hai. Sabhi links aur images GitHub release context mein sahi se kaam karenge.

Documentation ke liye screenshots lein​

pnpm take-screenshots

Ya seedhe run karein: pnpm take-screenshots (agar environment variables ke liye zaroori ho to --env-file=.env ka upyog karein).

Yah script documentation ke liye application ke screenshots automatically leta hai. Yah:

  • Ek headless browser (Playwright Chromium) launch karta hai
  • Admin aur regular user ke roop mein login karta hai
  • Vibhinn pages (dashboard, server details, settings, aadi) ke through navigate karta hai
  • Vibhinn viewport sizes par screenshots leta hai
  • Screenshots ko documentation/static/assets/ (English) ya documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets (any locales) mein save karta hai

Aavashyaktaayein:

  • Development server http://localhost:8666 par chalna chahiye
  • Playwright Chromium browser install hona chahiye (ek baar pnpm take-screenshots:install run karein, jo playwright install chromium run karta hai)
  • Environment variables set hone chahiye, inhein apne .env file mein jodein ya export karein:
    • ADMIN_PASSWORD: Admin account ke liye Password
    • USER_PASSWORD: Regular user account ke liye Password

Options: --locale screenshots ko ek ya adhik locales (comma-separated) tak limit karta hai. Agar omit kiya gaya, to Sabhi locales capture kiye jaate hain. Valid locales: en-GB, de, fr, es, pt-BR, hi-Latn, zh-Hans. Usage print karne ke liye -h ya --help ka upayog karein.

Udaharan:

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

Documentation deploy karna​

Documentation ko GitHub Pages par deploy karne ke liye, aapko ek GitHub Personal Access Token generate karna hoga. GitHub Personal Access Tokens par jaakar repo scope ke saath ek naya token banayein.

Jab token mil jaaye, use Git credential store mein store karein (udaharan ke liye git config credential.helper store ya aapke pranali ke credential manager ka istemaal karke).

Phir, documentation ko GitHub Pages par deploy karne ke liye, documentation directory se nimnalikhit command chalayein:

pnpm run deploy

Yah documentation ko build karega aur repository ki gh-pages branch mein push karega, aur documentation https://wsj-br.github.io/duplistatus/ par uplabdh hogi.

Documentation ke saath kaam karna​

Poore anuvaad workflow (glossary management, AI anuvaad, cache management) ke liye, Anuvaad Workflow dekhein.

Source File​

  • Documentation content: documentation/docs/ mein English markdown file
  • UI anuvaad: documentation/i18n/en/ mein English JSON file (pnpm write-translations dwara auto-generate ki gayi)
  • Sidebar navigation: documentation/sidebars.ts
  • Docusaurus configuration: documentation/docusaurus.config.ts
  • Anukoolit React components: documentation/src/components/
  • Static assets: documentation/static/
  • Mukhya homepage: documentation/docs/intro.md (README.md generate karne ka source)

Naye Components jodna​

  1. documentation/src/components/ mein apna React component banayein
  2. ise MDX mein uplabdh karne ke liye documentation/src/theme/MDXComponents.js se export karein
  3. Agar component mein anuvaad yogya UI strings hain, to unhein extract karne ke liye pnpm write-translations chalayein
  4. Nayi strings ko sabhi locales mein anuvaadit karne ke liye pnpm translate chalayein

Naye Documentation Pages jodna​

  1. documentation/docs/ mein ek nayi .md file banayein (ya ek subdirectory)
  2. ise sidebar mein documentation/sidebars.ts mein jodein
  3. anuvaad file structure ko update karne ke liye pnpm write-translations chalayein
  4. Heading IDs (anchors) generate karne ke liye pnpm write-heading-ids chalayein
  5. Naye page ko sabhi locales mein anuvaadit karne ke liye pnpm translate chalayein
  6. Build aur test karein: pnpm build

Static Assets​

  • Images: documentation/static/img/ mein rakhein aur markdown mein /img/filename.png se refer karein
  • Downloads/PDFs: documentation/static/ mein rakhein aur /filename.pdf se refer karein
  • Prati-locale assets: Agar kisi asset ko locale-specific (jaise, screenshots) hone ki zaroorat hai, to use documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets/ mein rakhein

Build & Test​

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

Hamesha apne changes ko kam se kam default English locale aur ek anya locale mein test karein taaki yeh sunishchit ho sake ki anuvaad sahi tarah se dikh rahe hain.