Merge pull request #366 from adamspd/361-i18n-implementation

Implement i18n/l10n with French translation and UX enhancements

Author: adamspd

.gitignore

@@ -67,10 +67,6 @@ coverage.xml
 .pytest_cache/
 cover/
 
-# Translations
-*.mo
-*.pot
-
 # Django stuff:
 *.log
 local_settings.py
@@ -178,4 +174,7 @@ cython_debug/
 **/.DS_Store/**
 **/migrations/**
 /services/
-locale/
+data
+
+*.pyc
+*.pyx

INTERNATIONALIZATION.md

@@ -0,0 +1,196 @@
+# Internationalization (i18n) Guide 🌍
+
+Django-Appointment includes built-in internationalization support with localized date formats, translations, and multi-language capabilities.
+
+## Built-in Language Support 🗣️
+
+Django-Appointment currently includes translations for:
+- **English** (en) - Default
+- **French** (fr) - Complete translation
+
+## Quick Setup
+
+### 1. Enable Internationalization in Django
+
+Add these settings to your `settings.py`:
+
+```python
+# Internationalization
+LANGUAGE_CODE = 'en'  # Default language
+USE_I18N = True       # Enable translations
+USE_L10N = True       # Enable localized formatting
+USE_TZ = True         # Enable timezone support
+
+# Supported languages
+LANGUAGES = [
+    ('en', 'English'),
+    ('fr', 'French'),
+    # Add more languages as needed
+]
+
+# Translation files location
+LOCALE_PATHS = [
+    BASE_DIR / 'locale',
+]
+```
+
+### 2. Add Middleware
+
+Add the locale middleware to your `MIDDLEWARE` setting:
+
+```python
+MIDDLEWARE = [
+    # ... other middleware
+    'django.middleware.locale.LocaleMiddleware',
+    # ... other middleware
+]
+```
+
+### 3. Language Switching
+
+Include language switching in your URLs:
+
+```python
+# urls.py
+from django.conf.urls.i18n import i18n_patterns
+from django.urls import path, include
+
+urlpatterns = [
+    path('i18n/', include('django.conf.urls.i18n')),
+]
+
+urlpatterns += i18n_patterns(
+    path('appointment/', include('appointment.urls')),
+    # ... other URL patterns
+)
+```
+
+## Localized Date Formats 📅
+
+Django-Appointment automatically formats dates according to the user's language:
+
+- **English**: "Thu, August 14, 2025"
+- **French**: "jeu 14 août 2025"
+- **German**: "Do, 14. August 2025"
+- **Spanish**: "jue, 14 de agosto de 2025"
+
+The package includes date format patterns for 35+ languages. No additional configuration needed!
+
+## Contributing Translations 🤝
+
+Want to add support for your language? We'd love your help!
+
+### Adding a New Language
+
+1. **Fork the repository** and create a new branch
+2. **Generate translation files**:
+   ```bash
+   python manage.py makemessages -l [language_code]
+   # Example: python manage.py makemessages -l es
+   ```
+3. **Translate the strings** in `locale/[language_code]/LC_MESSAGES/django.po`
+4. **Add date format** to `appointment/utils/date_time.py` in the `DATE_FORMATS` dictionary
+5. **Test your translations**:
+   ```bash
+   python manage.py compilemessages
+   ```
+6. **Submit a pull request**
+
+### Translation Guidelines
+
+- Use formal tone for UI elements
+- Keep technical terms consistent
+- Test date formats with real examples
+- Include gender-neutral language where possible
+
+## Advanced: Translating Database Content 🗃️
+
+For translating service names, descriptions, and other database content, you can use third-party packages:
+
+### Option 1: django-modeltranslation
+
+1. **Install the package**:
+   ```bash
+   pip install django-modeltranslation
+   ```
+
+2. **Add to INSTALLED_APPS**:
+   ```python
+   INSTALLED_APPS = [
+       'modeltranslation',
+       'appointment',  # Must come after modeltranslation
+       # ... other apps
+   ]
+   ```
+
+3. **Create translation configuration**:
+   ```python
+   # translation.py (in your project root)
+   from modeltranslation.translator import translator, TranslationOptions
+   from appointment.models import Service
+
+   class ServiceTranslationOptions(TranslationOptions):
+       fields = ('name', 'description')
+
+   translator.register(Service, ServiceTranslationOptions)
+   ```
+
+4. **Generate and run migrations**:
+   ```bash
+   python manage.py makemigrations
+   python manage.py migrate
+   ```
+
+### Option 2: django-parler
+
+1. **Install the package**:
+   ```bash
+   pip install django-parler
+   ```
+
+2. **Follow django-parler documentation** for setup and configuration
+
+## Language-Specific Features 🎯
+
+### Right-to-Left (RTL) Languages
+
+Django-Appointment includes basic RTL support for languages like Arabic and Hebrew. The date formats are properly configured for RTL display.
+
+### Pluralization
+
+The package correctly handles plural forms for time durations:
+- English: "1 hour" vs "2 hours"
+- French: "1 heure" vs "2 heures"
+- And more complex rules for languages like Russian or Arabic
+
+## Troubleshooting 🔧
+
+### Common Issues
+
+1. **Dates showing in wrong format**:
+   - Ensure `USE_L10N = True` in settings
+   - Check that locale middleware is enabled
+   - Verify language code is supported
+
+2. **Translations not appearing**:
+   - Run `python manage.py compilemessages`
+   - Check `LOCALE_PATHS` setting
+   - Verify middleware order
+
+3. **Mixed language content**:
+   - Database content requires separate translation (see above)
+   - UI elements use Django's translation system
+
+### Getting Help
+
+- Check the [main documentation](https://django-appt-doc.adamspierredavid.com)
+- Open an issue on [GitHub](https://github.com/adamspd/django-appointment/issues)
+- Join the discussion in our [community](https://github.com/adamspd/django-appointment/discussions)
+
+## Supported Date Format Languages 📊
+
+Currently includes date format patterns for:
+
+Arabic, Bengali, Bulgarian, Chinese, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hebrew, Hindi, Croatian, Hungarian, Indonesian, Italian, Japanese, Korean, Latvian, Lithuanian, Malay, Norwegian, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Serbian, Spanish, Swedish, Thai, Turkish, Ukrainian, Vietnamese
+
+Missing your language? Please contribute!

MANIFEST.in

@@ -29,6 +29,7 @@ recursive-include appointment/static/img *.jpg
 recursive-include appointment/templates/ *.html
 recursive-include appointment/tests *.py
 recursive-include appointment/utils *.py
+recursive-include appointment/locale *.po *.mo
 
 # Exclusions
 exclude release_notes.md

README.md

@@ -275,6 +275,31 @@ See an example of a base.html template [here](https://github.com/adamspd/django-
 2. Modify these values as needed for your application, and the app will adapt to the new settings.
 3. For further customization, you can extend the provided models, views, and templates or create your own.
 
+## Internationalization 🌍
+
+Django-Appointment includes built-in support for multiple languages with localized date formats and translations.
+
+**Currently supported languages:**
+- English (en) - Default
+- French (fr) - Complete translation
+
+**Features:**
+- 🗣️ UI translations for 2 languages (more welcome!)
+- 📅 Localized date formats for 35+ languages
+- 🌐 Automatic language detection
+- 📝 RTL language support
+
+**Quick setup:**
+```python
+# settings.py
+USE_I18N = True
+USE_L10N = True
+LANGUAGES = [('en', 'English'), ('fr', 'French')]
+```
+
+**Want to add your language or translate database content?**
+👉 **[See the full Internationalization Guide](INTERNATIONALIZATION.md)**
+
 ## Docker Support 🐳
 
 Django-Appointment now supports Docker, making it easier to set up, develop, and test.

appointment/__init__.py

@@ -6,5 +6,5 @@
 __url__ = "https://github.com/adamspd/django-appointment"
 __package_website__ = "https://django-appt.adamspierredavid.com/"
 __package_doc_url__ = "https://django-appt-doc.adamspierredavid.com/"
-__version__ = "3.8.0"
-__test_version__ = False
+__version__ = "3.9.0"
+__test_version__ = True

appointment/forms.py

@@ -20,8 +20,10 @@
 
 class SlotForm(forms.Form):
     selected_date = forms.DateField(validators=[not_in_the_past])
-    staff_member = forms.ModelChoiceField(StaffMember.objects.all(),
-                                          error_messages={'invalid_choice': 'Staff member does not exist'})
+    staff_member = forms.ModelChoiceField(
+            StaffMember.objects.all(),
+            error_messages={'invalid_choice': _('Staff member does not exist')}
+    )
 
 
 class AppointmentRequestForm(forms.ModelForm):
@@ -35,7 +37,7 @@ class Meta:
         model = AppointmentRescheduleHistory
         fields = ['reason_for_rescheduling']
         widgets = {
-            'reason_for_rescheduling': forms.Textarea(attrs={'rows': 4, 'placeholder': 'Reason for rescheduling...'}),
+            'reason_for_rescheduling': forms.Textarea(attrs={'rows': 4, 'placeholder': _('Reason for rescheduling...')}),
         }
 
 
@@ -50,7 +52,7 @@ def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.fields['phone'].widget.attrs.update(
                 {
-                    'placeholder': '1234567890'
+                    'placeholder': _('1234567890')
                 })
         self.fields['additional_info'].widget.attrs.update(
                 {
@@ -61,26 +63,26 @@ def __init__(self, *args, **kwargs):
                 {
                     'rows': 2,
                     'class': 'form-control',
-                    'placeholder': '1234 Main St, City, State, Zip Code',
+                    'placeholder': _('1234 Main St, City, State, Zip Code'),
                     'required': 'true'
                 })
         self.fields['additional_info'].widget.attrs.update(
                 {
                     'class': 'form-control',
-                    'placeholder': 'I would like to be contacted by phone.'
+                    'placeholder': _('I would like to be contacted by phone.')
                 })
 
 
 class ClientDataForm(forms.Form):
-    name = forms.CharField(max_length=50, widget=forms.TextInput(attrs={'class': 'form-control'}))
-    email = forms.EmailField(widget=forms.EmailInput(attrs={'class': 'form-control'}))
+    name = forms.CharField(max_length=50, widget=forms.TextInput(attrs={'class': 'form-control', 'placeholder': _('John Doe')}))
+    email = forms.EmailField(widget=forms.EmailInput(attrs={'class': 'form-control', 'placeholder': _('[email protected]')}))
 
 
 class PersonalInformationForm(forms.Form):
     # first_name, last_name, email
-    first_name = forms.CharField(max_length=50, widget=forms.TextInput(attrs={'class': 'form-control'}))
-    last_name = forms.CharField(max_length=50, widget=forms.TextInput(attrs={'class': 'form-control'}))
-    email = forms.EmailField(widget=forms.EmailInput(attrs={'class': 'form-control'}))
+    first_name = forms.CharField(max_length=50, widget=forms.TextInput(attrs={'class': 'form-control', 'placeholder': _('John')}))
+    last_name = forms.CharField(max_length=50, widget=forms.TextInput(attrs={'class': 'form-control', 'placeholder': _('Doe')}))
+    email = forms.EmailField(widget=forms.EmailInput(attrs={'class': 'form-control', 'placeholder': _('[email protected]')}))
 
     def __init__(self, *args, **kwargs):
         self.user = kwargs.pop('user', None)  # pop the user from the kwargs
@@ -205,19 +207,19 @@ class Meta:
             }),
             'description': forms.Textarea(attrs={
                 'class': 'form-control',
-                'placeholder': "Example: Overview of client's needs."
+                'placeholder': _("Example: Overview of client's needs.")
             }),
             'duration': forms.TextInput(attrs={
                 'class': 'form-control',
-                'placeholder': 'HH:MM:SS, (example: 00:15:00 for 15 minutes)'
+                'placeholder': _('HH:MM:SS, (example: 00:15:00 for 15 minutes)')
             }),
             'price': forms.NumberInput(attrs={
                 'class': 'form-control',
-                'placeholder': 'Example: 100.00 (0 for free)'
+                'placeholder': _('Example: 100.00 (0 for free)')
             }),
             'down_payment': forms.NumberInput(attrs={
                 'class': 'form-control',
-                'placeholder': 'Example: 50.00 (0 for free)'
+                'placeholder': _('Example: 50.00 (0 for free)')
             }),
             'image': forms.ClearableFileInput(attrs={'class': 'form-control'}),
             'currency': forms.Select(choices=[('USD', 'USD'), ('EUR', 'EUR'), ('GBP', 'GBP')],