mirror of https://github.com/Frooodle/Stirling-PDF.git synced 2025-11-16 01:21:16 +01:00

feat(scripts): enhance translation progress tool with CLI flags, TOML management, and CI-friendly output (#4801 )

# Description of Changes

- **What was changed**
- Refactored `scripts/counter_translation.py` into a more modular CLI
tool.
  - Added argument parsing with new flags:
    - `--lang/-l` to check a single `messages_*.properties` file.
- `--show-percentage/-sp` to print **only** the numeric percentage
(useful for CI).
- `--show-missing-keys/-smk` to list untranslated keys for a single
language.
- Introduced `main()` entrypoint and helper `_lang_from_path()` for
robust language code extraction.
  - Improved comparison logic:
    - Skips header lines, trims values, and tolerates BOM.
    - Treats `en_GB`/`en_US` as 100% translated.
- Tracks and reports missing keys; removes keys from ignore list once
translated.
  - Hardened TOML handling:
- Automatically creates/updates `scripts/ignore_translation.toml` when
absent.
    - `convert_to_multiline()` normalizes/sorts arrays for stable diffs.
  - README integration:
    - `write_readme()` updates language badges from computed progress.
- Added type hints, richer docstrings, usage examples, and clearer
console messages.
  - Deduplicates language results and sorts by percentage (desc).
  - Uses consistent UTF-8 and newline handling.

- **Why the change was made**
- Make translation tracking **automation-ready** (CI pipelines can
consume a single number).
- Reduce manual maintenance of ignore lists and improve
**deterministic** formatting for clean diffs.
- Provide better **developer UX** with explicit flags and actionable
diagnostics (missing keys).
- Increase correctness and maintainability via structured code, typing,
and clear responsibilities.


---

## Checklist

### General

- [x] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [x] 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)
- [x] I have performed a self-review of my own code
- [x] 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)

### 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-11-02 16:34:22 +00:00

2.8 KiB

Raw Blame History

`counter_translation.py`

Overview

The script scripts/counter_translation.py checks the translation progress of the property files in the directory app/core/src/main/resources/. It compares each messages_*.properties file with the English reference file messages_en_GB.properties and calculates a percentage of completion for each language.

In addition to console output, the script automatically updates the progress badges in the project’s README.md and maintains the configuration file scripts/ignore_translation.toml, which lists translation keys to be ignored for each language.

Requirements

Python 3.10 or newer (requires tomlkit).
Must be executed from the project root directory so all relative paths are resolved correctly.
Write permissions for README.md and scripts/ignore_translation.toml.

Default usage

python scripts/counter_translation.py

This command:

scans app/core/src/main/resources/ for all messages_*.properties files,
calculates the translation progress for each file,
updates the badges in README.md,
reformats scripts/ignore_translation.toml (sorted, multi-line arrays).

Check a single language

python scripts/counter_translation.py --lang messages_fr_FR.properties

The specified file can be given as a relative (to the resources folder) or absolute path.
The result is printed to the console (e.g. fr_FR: 87% translated).
With --show-missing-keys, all untranslated keys are listed as well.

Output only the percentage

For scripts or CI pipelines, the output can be reduced to just the percentage value:

python scripts/counter_translation.py --lang messages_fr_FR.properties --show-percentage

The console will then only print 87 (without the percent symbol or any extra text).

Handling `ignore_translation.toml`

If a language section is missing, the script creates it automatically.
Entries in ignore are alphabetically sorted and written as multi-line arrays.
By default, language.direction is ignored. If that key is later translated, the script automatically removes it from the ignore list.

Integration in Pull Requests

Whenever translations are updated, this script should be executed. The updated badges and the modified ignore_translation.toml should be committed together with the changed messages_*.properties files.

Troubleshooting

File not found: Check the path or use --lang with an absolute path.
Line error: The script reports the specific line in both files—this usually means a missing = or an unmatched line.
Incorrect percentages in README: Make sure the script was run from the project root and that write permissions are available.

2.8 KiB Raw Blame History Unescape Escape

counter_translation.py