Django Rosetta

Common errors

• django.core.exceptions.ImproperlyConfigured: 'rosetta' is not in your INSTALLED_APPS setting.

  cause The 'rosetta' app has not been added to the INSTALLED_APPS list in your Django project's settings.py file.
  fix Add `'rosetta'` to the `INSTALLED_APPS` list in `settings.py`: ```python INSTALLED_APPS = [ # ... other apps 'rosetta', ] ```

• NoReverseMatch at /rosetta/ 'rosetta' is not a registered namespace

  cause The `rosetta.urls` have not been included in your project's main `urls.py` file or are incorrectly included.
  fix Add `path('rosetta/', include('rosetta.urls'))` to your project's `urlpatterns` in `urls.py`: ```python from django.urls import include, path urlpatterns = [ # ... other url patterns path('rosetta/', include('rosetta.urls')), ] ```

• Translated strings do not appear on the website after editing in Rosetta.

  cause After editing `.po` files in Rosetta, the corresponding `.mo` (machine object) files, which Django uses for translations, have not been recompiled or the web server hasn't been restarted. This can also happen if `LOCALE_PATHS` is incorrect or `makemessages` wasn't run for the relevant strings.
  fix Run `python manage.py compilemessages` from your project root. If `ROSETTA_WSGI_AUTO_RELOAD` is enabled and your web server supports it, changes might apply immediately, but a server restart is often needed. Ensure `LOCALE_PATHS` is correctly configured in `settings.py`.

• Uncaught ReferenceError: jQuery is not defined in rosetta interface.

  cause Your custom JavaScript or an older version of your frontend assets in the Rosetta interface is still trying to use jQuery, but django-rosetta versions 0.10.2 and later have removed jQuery from its core.
  fix Update any custom JavaScript that runs within the Rosetta interface to remove its dependency on jQuery or ensure a compatible jQuery version is explicitly loaded if absolutely necessary.

Warnings

• breaking As of version 0.10.2, django-rosetta has rewritten its `rosetta.js` to drop jQuery, modernizing its frontend. If your custom frontend JavaScript heavily relied on jQuery in the Rosetta interface, it might break.
  Fix: Review and update any custom JavaScript that interacts with Rosetta's frontend to remove jQuery dependencies or adapt to the new vanilla JS implementation.
• breaking Django and Python version compatibility has been frequently updated. Version 0.10.0 and later require Django 4.2+ and Python 3.9+. Older versions (0.9.9) required Django 3.2+ and Python 3.8+. Ensure your environment meets the minimum requirements for your installed rosetta version.
  Fix: Check the official documentation or PyPI for the exact Django/Python version requirements for your django-rosetta version and upgrade your Django/Python environment if necessary.
• gotcha When running django-rosetta in a multi-process environment (e.g., Gunicorn, mod_wsgi) with Django's default `LocMemCache` as the cache backend, you may encounter issues with translation data not persisting between requests.
  Fix: Configure a persistent cache backend (e.g., Memcached, Redis) in your Django settings and ensure `ROSETTA_STORAGE_CLASS` is set to `'rosetta.storage.CacheRosettaStorage'`. Avoid using `signed_cookies` with `SessionRosettaStorage` for large PO files.
• gotcha Version 0.10.1 improved Content Security Policy (CSP) support by avoiding inline styles and server-side rendered stylesheets. If your project has a very strict CSP, you might need to adjust your CSP directives to allow Rosetta's assets, especially if you had custom overrides.
  Fix: Review your `Content-Security-Policy` headers and potentially add `nonce` attributes or specific `'self'` sources for styles and scripts if you encounter CSP violations after upgrading.
• gotcha Using translation suggestion APIs (DeepL, OpenAI, etc.) requires configuring API keys in your Django settings. These keys should be securely managed, ideally via environment variables, to avoid exposure.
  Fix: Set `DEEPL_AUTH_KEY`, `OPENAI_API_KEY`, or other relevant API keys in your `settings.py` (e.g., using `os.environ.get`) and ensure `ROSETTA_ENABLE_TRANSLATION_SUGGESTIONS` is `True`.

Install

• pip install django-rosetta Install with pip

Imports

• 'rosetta'

  # settings.py
  INSTALLED_APPS = [
      # ...
      'rosetta',
  ]

  Add 'rosetta' to your INSTALLED_APPS list to enable the application.
• include('rosetta.urls')
  wrong:

  from django.conf.urls import patterns, url, include
  urlpatterns = patterns('',
      url(r'^rosetta/', include('rosetta.urls')),
  )

  correct:

  # urls.py
  from django.urls import include, path
  
  urlpatterns = [
      # ...
      path('rosetta/', include('rosetta.urls')),
  ]

  Modern Django uses `path` or `re_path` from `django.urls`. The `patterns` function was deprecated and removed in Django 2.0.

Quickstart

To quickly set up django-rosetta, first install it via pip. Then, add `'rosetta'` to your `INSTALLED_APPS` in `settings.py` and include `rosetta.urls` in your project's `urls.py`. Ensure your Django project is already configured for internationalization (i18n) by defining `LANGUAGES` and `LOCALE_PATHS`, and running `python manage.py makemessages` and `python manage.py compilemessages` to create and compile translation files.

import os

# settings.py
INSTALLED_APPS = [
    # ... default Django apps
    'rosetta',
    'django.contrib.admin', # Rosetta often accessed via admin
]

# Example for translation suggestions
ROSETTA_ENABLE_TRANSLATION_SUGGESTIONS = True

# Configure DeepL or OpenAI if desired
# DEEPL_AUTH_KEY = os.environ.get('DEEPL_AUTH_KEY', '')
# OPENAI_API_KEY = os.environ.get('OPENAI_API_KEY', '')
# OPENAI_BASE_URL = os.environ.get('OPENAI_BASE_URL', '') # for self-hosted LLM

# urls.py (in your project's main urls.py)
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path('admin/', admin.site.urls),
    path('rosetta/', include('rosetta.urls')),
]

# After configuration and running makemessages:
# python manage.py makemessages -l es
# python manage.py compilemessages
# Then, navigate to /rosetta/ in your browser.