Metadata-Version: 2.4
Name: django-cartouche
Version: 0.1.0
Summary: Inline translation string editing for Django
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: django>=4.2
Requires-Dist: polib>=1.2
Description-Content-Type: text/markdown

# django-cartouche

[![CI](https://github.com/rnegron/django-cartouche/actions/workflows/ci.yml/badge.svg)](https://github.com/rnegron/django-cartouche/actions/workflows/ci.yml)

[![codecov](https://codecov.io/github/rnegron/django-cartouche/graph/badge.svg?token=EMRGIAU3UZ)](https://codecov.io/github/rnegron/django-cartouche)

Inline .po translation editing for Django. Click on any translated string in the browser to edit it directly during development.

## Installation

Install as a development dependency:

```bash
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`):

```python
# 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`:

```python
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:

```html
<html lang="{{ LANGUAGE_CODE }}">
```

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

## Development

```bash
uv sync                              # Install dependencies
uv run pre-commit install            # Install git hooks (one-time)
cd demo && python manage.py runserver  # Run demo server
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:

```bash
uv run cz commit
```

Or use standard git with conventional format:

```bash
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 →](https://github.com/rnegron/django-cartouche/issues/new?template=feedback.md)**
