django-cartouche
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.
Clickable Elements: When translated text appears inside links or buttons, clicking shows an "Edit | Open" menu. Choose "Edit" to modify the translation or "Open" to navigate normally. Regular text outside clickable elements can be edited with a direct click.
When you edit a string and save (blur or press Enter):
- The original source string (
msgid) is used to locate the entry in your.pofile - The
langattribute on<html>determines which locale's.pofile to update - The
.pofile is saved andcompilemessagesruns automatically
For example, if your source is English and you're viewing the site in Spanish (<html lang="es">):
{% trans "Welcome" %}displays "Bienvenido" (fromlocale/es/LC_MESSAGES/django.po)- Clicking on "Bienvenido" lets you edit the Spanish translation
- Saving updates
msgstrin the Spanish.pofile
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.
1 maintainer
Release files for django-cartouche 0.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| django_cartouche-0.3.2.tar.gz | 81.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| django_cartouche-0.3.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 92.8 kB
Release files / django_cartouche-0.3.2.tar.gz
| Download URL | django_cartouche-0.3.2.tar.gz |
|---|---|
| Size | 81.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
511af8abcc980000ebd35c7b1c49cd6999b63dc11194bc970573fb7886a37c35
|
|
BLAKE2b-256 checksum How to use checksums |
87a8500af2f6ba6f4356993d38ceed635bb3a447aab5571653a48242081ac350
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 10, 2026.
Transparency logRelease files / django_cartouche-0.3.2-py3-none-any.whl
| Download URL | django_cartouche-0.3.2-py3-none-any.whl |
|---|---|
| Size | 11.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
87829832acbd89b5288c46a06a46a4d16199aa9e605937fd6fc07981d4659f6d
|
|
BLAKE2b-256 checksum How to use checksums |
8ae26931ac62adc92aa14da023481efd052499e86c886ebe70af9a427901c1f0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 10, 2026.
Transparency log
