haeaeae/Stirling-PDF
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
Anthony Stirling
2025-10-09 18:20:22 +01:00
parent b695e3900e
commit e32a0c04c4
2 changed files with 388 additions and 274 deletions
Download Patch File Download Diff File Expand all files Collapse all files
devGuide/HowToAddNewLanguage.md
+149 -27
View File
@@ -8,36 +8,66 @@
Fork Stirling-PDF and create a new branch out of `main`.
Then add a reference to the language in the navbar by adding a new language entry to the dropdown:
## Add Language to i18n Configuration
- Edit the file: [languages.html](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/app/core/src/main/resources/templates/fragments/languages.html)
Edit the file: [frontend/src/i18n.ts](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/frontend/src/i18n.ts)
Add your language to the `supportedLanguages` object. For example, to add Polish:
For example, to add Polish, you would add:
```html
<div th:replace="~{fragments/languageEntry :: languageEntry ('pl_PL', 'Polski')}" ></div>
```typescript
export const supportedLanguages = {
'en': 'English',
'en-GB': 'English (UK)',
// ... other languages ...
'pl-PL': 'Polski', // Add your language here
};
```
The `data-bs-language-code` is the code used to reference the file in the next step.
If your language uses right-to-left (RTL) text direction, also add it to the `rtlLanguages` array:
### Add Language Property File
```typescript
export const rtlLanguages = ['ar-AR', 'fa-IR', 'pl-PL']; // Add if RTL
```
Start by copying the existing English property file:
## Create Translation Directory
- [messages_en_GB.properties](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/app/core/src/main/resources/messages_en_GB.properties)
Create a new directory for your language in `frontend/public/locales/`. For Polish, this would be:
Copy and rename it to `messages_{your data-bs-language-code here}.properties`. In the Polish example, you would set the name to `messages_pl_PL.properties`.
```bash
mkdir -p frontend/public/locales/pl-PL
```
Then simply translate all property entries within that file and make a Pull Request (PR) into `main` for others to use!
## Add Translation File
If you do not have a Java IDE, I am happy to verify that the changes work once you raise the PR (but I won't be able to verify the translations themselves).
Start by copying the existing English (UK) translation file:
- [frontend/public/locales/en-GB/translation.json](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/frontend/public/locales/en-GB/translation.json)
Copy and rename it to `frontend/public/locales/{your-language-code}/translation.json`. In the Polish example:
```bash
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:
```json
{
"addPageNumbers": {
"title": "Add Page Numbers",
"submit": "Add Page Numbers",
"error": {
"failed": "Add page numbers operation failed"
}
}
}
```
## Handling Untranslatable Strings
Sometimes, certain strings in the properties file 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.
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=Error` does not need translation in Polish, add it to the `ignore_translation.toml` under the Polish section:
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:
```toml
[pl_PL]
@@ -50,27 +80,119 @@ ignore = [
## Add New Translation Tags
> [!IMPORTANT]
> If you add any new translation tags, they must first be added to the `messages_en_GB.properties` file. This ensures consistency across all language files.
> 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 `messages_en_GB.properties` file to maintain a reference for other languages.
- After adding the new tags to `messages_en_GB.properties`, add and translate them in the respective language file (e.g., `messages_pl_PL.properties`).
- 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.
### Use this code to perform a local check
## Testing Your Translation
#### Windows command
### Start the development server
```powershell
python .github/scripts/check_language_properties.py --reference-file app\core\src\main\resources\messages_en_GB.properties --branch "" --files app\core\src\main\resources\messages_pl_PL.properties
1. Start the frontend development server:
```bash
cd frontend
npm run dev
```
python .github/scripts/check_language_properties.py --reference-file app\core\src\main\resources\messages_en_GB.properties --branch "" --check-file app\core\src\main\resources\messages_pl_PL.properties
```
2. The language selector should now include your new language
#### Linux command
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:
```bash
python3 .github/scripts/check_language_properties.py --reference-file app/core/src/main/resources/messages_en_GB.properties --branch "" --files app/core/src/main/resources/messages_pl_PL.properties
# Check translation status for your language
python scripts/translations/translation_analyzer.py --language pl-PL --summary
python3 .github/scripts/check_language_properties.py --reference-file app/core/src/main/resources/messages_en_GB.properties --branch "" --check-file app/core/src/main/resources/messages_pl_PL.properties
# 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:
```bash
# 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:
```json
{
"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:
```json
{
"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:
```bash
# 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:
```bash
# 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.