mirror of https://github.com/Frooodle/Stirling-PDF.git synced 2025-12-18 20:04:17 +01:00

Anthony Stirling 65a3eeca76

# Description of Changes

<!--
Please provide a summary of the changes, including:

- What was changed
- Why the change was made
- Any challenges encountered

Closes #(issue_number)
-->

---

## Checklist

### General

- [ ] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [ ] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [ ] I have performed a self-review of my own code
- [ ] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### Translations (if applicable)

- [ ] I ran
[`scripts/counter_translation.py`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docs/counter_translation.md)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [ ] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing)
for more details.

2025-12-03 09:57:00 +00:00

3.1 KiB

Raw Blame History

Stirling-PDF

How to add new languages to Stirling-PDF

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

Frontend Translation Files (TOML Format)

Add Language Directory and Translation File

Create a new language directory in frontend/public/locales/
- Use hyphenated format: pl-PL (not underscore)
Copy the reference translation file:
- Source: frontend/public/locales/en-GB/translation.toml
- Destination: frontend/public/locales/pl-PL/translation.toml
Translate all entries in the TOML file
- Keep the TOML structure intact
- Preserve all placeholders like {n}, {total}, {filename}, {{variable}}
- See scripts/translations/README.md for translation tools and workflows
Update the language selector in the frontend to include your new language

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

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 error does not need translation in Polish, add it to the ignore_translation.toml under the Polish section:

Note: Use underscores in ignore_translation.toml even though frontend uses hyphens (e.g., pl_PL not pl-PL)

[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 en-GB/translation.toml file. This ensures consistency across all language files.

New translation tags must be added to frontend/public/locales/en-GB/translation.toml to maintain a reference for other languages.
After adding the new tags to en-GB/translation.toml, add and translate them in the respective language file (e.g., pl-PL/translation.toml).
Use the scripts in scripts/translations/ to validate and manage translations (see scripts/translations/README.md)

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.

Validation Commands

Use the translation scripts in scripts/translations/ directory:

# Analyze translation progress
python3 scripts/translations/translation_analyzer.py --language pl-PL

# Validate TOML structure
python3 scripts/translations/validate_json_structure.py --language pl-PL

# Validate placeholders
python3 scripts/translations/validate_placeholders.py --language pl-PL

See scripts/translations/README.md for complete documentation.

3.1 KiB Raw Blame History