Translation Guide

Help us make the Scrum Guide Expansion Pack accessible to everyone worldwide by -Contributing-to-the-Scrum-Guide-Expansion-Pack Translation-Guide!

Please read the Code of Conduct for Translation Contributors before starting.

🎯 Quick Start - Choose Your Path

Option 1: GitHub Collaboration (for contributors familiar with GitHub)

Best for: Translators familiar with Git, GitHub, and the Pull Request Workflow.

Process:

Fork the repository
Create translation files with our Automated Setup
Collaborate with other translators
Submit Pull Request for review

📖 Skip to GitHub Workflow →

Option 2: Manual Submission (for contributors who don't understand GitHub)

Best for: Translators who are non-technical and dont want to collaborating with pull requests.

Process:

Download translation templates
Work independently or collaborate via email/messaging
Submit completed Translation-Guide via GitHub Issues
We'll create the Pull Request for community review

📖 Skip to Manual Workflow →

📋 What Needs Translation

To add a new language to the site, you'll need to translate:

1. Main Guide Content

File: site/content/guide/index.{LANG}.md
Content: The complete Scrum Guide Expansion Pack document
Size: ~900 lines of Markdown content

2. User Interface Elements

File: site/i18n/{LANG}.yaml
Content: Navigation, buttons, labels, and interface text
Size: ~40 translation keys

3. Supporting Content (Optional)

Creator pages in site/content/creators/
Download page content

🔧 GitHub Workflow

Prerequisites

GitHub account
Basic understanding of Git/GitHub
Markdown knowledge helpful but not required

Step 1: Set Up Your Fork

Fork the repository
- Go to ScrumGuide-ExpansionPack
- Click "Fork" button
- Clone your fork locally

git clone https://github.com/YOUR-USERNAME/ScrumGuide-ExpansionPack.git
cd ScrumGuide-ExpansionPack

Step 2: Create Translation Branch

git checkout -b translation/add-{LANG}-language

Replace {LANG} with your language code (e.g., pt for Portuguese, ja for Japanese).

Step 3: Create Translation Files

Option A: Automated Setup (PowerShell - Recommended)

Prerequisites: PowerShell 7+ (Windows, macOS, or Linux)

Use our automated translation template script to set up all necessary files:

⚠️ Note: The script will automatically install the required powershell-yaml module if it's not already available.

# Basic usage
.\scripts\Create-TranslationTemplate.ps1 -LanguageCode "de" -LanguageName "German"

# Advanced usage with custom settings
.\scripts\Create-TranslationTemplate.ps1 -LanguageCode "es" -LanguageName "Spanish" -Title "Guía Scrum Paquete de Expansión" -Weight 3 -Force

What the script does:

✅ Adds language -Configuration-Reference to hugo.yaml
✅ Creates site/i18n/{LANG}.yaml from English template
✅ Creates all translated content files (*.{LANG}.md)
✅ Sets up proper frontmatter with placeholders
✅ Validates the complete setup
✅ Provides next steps guidance

🕒 Time savings: The script reduces setup time from ~30 minutes manual work to ~2 minutes automated setup.

Script Parameters:

LanguageCode - ISO language code (e.g., 'de', 'es', 'fr')
LanguageName - Display name (e.g., 'German', 'Spanish')
Title - Translated site title (optional)
Description - Translated site description (optional)
Keywords - Translated site keywords (optional)
Weight - Language menu order (optional, auto-calculated)
Force - Overwrite existing files

💡 Don't have PowerShell? Install it from Microsoft's official guide - it's free and available for Windows, macOS, and Linux.

Option B: Manual Setup

If you prefer manual setup or don't have PowerShell:

A. Main Guide Translation

Copy the English guide:

cp site/content/guide/index.md site/content/guide/index.{LANG}.md

Edit the frontmatter in site/content/guide/index.{LANG}.md:

---
title: "Your Translated Title"
description: "Your translated description"
# ... translate other metadata
---

Translate the entire content while preserving:
- Markdown formatting (##, **bold**, [links](https://github.com/ScrumGuides/ScrumGuide-ExpansionPack/blob/main/docs/url))
- Hugo shortcodes
- Reference numbers (40), (58), etc.
- HTML comments and IDs

B. UI Translation File

Copy the English Translation-Guide:

cp site/i18n/en.yaml site/i18n/{LANG}.yaml

Translate each entry in site/i18n/{LANG}.yaml:

# Example - keep the ID, translate the text
- id: read_online_title
  translation: "Your translated text here"

C. Add Language to Hugo -Configuration-Reference

Add your language to site/hugo.yaml in the languages: section:

languages:
  # ... existing languages
  { LANG }:
    languageName: Your Language Name
    weight: 2 # Adjust as needed
    title: Your Translated Site Title
    params:
      description: "Your translated description"
      keywords: "Your translated keywords"

Step 4: Test Your Translation

Install Hugo (see -Development-Guide Guide)
Start the -Development-Guide server:

cd site
hugo server --config hugo.yaml,hugo.local.yaml

View your translation:
- Navigate to http://localhost:1313/{LANG}/
- Check all pages and UI elements
- Verify language switching works correctly

Step 5: Submit for Review

Commit your changes:

git add .
git commit -m "Add {LANG} translation"
git push origin translation/add-{LANG}-language

Create Pull Request:
- Go to your fork on GitHub
- Click "New Pull Request"
- Use title: "Add {Language Name} translation"
- Include translation details in description
Review Process:
- Creators and community will review
- Native speakers may suggest improvements
- Collaborate on refinements
- Merge when approved

📝 Manual Workflow

💡 Tip: Even if you're using the manual workflow, you can still use our PowerShell automation script to generate the template files - just fork the repo temporarily, run the script, then download the generated files to work with locally.

Step 1: Get Translation Templates

Download files to translate:
- Main Guide Template
- UI Translation-Guide Template
Save locally with your language code:
- index.{LANG}.md (e.g., index.pt.md)
- {LANG}.yaml (e.g., pt.yaml)

Step 2: Translate Content

Main Guide (index.{LANG}.md):
- Translate title and description in the frontmatter
- Translate all body content
- Keep all Markdown formatting intact
- Preserve reference numbers and links
UI File ({LANG}.yaml):
- Translate only the text after translation:
- Keep the id: values unchanged
- Maintain YAML formatting

Step 3: Collaborate (Optional)

Share files with other translators via email or messaging
Use Google Docs or similar for collaborative editing
Coordinate with existing translation communities

Step 4: Submit Translation

Create GitHub Issue:
- Go to Issues page
- Click "New Issue"
- Title: "Translation Submission: {Language Name}"
Include in issue:
- Language name and code
- Attach your translated files
- List any collaborators to credit
- Note any questions or concerns
We'll handle the rest:
- Create proper Git commits
- Set up Pull Request
- Coordinate community review
- Handle technical integration