feat: add internationalization support for verification messages

Add support for localizing SMS verification messages based on the
Accept-Language HTTP header. The library now automatically detects
the user's preferred language and sends verification messages in
that language using Django's translation system.

Changes:
- Extract language from Accept-Language header in API endpoint
- Add language parameter to PhoneVerificationService
- Implement message translation using Django's override and gettext
- Add comprehensive i18n documentation with setup guide
- Add tests for i18n functionality in API and service layers

Co-authored-by: Hari Mahadevan <[email protected]>

Author: CuriousLearner

CHANGELOG.rst

@@ -6,6 +6,7 @@ Release Notes
 
 Added
 """""
+- **Internationalization (i18n)**: Added support for localizing verification messages based on the ``Accept-Language`` HTTP header. The library now automatically detects the user's preferred language and sends verification messages in that language using Django's translation system. Contributed by `Hari Mahadevan <https://github.com/harikvpy>`_.
 - **Documentation**: Completely overhauled documentation to professional, enterprise-grade quality:
 
   - **Getting Started Guide** - Expanded with prerequisites, step-by-step configuration, environment variables, and testing instructions

docs/advanced_examples.rst

@@ -570,6 +570,149 @@ Implementation
         ...
     }
 
+Internationalization (i18n) Support
+------------------------------------
+
+Send verification messages in different languages based on user preferences.
+
+Overview
+^^^^^^^^
+
+The library automatically detects the user's language from the ``Accept-Language`` HTTP header
+and localizes the verification message accordingly. This is useful for applications serving
+users in multiple countries or regions.
+
+Setup
+^^^^^
+
+First, ensure Django's internationalization is enabled in your ``settings.py``:
+
+.. code-block:: python
+
+    # settings.py
+    USE_I18N = True
+    LANGUAGE_CODE = 'en-us'
+
+    LANGUAGES = [
+        ('en', 'English'),
+        ('es', 'Spanish'),
+        ('fr', 'French'),
+        ('zh-hant', 'Traditional Chinese'),
+        # Add more languages as needed
+    ]
+
+    LOCALE_PATHS = [
+        BASE_DIR / 'locale',
+    ]
+
+Create Translation Files
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create translation files for your verification message. The message template in ``PHONE_VERIFICATION['MESSAGE']``
+will be automatically translated:
+
+.. code-block:: bash
+
+    # Create locale directories
+    mkdir -p locale/es/LC_MESSAGES
+    mkdir -p locale/fr/LC_MESSAGES
+    mkdir -p locale/zh_Hant/LC_MESSAGES
+
+    # Generate message files
+    django-admin makemessages -l es
+    django-admin makemessages -l fr
+    django-admin makemessages -l zh_Hant
+
+Edit the generated ``.po`` files to add translations:
+
+.. code-block:: po
+
+    # locale/es/LC_MESSAGES/django.po
+    msgid "Welcome to {app}! Please use security code {security_code} to proceed."
+    msgstr "¡Bienvenido a {app}! Por favor usa el código de seguridad {security_code} para continuar."
+
+    # locale/fr/LC_MESSAGES/django.po
+    msgid "Welcome to {app}! Please use security code {security_code} to proceed."
+    msgstr "Bienvenue sur {app}! Veuillez utiliser le code de sécurité {security_code} pour continuer."
+
+    # locale/zh_Hant/LC_MESSAGES/django.po
+    msgid "Welcome to {app}! Please use security code {security_code} to proceed."
+    msgstr "歡迎使用 {app}! 請使用安全碼 {security_code} 繼續。"
+
+Compile the translations:
+
+.. code-block:: bash
+
+    django-admin compilemessages
+
+Usage
+^^^^^
+
+The library automatically reads the ``Accept-Language`` header from HTTP requests and sends
+the verification message in the user's preferred language:
+
+.. code-block:: javascript
+
+    // Frontend: Set Accept-Language header
+    fetch('/api/phone/register/', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Accept-Language': 'es'  // Spanish
+        },
+        body: JSON.stringify({
+            phone_number: '+1234567890'
+        })
+    });
+
+The SMS sent to the user will automatically be in Spanish if you've provided a translation.
+
+Programmatic Usage
+^^^^^^^^^^^^^^^^^^
+
+You can also specify the language programmatically when using the service directly:
+
+.. code-block:: python
+
+    from phone_verify.services import send_security_code_and_generate_session_token
+
+    # Send verification in French
+    session_token = send_security_code_and_generate_session_token(
+        phone_number="+1234567890",
+        language="fr"
+    )
+
+    # Or using the service class directly
+    from phone_verify.services import PhoneVerificationService
+
+    service = PhoneVerificationService(
+        phone_number="+1234567890",
+        language="zh-hant"  # Traditional Chinese
+    )
+
+    backend = service.backend
+    security_code, session_token = backend.create_security_code_and_session_token(
+        phone_number="+1234567890"
+    )
+
+    service.send_verification("+1234567890", security_code)
+
+Language Code Format
+^^^^^^^^^^^^^^^^^^^^
+
+The library accepts standard language codes:
+
+- Simple codes: ``en``, ``es``, ``fr``, ``de``, ``ja``, ``zh``
+- Locale-specific: ``en-US``, ``en-GB``, ``zh-Hans`` (Simplified Chinese), ``zh-Hant`` (Traditional Chinese)
+- The first language in comma-separated ``Accept-Language`` headers is used
+- Quality values (``q=``) are ignored; only the first language is considered
+
+Fallback Behavior
+^^^^^^^^^^^^^^^^^
+
+If a translation is not available for the requested language, the library falls back to
+the default message defined in ``PHONE_VERIFICATION['MESSAGE']``.
+
 Phone Number Update Flow
 -------------------------
 

phone_verify/api.py

@@ -20,8 +20,18 @@ class VerificationViewSet(viewsets.GenericViewSet):
     def register(self, request):
         serializer = PhoneSerializer(data=request.data)
         serializer.is_valid(raise_exception=True)
+
+        # Extract language from Accept-Language header
+        # Format: "en-US,en;q=0.9,es;q=0.8" -> take first language "en-US"
+        accept_language = request.META.get('HTTP_ACCEPT_LANGUAGE', '')
+        language = None
+        if accept_language:
+            # Take first language, strip quality params (e.g., "en-US;q=0.9" -> "en-US")
+            language = accept_language.split(',')[0].split(';')[0].strip() or None
+
         session_token = send_security_code_and_generate_session_token(
-            str(serializer.validated_data["phone_number"])
+            str(serializer.validated_data["phone_number"]),
+            language=language
         )
         return response.Ok({"session_token": session_token})
 

phone_verify/services.py

@@ -6,6 +6,7 @@
 # Third Party Stuff
 from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
+from django.utils.translation import gettext, override
 
 # phone_verify stuff
 from .backends import get_sms_backend
@@ -21,7 +22,7 @@
 
 class PhoneVerificationService(object):
 
-    def __init__(self, phone_number, backend=None):
+    def __init__(self, phone_number, backend=None, language=None):
         try:
             self.phone_settings = settings.PHONE_VERIFICATION
         except AttributeError as e:
@@ -33,6 +34,7 @@ def __init__(self, phone_number, backend=None):
             self.backend = backend
 
         self.verification_message = self.phone_settings.get("MESSAGE", DEFAULT_MESSAGE)
+        self.language = language
 
     def send_verification(self, number, security_code, context=None):
         """
