Stirling-PDF/devGuide/HowToAddNewLanguage.md

Stirling-PDF

How to add new languages to Stirling-PDF

Fork Stirling-PDF and create a new branch out of main.

Add Language to i18n Configuration

Edit the file: frontend/src/i18n.ts

Add your language to the supportedLanguages object. For example, to add Polish:

export const supportedLanguages = {
  'en': 'English',
  'en-GB': 'English (UK)',
  // ... other languages ...
  'pl-PL': 'Polski',  // Add your language here
};

If your language uses right-to-left (RTL) text direction, also add it to the rtlLanguages array:

export const rtlLanguages = ['ar-AR', 'fa-IR', 'pl-PL']; // Add if RTL

Create Translation Directory

Create a new directory for your language in frontend/public/locales/. For Polish, this would be:

mkdir -p frontend/public/locales/pl-PL

Add Translation File

Start by copying the existing English (UK) translation file:

• frontend/public/locales/en-GB/translation.json

Copy and rename it to frontend/public/locales/{your-language-code}/translation.json. In the Polish example:

cp frontend/public/locales/en-GB/translation.json frontend/public/locales/pl-PL/translation.json

Then translate all entries within that JSON file. The file uses nested JSON structure like:

{
  "addPageNumbers": {
    "title": "Add Page Numbers",
    "submit": "Add Page Numbers",
    "error": {
      "failed": "Add page numbers operation failed"
    }
  }
}

Handling Untranslatable Strings

Sometimes, certain strings may not require translation because they are the same in the target language or are universal (like names of protocols, certain terminologies, etc.). To ensure accurate statistics for language progress, these strings should be added to the ignore_translation.toml file located in the scripts directory. This will exclude them from the translation progress calculations.

For example, if the English string for "error" does not need translation in Polish, add it to the ignore_translation.toml under the Polish section:

[pl_PL]
ignore = [
    "language.direction",  # Existing entries
    "error"                # Add new entries here
]

Add New Translation Tags

Important

If you add any new translation tags, they must first be added to the frontend/public/locales/en-GB/translation.json file. This ensures consistency across all language files.

• New translation tags must be added to the en-GB translation file to maintain a reference for other languages.
• After adding the new tags to the en-GB file, add and translate them in the respective language file (e.g., pl-PL/translation.json).

Make sure to place the entry under the correct language section. This helps maintain the accuracy of translation progress statistics and ensures that the translation tool or scripts do not misinterpret the completion rate.

Testing Your Translation

Start the development server

1. Start the frontend development server:

   cd frontend
   npm run dev
   

2. The language selector should now include your new language

3. Select your language from the dropdown and verify all translations appear correctly

Summary Checklist

When adding a new language, you need to update:

• frontend/src/i18n.ts - Add to supportedLanguages (and rtlLanguages if needed)
• frontend/public/locales/{language-code}/translation.json - Create and translate
• scripts/ignore_translation.toml - Add untranslatable strings if needed

Then make a Pull Request (PR) into main for others to use!

If you do not have a Node.js environment, we are happy to verify that the changes work once you raise the PR (but we won't be able to verify the translations themselves).

Translation Guidelines

• Consistency: Keep terminology consistent throughout the translation
• Context: Consider the UI context when translating (e.g., button labels should be concise)
• Formatting: Preserve placeholders like {n} or {{count}} in translations
• Testing: Test your translations in the frontend interface
• RTL Languages: If your language uses RTL, ensure you add it to the rtlLanguages array

Advanced: Translation Management Scripts

For translators working on large translation files, Python scripts are available in scripts/translations/ to help manage the workflow.

Finding Untranslated Strings

To see which strings still need translation:

# Check translation status for your language
python scripts/translations/translation_analyzer.py --language pl-PL --summary

# See detailed list of missing translations
python scripts/translations/translation_analyzer.py --language pl-PL --missing-only

Extracting Untranslated Strings

To extract only the strings that need translation into a separate file:

# Extract to a compact JSON file
python scripts/translations/compact_translator.py pl-PL --output to_translate.json

This creates a file with just the untranslated entries:

{
  "addPageNumbers.title": "Add Page Numbers",
  "compress.header": "Compress PDF",
  "merge.submit": "Merge PDFs"
}

Translating the Extracted File

Open to_translate.json and translate the values while keeping the keys unchanged:

{
  "addPageNumbers.title": "Dodaj numery stron",
  "compress.header": "Kompresuj PDF",
  "merge.submit": "Połącz pliki PDF"
}

Merging Translations Back

After translating, merge your translations back into the main file:

# Apply your translations
python scripts/translations/translation_merger.py pl-PL apply-translations --translations-file to_translate.json

# Verify the result
python scripts/translations/translation_analyzer.py --language pl-PL --summary

Validating Your Work

Before submitting, validate your translation file:

# Check for JSON syntax errors
python scripts/translations/json_validator.py frontend/public/locales/pl-PL/translation.json

# Check for missing placeholders
python scripts/translations/validate_placeholders.py --language pl-PL

# Check for structural issues
python scripts/translations/validate_json_structure.py --language pl-PL

Note: These scripts require Python 3.7+ to be installed. See scripts/translations/README.md for detailed documentation.