Stirling-PDF/HowToAddNewLanguage.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

73 lines
3.7 KiB
Markdown
Raw Normal View History

2024-11-03 08:20:10 +01:00
<p align="center">
<img src="https://raw.githubusercontent.com/Stirling-Tools/Stirling-PDF/main/docs/stirling.png" width="80">
<br>
<h1 align="center">Stirling-PDF</h1>
2023-02-05 22:40:25 +01:00
</p>
2023-02-05 13:54:48 +01:00
# How to add new languages to Stirling-PDF
2024-11-03 08:20:10 +01:00
Fork Stirling-PDF and create a new branch out of `main`.
2023-02-05 13:54:48 +01:00
2024-11-03 08:20:10 +01:00
Then add a reference to the language in the navbar by adding a new language entry to the dropdown:
2023-02-05 13:54:48 +01:00
2024-11-03 08:20:10 +01:00
- Edit the file: [languages.html](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/src/main/resources/templates/fragments/languages.html)
- Add a flag SVG file to: [flags directory](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/src/main/resources/static/images/flags)
2023-05-12 21:35:17 +02:00
2024-11-03 08:20:10 +01:00
Any SVG flags are fine; most of the current ones were sourced from [here](https://flagicons.lipis.dev/). If your language isn't represented by a flag, choose a similar one, such as Saudi Arabia's flag for Arabic.
For example, to add Polish, you would add:
```html
2024-11-03 08:20:10 +01:00
<a class="dropdown-item lang_dropdown-item" href="" data-bs-language-code="pl_PL">
2023-05-12 21:35:17 +02:00
<img src="images/flags/pl.svg" alt="icon" width="20" height="15"> Polski
</a>
2023-02-05 13:54:48 +01:00
```
2024-11-03 08:20:10 +01:00
The `data-bs-language-code` is the code used to reference the file in the next step.
### Add Language Property File
2023-02-05 13:54:48 +01:00
2024-11-03 08:20:10 +01:00
Start by copying the existing English property file:
2023-02-05 13:54:48 +01:00
2024-11-03 08:20:10 +01:00
- [messages_en_GB.properties](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/src/main/resources/messages_en_GB.properties)
2023-02-05 13:54:48 +01:00
2024-11-03 08:20:10 +01:00
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`.
2023-02-05 13:54:48 +01:00
2024-11-03 08:20:10 +01:00
Then simply translate all property entries within that file and make a Pull Request (PR) into `main` for others to use!
2023-02-05 13:54:48 +01:00
2024-11-03 08:20:10 +01:00
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).
2023-02-05 13:54:48 +01:00
## Handling Untranslatable Strings
2023-02-05 13:54:48 +01:00
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.
2023-02-05 13:54:48 +01:00
2024-11-03 08:20:10 +01:00
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:
```toml
[pl_PL]
ignore = [
"language.direction", # Existing entries
"error" # Add new entries here
]
```
## Add New Translation Tags
2024-11-03 08:20:10 +01:00
> [!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.
- 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`).
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.
expand: check language properties (#2724) # Description Improvement in `check_language_properties.py`: Added support for local Windows commands to check language properties files with an updated script. Added a new optional argument `--check-file` to specify a single file to check, replacing the need to process all files in the directory. Adjusted file path handling to better support Windows paths. Update to `update-translations.yml`: Added `workflow_dispatch` trigger to allow manual execution of the workflow. Documentation update in `HowToAddNewLanguage.md`: Added instructions for running the language properties check locally on Windows, including example commands. These changes streamline the process of checking language properties files and provide additional flexibility for local testing and manual workflow triggering. ## Checklist - [x] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) - [x] I have performed a self-review of my own code - [ ] I have attached images of the change if it is UI based - [x] I have commented my code, particularly in hard-to-understand areas - [ ] If my code has heavily changed functionality I have updated relevant docs on [Stirling-PDFs doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) - [x] My changes generate no new warnings - [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only)
2025-01-16 23:03:54 +01:00
### Use this code to perform a local check
#### Windows command
```ps
python .github/scripts/check_language_properties.py --reference-file src\main\resources\messages_en_GB.properties --branch "" --files src\main\resources\messages_pl_PL.properties
python .github/scripts/check_language_properties.py --reference-file src\main\resources\messages_en_GB.properties --branch "" --check-file src\main\resources\messages_pl_PL.properties
```