# 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:**
```bash
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:**
```bash
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**
```bash
# 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:**
```html
<!-- BEFORE -->
<button>Generate</button>
<label>Language:</label>

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

**JavaScript Files:**
```javascript
// 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:

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

With proper translations:
```json
{
  "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
```html
<h1 data-i18n="app_title">Password Generator</h1>
```

### **Issue: Hardcoded JavaScript strings**
**Solution:** Use `this.t()` method
```javascript
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:**
   ```bash
   php extract-translations.php
   ```

2. **Fix the highest-priority strings first**

3. **Test in multiple languages:**
   ```bash
   # 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! 🌍✨