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

0.3.0

This version

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.2.1.tar.gz (79.0 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.2.1-py3-none-any.whl (10.2 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: django_cartouche-0.2.1.tar.gz
  • Upload date:
  • Size: 79.0 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.2.1.tar.gz
Algorithm Hash digest
SHA256 b427127cb08ae871bcc0ad3a2a1d5036fcdbf65d2f6d71948fa13d2534269e1a
MD5 4520fdea3345cb00e937de307f99c850
BLAKE2b-256 343559b39c6d0e5e50fb900d119e1901b31e21526341f6d0d817ae17015310dd

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_cartouche-0.2.1.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.2.1-py3-none-any.whl.

File metadata

File hashes

Hashes for django_cartouche-0.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 bc3c51312d37c559b1ca2b74edd2d59a959bd93b46cb11c2950a33531e465cd3
MD5 142e694de16dad7befcbe2e0e6336c29
BLAKE2b-256 b005719748a73a8ac2bb4899e8b4ad3c3ebf9c5fbf01d15ccdaa03779b74b75a

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_cartouche-0.2.1-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