Skip to main content

Quickstart Guide

Get your first Docusaurus site translated and deployed in less than 10 minutes.

Prerequisites​

Before starting, you'll need:

1. GitHub Personal Access Token​

Create a token with repo scope:

2. Anthropic API Key​

Sign up and get your API key:

  • Visit Anthropic Console
  • Create API key: sk-ant-xxxxx...
  • Ensure you have sufficient credits ($5+ recommended for testing)

3. Vercel Token (Optional)​

For automatic deployment:

Note: Without Vercel token, translations will still work - repositories will be created on GitHub without automatic deployment.

Your First Translation​

Step 1: Install PageTurner​

pip install transaurus

Step 2: Run Translation​

Create a Python script or use this in a Jupyter notebook:

from transaurus import DocusaurusMaster

# Initialize with your repository
master = DocusaurusMaster(
    # Source Docusaurus repository
    source_repo_url="https://github.com/nozbe/WatermelonDB",

    # Target languages (ISO 639-1 codes)
    target_languages=["es", "fr", "zh-Hans"],

    # Authentication (required)
    github_pat="ghp_xxxxx...",              # Your GitHub token
    anthropic_api_key="sk-ant-xxxxx...",   # Your Anthropic key

    # Optional: Automatic deployment
    vercel_token="xxxxxxxx...",            # Your Vercel token
)

# Execute complete translation pipeline
result = master.run_full_translation_pipeline()

# Your multilingual sites are now live!
print(f"✅ Translation complete!")
print(f"📦 Repositories created: {result['mirror_repos']}")
print(f"🌐 Deployed to: {result['vercel_deployment_urls']}")

Step 3: Wait for Translation​

Expected duration: 15-30 minutes for a typical 100-page documentation site.

You'll see progress logs:

🔍 Phase 1: Analyzing source repository...
📝 Found 156 translatable segments
🧠 Phase 2: Extracting terminology...
🔄 Phase 3: Translating to Spanish...
🔄 Phase 3: Translating to French...
🔄 Phase 3: Translating to Chinese...
✅ Phase 4: Validating translations...
🚀 Phase 5: Deploying to Vercel...

What Just Happened?​

PageTurner performed the following automatically:

1. Repository Setup​

  • Cloned source repository
  • Created mirror repositories:
    • WatermelonDB-es (Spanish)
    • WatermelonDB-fr (French)
    • WatermelonDB-zh-Hans (Simplified Chinese)
  • Configured GitHub security settings
  • Added GitHub Actions workflows

2. Translation Process​

  • Analyzed 156 translatable segments
  • Extracted technical terminology
  • Translated using 5-phase AI pipeline
  • Preserved all React components and MDX structure
  • Validated translation quality

3. Deployment​

  • Created Vercel projects
  • Deployed multilingual sites
  • Configured custom URLs
  • Set up automatic deployment on future updates

Verify Your Translation​

Check GitHub Repositories​

Visit your GitHub organization to see the new repositories:

  • https://github.com/your-org/WatermelonDB-es
  • https://github.com/your-org/WatermelonDB-fr
  • https://github.com/your-org/WatermelonDB-zh-Hans

Each repository contains:

  • Translated MDX files
  • Translated configuration
  • Updated sidebars and navigation
  • GitHub Actions workflow for auto-updates

Visit Deployed Sites​

Open the Vercel deployment URLs:

  • https://watermelondb-es.vercel.app
  • https://watermelondb-fr.vercel.app
  • https://watermelondb-zh-hans.vercel.app

What to check:

  • ✅ Navigation translated correctly
  • ✅ Technical terms consistent across pages
  • ✅ React components still work
  • ✅ Code blocks preserved (not translated)
  • ✅ Links point to correct pages

Review Translation Quality​

Pick a few pages and verify:

  • Technical terms are translated consistently
  • Sentences flow naturally
  • Context is preserved
  • No broken components or formatting

Average quality: 91.3/100 for technical documentation

Next Steps​

Add More Languages​

Simply add more language codes:

master = DocusaurusMaster(
    source_repo_url="https://github.com/nozbe/WatermelonDB",
    target_languages=["es", "fr", "zh-Hans", "ja", "de", "ko", "pt", "ru"],
    # ... rest of config
)

Supported languages: 100+ via Claude AI. Common codes:

  • es - Spanish
  • fr - French
  • de - German
  • ja - Japanese
  • zh-Hans - Simplified Chinese
  • zh-Hant - Traditional Chinese
  • ko - Korean
  • pt - Portuguese
  • ru - Russian
  • ar - Arabic

Handle Updates to Your Docs​

When you update source documentation, re-run the same command:

result = master.run_full_translation_pipeline()

Translation memory ensures only changed content is retranslated:

  • First run: 100 pages × 3 languages = 300 translation requests
  • Update 5 pages: 5 pages × 3 languages = 15 translation requests
  • Cost savings: 95% reduction

Customize Configuration​

See our Configuration Guide for:

  • Custom repository organization
  • Run modes (DRY_RUN, FAKE_TRANSLATE)
  • Advanced LLM settings
  • Deployment options

Troubleshooting​

"GitHub repository creation failed"​

Fix: Ensure your GitHub PAT has repo scope:

  1. Go to GitHub Token Settings
  2. Click your token
  3. Verify repo is checked
  4. Regenerate if needed

"Anthropic API error: insufficient credits"​

Fix: Add credits to your Anthropic account:

  1. Visit Anthropic Console
  2. Go to Billing
  3. Add $20+ (covers ~50,000 pages)

"Translation quality seems poor"​

Likely cause: Source content quality affects translation quality.

Improvements:

  • Ensure source docs are well-written
  • Use consistent terminology in English
  • Provide context for abbreviations
  • Use translation memory to correct specific terms

"React components are broken"​

This shouldn't happen! PageTurner preserves all JSX/MDX components.

If it does:

  1. Check the error in browser console
  2. Verify source repo's components work
  3. Contact support with repo URL

Real-World Example​

Here's a live example using WatermelonDB documentation:

Source: https://github.com/Nozbe/WatermelonDB (English)

Translated:

Stats:

  • Pages: 62 documentation pages
  • Translation time: ~20 minutes
  • Quality score: 92.4/100
  • Components preserved: 100%

Get Help​

Questions? Check our FAQ for common issues.

Still stuck? We're here to help:

What's Next?​