Kobelly/example_usage.md

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):

<h1>{{ _('Welcome to Kobelly Web Solutions') }}</h1>
<p>{{ _('We create stunning, modern websites') }}</p>

New (JSON-based):

<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:

<h2>{{ t('New Section Title') }}</h2>

2. Add it to the translation files:

// 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:

<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:

{{ create_language_selector() | safe }}

🛠️ Management Scripts

Extract New Strings

python extract_translations.py

Clean Translation Files

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

{
  "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:

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