Inline translation string editing for Django
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Project description
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.
Project details
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file django_cartouche-0.3.1.tar.gz.
File metadata
- Download URL: django_cartouche-0.3.1.tar.gz
- Upload date:
- Size: 80.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
37ed972e844063439879cf9654174143ca5d9e813e9cc46f7f61cd8f7a31dc17
|
|
| MD5 |
d56fd2aaa1756ba6f841c8c8eba1cba5
|
|
| BLAKE2b-256 |
031faf389dee54b0de42e20692a114126292efe9ce747889d68ac62106129624
|
Provenance
The following attestation bundles were made for django_cartouche-0.3.1.tar.gz:
Publisher:
release.yml on rnegron/django-cartouche
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
django_cartouche-0.3.1.tar.gz -
Subject digest:
37ed972e844063439879cf9654174143ca5d9e813e9cc46f7f61cd8f7a31dc17 - Sigstore transparency entry: 813257393
- Sigstore integration time:
-
Permalink:
rnegron/django-cartouche@28fc17d03f864477f3b77477989f77bf2403db2f -
Branch / Tag:
refs/tags/v0.3.1 - Owner: https://github.com/rnegron
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@28fc17d03f864477f3b77477989f77bf2403db2f -
Trigger Event:
push
-
Statement type:
File details
Details for the file django_cartouche-0.3.1-py3-none-any.whl.
File metadata
- Download URL: django_cartouche-0.3.1-py3-none-any.whl
- Upload date:
- Size: 11.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f882a7e58b827804b23502f63d86dec94ca5cbc1e27d4d7257d9e3f9e96ab46e
|
|
| MD5 |
37485a0614ace39dee73a01a594c4578
|
|
| BLAKE2b-256 |
71762104048a75618c59771b1c5a8795b99f9995cb0e1e03b40a39108780cf66
|
Provenance
The following attestation bundles were made for django_cartouche-0.3.1-py3-none-any.whl:
Publisher:
release.yml on rnegron/django-cartouche
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
django_cartouche-0.3.1-py3-none-any.whl -
Subject digest:
f882a7e58b827804b23502f63d86dec94ca5cbc1e27d4d7257d9e3f9e96ab46e - Sigstore transparency entry: 813257395
- Sigstore integration time:
-
Permalink:
rnegron/django-cartouche@28fc17d03f864477f3b77477989f77bf2403db2f -
Branch / Tag:
refs/tags/v0.3.1 - Owner: https://github.com/rnegron
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@28fc17d03f864477f3b77477989f77bf2403db2f -
Trigger Event:
push
-
Statement type:
