Add translations for ar-AR, de-DE, fr-FR, it-IT, pt-BR, ru-RU and ena… (#4572)

…ble in frontend - Updated ar-AR (Arabic) to 98.7% completion (1088 entries) - Updated fr-FR (French) to 97.3% completion (1296 entries) - Updated pt-BR (Portuguese Brazil) to 98.6% completion (1294 entries) - Updated ru-RU (Russian) to 98.1% completion (1277 entries) - Updated ja-JP (Japanese) to 73.4% completion (796 entries, batches 1-2) - Updated es-ES minor corrections - Enabled 8 languages with >90% completion in LanguageSelector - Added JSON validation scripts for translation quality assurance - RTL support already enabled for ar-AR Enabled languages: en-GB, ar-AR, de-DE, es-ES, fr-FR, it-IT, pt-BR, ru-RU, zh-CN 🤖 Generated with [Claude Code](https://claude.com/claude-code) # Description of Changes  --- ## 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) ### 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. Co-authored-by: Claude <[email protected]>
2026-07-16 19:33:11 +02:00 · 2025-10-01 12:58:41 +01:00
parent 3dd4a33595
commit 0fa53185f2
11 changed files with 10963 additions and 2450 deletions
@@ -1,9 +1,96 @@
 # Translation Management Scripts

-This directory contains Python scripts for managing frontend translations in Stirling PDF. These tools help analyze, merge, and manage translations against the en-GB golden truth file.
+This directory contains Python scripts for managing frontend translations in Stirling PDF. These tools help analyze, merge, validate, and manage translations against the en-GB golden truth file.

 ## Scripts Overview

+### 0. Validation Scripts (Run First!)
+
+#### `json_validator.py`
+Validates JSON syntax in translation files with detailed error reporting.
+
+**Usage:**
+```bash
+# Validate single file
+python scripts/translations/json_validator.py ar_AR_batch_1_of_3.json
+
+# Validate all batches for a language
+python scripts/translations/json_validator.py --all-batches ar_AR
+
+# Validate pattern with wildcards
+python scripts/translations/json_validator.py "ar_AR_batch_*.json"
+
+# Brief output (no context)
+python scripts/translations/json_validator.py --all-batches ar_AR --brief
+
+# Only show files with errors
+python scripts/translations/json_validator.py --all-batches ar_AR --quiet
+```
+
+**Features:**
+- Validates JSON syntax with detailed error messages
+- Shows exact line, column, and character position of errors
+- Displays context around errors for easy fixing
+- Suggests common fixes based on error type
+- Detects unescaped quotes and backslashes
+- Reports entry counts for valid files
+- Exit code 1 if any files invalid (good for CI/CD)
+
+**Common Issues Detected:**
+- Unescaped quotes inside strings: `"text with "quotes""` → `"text with \"quotes\""`
+- Invalid backslash escapes: `\d{4}` → `\\d{4}`
+- Missing commas between entries
+- Trailing commas before closing braces
+
+#### `validate_placeholders.py`
+Validates that translation files have correct placeholders matching en-GB (source of truth).
+
+**Usage:**
+```bash
+# Validate all languages
+python scripts/translations/validate_placeholders.py
+
+# Validate specific language
+python scripts/translations/validate_placeholders.py --language es-ES
+
+# Show detailed text samples
+python scripts/translations/validate_placeholders.py --verbose
+
+# Output as JSON
+python scripts/translations/validate_placeholders.py --json
+```
+
+**Features:**
+- Detects missing placeholders (e.g., {n}, {total}, {filename})
+- Detects extra placeholders not in en-GB
+- Shows exact keys and text where issues occur
+- Exit code 1 if issues found (good for CI/CD)
+
+#### `validate_json_structure.py`
+Validates JSON structure and key consistency with en-GB.
+
+**Usage:**
+```bash
+# Validate all languages
+python scripts/translations/validate_json_structure.py
+
+# Validate specific language
+python scripts/translations/validate_json_structure.py --language de-DE
+
+# Show all missing/extra keys
+python scripts/translations/validate_json_structure.py --verbose
+
+# Output as JSON
+python scripts/translations/validate_json_structure.py --json
+```
+
+**Features:**
+- Validates JSON syntax
+- Detects missing keys (not translated yet)
+- Detects extra keys (not in en-GB, should be removed)
+- Reports key counts and structure differences
+- Exit code 1 if issues found (good for CI/CD)
+
 ### 1. `translation_analyzer.py`
 Analyzes translation files to find missing translations, untranslated entries, and provides completion statistics.

@@ -142,7 +229,20 @@ python scripts/translations/translation_analyzer.py --language it-IT --summary

 #### Step 2: Extract Untranslated Entries
 ```bash
+# For small files (< 1200 entries)
 python scripts/translations/compact_translator.py it-IT --output to_translate.json
+
+# For large files, split into batches
+python scripts/translations/compact_translator.py it-IT --output it_IT_batch --batch-size 400
+# Creates: it_IT_batch_1_of_N.json, it_IT_batch_2_of_N.json, etc.
+```
+
+#### Step 2.5: Validate JSON (if using batches)
+```bash
+# After AI translates the batches, validate them before merging
+python scripts/translations/json_validator.py --all-batches it_IT
+
+# Fix any errors reported (common issues: unescaped quotes, backslashes)
 ```

 **Output format**: Compact JSON with minimal whitespace
@@ -309,6 +409,34 @@ ignore = [

 ### Common Issues and Solutions

+#### JSON Syntax Errors in AI Translations
+**Problem**: AI-translated batch files have JSON syntax errors
+**Symptoms**:
+- `JSONDecodeError: Expecting ',' delimiter`
+- `JSONDecodeError: Invalid \escape`
+
+**Solution**:
+```bash
+# 1. Validate all batches to find errors
+python scripts/translations/json_validator.py --all-batches ar_AR
+
+# 2. Check detailed error with context
+python scripts/translations/json_validator.py ar_AR_batch_2_of_3.json
+
+# 3. Fix the reported issues:
+#    - Unescaped quotes: "text with "quotes"" → "text with \"quotes\""
+#    - Backslashes in regex: "\d{4}" → "\\d{4}"
+#    - Missing commas between entries
+
+# 4. Validate again until all pass
+python scripts/translations/json_validator.py --all-batches ar_AR
+```
+
+**Common fixes:**
+- Arabic/RTL text with embedded quotes: Always escape with backslash
+- Regex patterns: Double all backslashes (`\d` → `\\d`)
+- Check for missing/extra commas at line reported in error
+
 #### [UNTRANSLATED] Pollution
 **Problem**: Hundreds of [UNTRANSLATED] markers from incomplete translation attempts
 **Solution**:
@@ -326,6 +454,54 @@ ignore = [

 ## Real-World Examples

+### Complete Arabic Translation with Validation (Batch Method)
+```bash
+# Check status
+python scripts/translations/translation_analyzer.py --language ar-AR --summary
+# Result: 50% complete, 1088 missing
+
+# Extract in batches due to AI token limits
+python scripts/translations/compact_translator.py ar-AR --output ar_AR_batch --batch-size 400
+# Created: ar_AR_batch_1_of_3.json (400 entries)
+#          ar_AR_batch_2_of_3.json (400 entries)
+#          ar_AR_batch_3_of_3.json (288 entries)
+
+# [Send each batch to AI for translation]
+
+# Validate translated batches before merging
+python scripts/translations/json_validator.py --all-batches ar_AR
+# Found errors in batch 1 and 2:
+#   - Line 263: Unescaped quotes in "انقر "إضافة ملفات""
+#   - Line 132: Unescaped quotes in "أو "and""
+#   - Line 213: Invalid escape "\d{4}"
+
+# Fix errors manually or with sed, then validate again
+python scripts/translations/json_validator.py --all-batches ar_AR
+# All valid!
+
+# Merge all batches
+python3 << 'EOF'
+import json
+merged = {}
+for i in range(1, 4):
+    with open(f'ar_AR_batch_{i}_of_3.json', 'r', encoding='utf-8') as f:
+        merged.update(json.load(f))
+with open('ar_AR_merged.json', 'w', encoding='utf-8') as f:
+    json.dump(merged, f, ensure_ascii=False, indent=2)
+EOF
+
+# Apply merged translations
+python scripts/translations/translation_merger.py ar-AR apply-translations --translations-file ar_AR_merged.json
+# Result: Applied 1088 translations
+
+# Beautify to match en-GB structure
+python scripts/translations/json_beautifier.py --language ar-AR
+
+# Check final progress
+python scripts/translations/translation_analyzer.py --language ar-AR --summary
+# Result: 98.7% complete, 9 missing, 20 untranslated
+```
+
 ### Complete Italian Translation (Compact Method)
 ```bash
 # Check status