pw-generator/utils/TRANSLATION_README.md

Translation Management Tools

📝 Overview

This directory contains tools and utilities for managing translations across the Password Generator application. These tools help identify, extract, and maintain translatable strings across HTML, JavaScript, and PHP files.

🛠️ Tools Provided

1. extract-translations.php

Advanced PHP-based translation extractor that scans your codebase and automatically generates/updates translation files.

Features:

• ✅ Scans HTML, JavaScript, and PHP files
• ✅ Extracts data-i18n attributes
• ✅ Finds this.t() calls in JavaScript
• ✅ Identifies hardcoded strings
• ✅ Generates translation keys automatically
• ✅ Updates existing translation files
• ✅ Provides basic translations for common strings
• ✅ Preserves consistent key structure across locales

Usage:

php extract-translations.php

2. update-translations.sh

Shell script for quick translation file updates and scanning.

Features:

• ✅ Fast scanning with grep/sed
• ✅ Updates all language files at once
• ✅ Shows translation coverage statistics
• ✅ Identifies hardcoded strings
• ✅ Color-coded output

Usage:

chmod +x update-translations.sh
./update-translations.sh

📋 Current Translation Status

Supported Languages

• 🇺🇸 English (en) - Base language
• 🇩🇪 German (de) - Partially translated
• 🇫🇷 French (fr) - Partially translated
• 🇮🇹 Italian (it) - Placeholders only
• 🇪🇸 Spanish (es) - Placeholders only
• 🇯🇵 Japanese (ja) - Placeholders only
• 🇨🇳 Chinese (zh) - Placeholders only

Translation Keys Identified

The tools have identified these categories of translatable strings:

UI Elements

• generate - Generate button text
• copy - Copy button text
• language - Language selector label
• options - Options section header
• loading - Loading messages
• error - Error messages
• success - Success messages

Password Generator Types

• high_entropy - High Entropy generator name
• xkcd_pass - XKCD Pass generator name
• diceware - Diceware generator name
• pwgen - PWGen generator name
• passkey - Passkey generator name

API Documentation

• api_documentation - API Documentation link
• download - Download button text
• interactive_api_explorer - API Explorer heading
• openapi_json - OpenAPI JSON description
• postman_collection - Postman Collection description

🔧 How to Use These Tools

Step 1: Run the Extractor

# Use the PHP extractor for comprehensive analysis
php extract-translations.php

# OR use the shell script for quick updates
./update-translations.sh

Step 2: Review Generated Files

Check the locales/ directory for:

• Updated JSON files for each language
• Any missing or placeholder translation entries that still need review

Step 3: Fix Hardcoded Strings

HTML Files:

<!-- BEFORE -->
<button>Generate</button>
<label>Language:</label>

<!-- AFTER -->
<button data-i18n="generate">Generate</button>
<label data-i18n="language">Language:</label>

JavaScript Files:

// BEFORE
showNotification('Copied to clipboard!');
generateBtn.innerHTML = 'Generating...';

// AFTER  
showNotification(this.t('copied_to_clipboard'));
generateBtn.innerHTML = this.t('generating');

Step 4: Translate Placeholder Strings

Replace placeholder entries in language files:

{
  "generate": "Generate (TODO: de)",  // ← Replace this
  "copy": "Kopieren"                  // ✅ Already translated
}

With proper translations:

{
  "generate": "Generieren",          // ✅ Properly translated
  "copy": "Kopieren"                 // ✅ Already translated
}

📊 Translation Statistics

Run the tools to get current statistics:

📊 Translation Status Report
============================
en: 87/87 (100%) translated
de: 45/87 (52%) translated  
fr: 32/87 (37%) translated
it: 15/87 (17%) translated
es: 15/87 (17%) translated
ja: 0/87 (0%) translated
zh: 0/87 (0%) translated

🎯 Quick Win Translations

High Priority Strings (Visible to Users)

1. generate → "Generate" button
2. copy → "Copy" button
3. language → Language selector
4. loading_generators → Loading message
5. api_documentation → Header link
6. back_to_generator → Navigation link

Common Translations Already Provided

German (de):

• generate → "Generieren"
• copy → "Kopieren"
• language → "Sprache"
• password_generator → "Passwort-Generator"

French (fr):

• generate → "Générer"
• copy → "Copier"
• language → "Langue"
• password_generator → "Générateur de mots de passe"

🚨 Common Issues & Solutions

Issue: Missing data-i18n attributes

Solution: Add data-i18n="key" to HTML elements

<h1 data-i18n="app_title">Password Generator</h1>

Issue: Hardcoded JavaScript strings

Solution: Use this.t() method

const message = this.t('copied_to_clipboard');

Issue: Translation not appearing

Solution: Check that:

1. Translation key exists in JSON file
2. data-i18n attribute is correct
3. updateUI() is called after content changes

📈 Improvement Roadmap

Phase 1: Core UI (Current)

• ✅ Main navigation
• ✅ Generator cards
• ✅ Button text
• ✅ Form labels

Phase 2: API Documentation

• 🔄 Swagger page content
• 🔄 Download descriptions
• 🔄 Example text

Phase 3: Advanced Features

• ⏳ Error messages
• ⏳ Validation text
• ⏳ Help tooltips

💡 Best Practices

Translation Keys

• Use snake_case format
• Be descriptive but concise
• Group related keys with prefixes:
  • error_* for error messages
  • button_* for button text
  • label_* for form labels

String Extraction

• Run tools regularly during development
• Check for new hardcoded strings after UI changes
• Update translations before releases

Quality Assurance

• Test UI in multiple languages
• Check for text overflow in different languages
• Verify special characters display correctly

---

🚀 Getting Started

1. Run the extractor:

   php extract-translations.php
   

2. Fix the highest-priority strings first

3. Test in multiple languages:

   # Change language in the UI dropdown
   # Or visit: http://localhost:8080/?lang=de
   

4. Iterate and improve

Your translation management system is now ready to ensure a fully internationalized Password Generator application! 🌍✨