167 lines
3.9 KiB
Markdown
167 lines
3.9 KiB
Markdown
# JSON-Based Translation System for Kobelly
|
|
|
|
## 🎉 Benefits of This System
|
|
|
|
✅ **No compilation needed** - Just edit JSON files directly
|
|
✅ **Edit English without breaking translations** - Each language is independent
|
|
✅ **Simple and lightweight** - No complex dependencies
|
|
✅ **Real-time updates** - Changes appear immediately after restart
|
|
✅ **Easy to maintain** - Clear JSON structure
|
|
|
|
## 📁 File Structure
|
|
|
|
```
|
|
translations/
|
|
├── en.json # English translations
|
|
├── de.json # German translations
|
|
├── fr.json # French translations
|
|
└── nl.json # Dutch translations
|
|
```
|
|
|
|
## 🔧 How to Use
|
|
|
|
### 1. In Templates
|
|
|
|
Replace Babel syntax with the new system:
|
|
|
|
**Old (Babel):**
|
|
```html
|
|
<h1>{{ _('Welcome to Kobelly Web Solutions') }}</h1>
|
|
<p>{{ _('We create stunning, modern websites') }}</p>
|
|
```
|
|
|
|
**New (JSON-based):**
|
|
```html
|
|
<h1>{{ translate('Welcome to Kobelly Web Solutions') }}</h1>
|
|
<p>{{ translate('We create stunning, modern websites') }}</p>
|
|
|
|
<!-- Or use the short alias -->
|
|
<h1>{{ t('Welcome to Kobelly Web Solutions') }}</h1>
|
|
<p>{{ t('We create stunning, modern websites') }}</p>
|
|
```
|
|
|
|
### 2. Adding New Translations
|
|
|
|
1. **Add the string to your template:**
|
|
```html
|
|
<h2>{{ t('New Section Title') }}</h2>
|
|
```
|
|
|
|
2. **Add it to the translation files:**
|
|
```json
|
|
// translations/en.json
|
|
{
|
|
"New Section Title": "New Section Title"
|
|
}
|
|
|
|
// translations/de.json
|
|
{
|
|
"New Section Title": "Neuer Abschnittstitel"
|
|
}
|
|
```
|
|
|
|
3. **Restart your Flask app** - Changes appear immediately!
|
|
|
|
### 3. Language Switching
|
|
|
|
The system automatically detects language from:
|
|
- URL parameter: `?lang=de`
|
|
- Session storage
|
|
- Browser preferences
|
|
|
|
**Manual language switching:**
|
|
```html
|
|
<a href="?lang=en">English</a>
|
|
<a href="?lang=de">Deutsch</a>
|
|
<a href="?lang=fr">Français</a>
|
|
<a href="?lang=nl">Nederlands</a>
|
|
```
|
|
|
|
**Or use the built-in selector:**
|
|
```html
|
|
{{ create_language_selector() | safe }}
|
|
```
|
|
|
|
## 🛠️ Management Scripts
|
|
|
|
### Extract New Strings
|
|
```bash
|
|
python extract_translations.py
|
|
```
|
|
|
|
### Clean Translation Files
|
|
```bash
|
|
python clean_translations.py
|
|
```
|
|
|
|
### Add New Language
|
|
1. Add language code to `SUPPORTED_LANGUAGES` in `translation_manager.py`
|
|
2. Create `translations/[lang].json`
|
|
3. Add translations
|
|
|
|
## 📝 Example Translation File
|
|
|
|
```json
|
|
{
|
|
"Home": "Home",
|
|
"Services": "Services",
|
|
"About": "About",
|
|
"Contact": "Contact",
|
|
"Welcome to Kobelly Web Solutions": "Welcome to Kobelly Web Solutions",
|
|
"We create stunning, modern websites that drive results": "We create stunning, modern websites that drive results"
|
|
}
|
|
```
|
|
|
|
## 🔄 Migration from Babel
|
|
|
|
1. **Replace template syntax:**
|
|
- `{{ _('text') }}` → `{{ t('text') }}`
|
|
- `{{ gettext('text') }}` → `{{ translate('text') }}`
|
|
|
|
2. **Remove Babel dependencies:**
|
|
- Remove `Flask-Babel` from requirements.txt
|
|
- Remove `babel.cfg`
|
|
|
|
3. **Update app.py:**
|
|
- Remove Babel imports and configuration
|
|
- Add translation manager imports
|
|
|
|
## 🚀 Getting Started
|
|
|
|
1. **Start the app:**
|
|
```bash
|
|
python app.py
|
|
```
|
|
|
|
2. **Edit translations:**
|
|
- Open `translations/[language].json`
|
|
- Replace English text with translations
|
|
- Save and restart app
|
|
|
|
3. **Test language switching:**
|
|
- Visit `http://localhost:5000?lang=de`
|
|
- Or use the language selector
|
|
|
|
## 💡 Tips
|
|
|
|
- **Keep keys descriptive** - Use full sentences as keys
|
|
- **Use consistent naming** - Follow the same pattern for similar content
|
|
- **Test all languages** - Make sure translations fit in your layout
|
|
- **Backup your translations** - JSON files are easy to version control
|
|
|
|
## 🔧 Troubleshooting
|
|
|
|
**Translations not showing?**
|
|
- Check that the key exists in the JSON file
|
|
- Restart the Flask application
|
|
- Check browser console for errors
|
|
|
|
**Language not switching?**
|
|
- Clear browser cache
|
|
- Check session storage
|
|
- Verify language code is in `SUPPORTED_LANGUAGES`
|
|
|
|
**New strings not appearing?**
|
|
- Run `python extract_translations.py` to extract new strings
|
|
- Add translations to all language files
|
|
- Restart the application |