@@ -60,7 +62,13 @@ def _generate_message(self, security_code, context=None):
         if context:
             format_context.update(context)
 
-        return self.verification_message.format(**format_context)
+        # Apply i18n if language is specified
+        verification_message = self.verification_message
+        if self.language:
+            with override(self.language):
+                verification_message = gettext(self.verification_message)
+
+        return verification_message.format(**format_context)
 
     def _check_required_settings(self):
         required_settings = {
@@ -81,12 +89,12 @@ def _check_required_settings(self):
             )
 
 
-def send_security_code_and_generate_session_token(phone_number):
+def send_security_code_and_generate_session_token(phone_number, language=None):
     sms_backend = get_sms_backend(phone_number)
     security_code, session_token = sms_backend.create_security_code_and_session_token(
         phone_number
     )
-    service = PhoneVerificationService(phone_number=phone_number)
+    service = PhoneVerificationService(phone_number=phone_number, language=language)
     try:
         service.send_verification(phone_number, security_code)
     except service.backend.exception_class as exc:

tests/test_api.py

@@ -202,3 +202,32 @@ def test_verified_security_code(client, backend):
         response_data = json.loads(json.dumps(response.data))
         assert response.status_code == 200
         assert response.data["message"] == "Security code is valid."
+
+
+def test_phone_registration_with_accept_language_header(client, mocker, backend):
+    with override_settings(PHONE_VERIFICATION=backend):
+        zh_verification_message = "歡迎使用 {app}! 請使用安全碼 {security_code} 繼續。"
+        mocker.patch('phone_verify.services.gettext', return_value=zh_verification_message)
+
+        backend_service = backend.get("BACKEND")
+        mock_backend_send_sms = mocker.patch(f"{backend_service}.send_sms")
+
+        url = reverse("phone-register")
+        phone_number = PHONE_NUMBER
+        data = {"phone_number": phone_number}
+
+        # Send request with Accept-Language header
+        response = client.post(url, data, HTTP_ACCEPT_LANGUAGE="zh-hant")
+
+        assert response.status_code == 200
+        assert "session_token" in response.data
+        SMSVerification = apps.get_model("phone_verify", "SMSVerification")
+        sms_verification = SMSVerification.objects.get(
+            session_token=response.data["session_token"], phone_number=phone_number
+        )
+        assert sms_verification
+        actual_message = zh_verification_message.format(
+            app=backend['APP_NAME'],
+            security_code=sms_verification.security_code
+        )
+        mock_backend_send_sms.assert_called_with("+13478379634", actual_message)

tests/test_services.py

@@ -131,3 +131,18 @@ def test_generate_message_from_custom_backend(settings):
     msg = svc._generate_message("999999", context={"extra": "runtime"})
 
     assert msg == "Custom: 999999 / runtime"
+
+
+@pytest.mark.django_db
+def test_i18n_message_generation_and_sending_service(client, mocker, backend):
+    with override_settings(PHONE_VERIFICATION=backend):
+        zh_verification_message = "歡迎使用 {app}! 請使用安全碼 {security_code} 繼續。"
+        mocker.patch('phone_verify.services.gettext', return_value=zh_verification_message)
+        service = PhoneVerificationService(phone_number="+13478379634", language='zh-hant')
+        backend_service = backend.get("BACKEND")
+        mock_api = mocker.patch(f"{backend_service}.send_sms")
+        service.send_verification("+13478379634", "123456")
+        actual_message = zh_verification_message.format(
+            app=backend['APP_NAME'], security_code="123456"
+        )
+        mock_api.assert_called_with("+13478379634", actual_message)