256 lines
6.5 KiB
Markdown
256 lines
6.5 KiB
Markdown
# 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! 🌍✨ |