Inline translation string editing for Django

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for rauln from gravatar.com rauln

Unverified details

These details have not been verified by PyPI
Project links
Meta
Classifiers
Report project as malware

Project description

django-cartouche

PyPI - Version Published on Django Packages CI docs codecov

Django Cartouche enables inline (in-HTML) .po translation editing for Django projects. Click on any string marked for translation in your browser to edit it directly during development.

Installation

Install as a development dependency:

pip install django-cartouche --group dev
# or with uv
uv add django-cartouche --dev

Configuration

django-cartouche should only be installed in development environments. Configure it in your local/development settings file (e.g., settings/local.py or settings/dev.py):

# settings/local.py

from .base import *

DEBUG = True

INSTALLED_APPS += [
    "cartouche",
]

MIDDLEWARE += [
    "cartouche.middleware.CartoucheMiddleware",  # Must be after LocaleMiddleware
]

Conditionally include URLs in your urls.py:

from django.conf import settings

urlpatterns = [
    # ...
]

if settings.DEBUG:
    urlpatterns += [
        path("cartouche/", include("cartouche.urls")),
    ]

Set the lang attribute on your <html> element for locale detection:

{% load i18n %}
<!DOCTYPE html>
<html lang="{{ LANGUAGE_CODE }}">

The editor only activates when DEBUG=True, but following these practices ensures cartouche is never present in production.

How It Works

When a page renders, django-cartouche tracks all translation calls (gettext, pgettext) and injects a manifest of translated strings into the HTML response. The frontend script then walks the DOM, finds matching text, and wraps it in editable spans.

When you edit a string and save (blur or press Enter):

  1. The original source string (msgid) is used to locate the entry in your .po file
  2. The lang attribute on <html> determines which locale's .po file to update
  3. The .po file is saved and compilemessages runs automatically

For example, if your source is English and you're viewing the site in Spanish (<html lang="es">):

  • {% trans "Welcome" %} displays "Bienvenido" (from locale/es/LC_MESSAGES/django.po)
  • Clicking on "Bienvenido" lets you edit the Spanish translation
  • Saving updates msgstr in the Spanish .po file

To edit translations for a different language, switch your site's active locale first. Each language has its own .po file, and the lang attribute tells cartouche which one to modify.

Demo

The project ships with a simple demo project so you can see it in action locally:

cd demo && python manage.py runserver

Notice how changing the strings in-browser modifies your .po files and re-compiles them into .mo files.

Development

uv sync                              # Install dependencies
uv run pre-commit install            # Install git hooks (one-time)
ruff check src/ && ruff format src/  # Lint and format
pytest --cov                         # Run tests with coverage

Making Commits

Use the interactive CLI for guided conventional commits:

uv run cz commit

Or use standard git with conventional format:

git commit -m "feat: add new feature"
git commit -m "fix(compiler): handle edge case"

Feedback

If you end up using django-cartouche, I'd genuinely like to hear about your experience. Whether you've found it helpful, run into issues or have ideas for improvements, your feedback is welcome.

Share your feedback here →

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for rauln from gravatar.com rauln

Unverified details

These details have not been verified by PyPI
Project links
Meta
Classifiers

Release history Release notifications | RSS feed

0.3.2

0.3.1

This version

0.3.0

0.2.1

0.2.0

0.1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_cartouche-0.3.0.tar.gz (80.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

django_cartouche-0.3.0-py3-none-any.whl (11.0 kB view details)

Uploaded Python 3

File details

Details for the file django_cartouche-0.3.0.tar.gz.

File metadata

  • Download URL: django_cartouche-0.3.0.tar.gz
  • Upload date:
  • Size: 80.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for django_cartouche-0.3.0.tar.gz
Algorithm Hash digest
SHA256 8b1ad99702a2e8476eac90cee38964c33cabd597c918c909842e9b375f736d73
MD5 a92b0eeb41e9eca2c63dab6bb02cd5b0
BLAKE2b-256 a3a61f02fd1c011de3a57071b0399efbd4eccd732b75ae97771a75387b2a1add

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_cartouche-0.3.0.tar.gz:

Publisher: release.yml on rnegron/django-cartouche

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file django_cartouche-0.3.0-py3-none-any.whl.

File metadata

File hashes

Hashes for django_cartouche-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 fc533d450520b0bb3af7d78d5d9872a50090ba9ff57c560b1f8501ec663e5328
MD5 739a6dcdf7ef5c2bb9c03cfc03251cbd
BLAKE2b-256 67d552896208707edc908eb31737d76868dfb2b6161c9a0df180dcd087560f64

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_cartouche-0.3.0-py3-none-any.whl:

Publisher: release.yml on rnegron/django-cartouche

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page