wagtail-localize-intentional-blanks

A Wagtail library that extends wagtail-localize to allow translators to mark translation segments as "do not translate". These segments count as translated (contributing to progress) but fall back to the source page's value when rendered.

Features

• ✅ Translator Control: Translators decide which fields to not translate, not developers
• ✅ Per-Locale Flexibility: German can use source while French translates
• ✅ Progress Tracking: "Do not translate" segments count as translated
• ✅ No Template Changes: Works transparently with existing templates
• ✅ Drop-in Integration: Minimal code changes required
• ✅ UI Included: Adds "Do Not Translate" buttons to translation editor

Installation

pip install wagtail-localize-intentional-blanks

Quick Start

1. Add to INSTALLED_APPS

Important: wagtail_localize_intentional_blanks must come before wagtail_localize in INSTALLED_APPS for template overrides to work.

# settings.py

INSTALLED_APPS = [
    # ... other apps
    'wagtail_localize_intentional_blanks',  # Must be BEFORE wagtail_localize
    'wagtail_localize',
    'wagtail_localize.locales',
    # ... other apps
]

2. Include URLs

# urls.py

from django.urls import path, include

urlpatterns = [
    # ... other patterns
    path(
        'intentional-blanks/',
        include('wagtail_localize_intentional_blanks.urls')
    ),
]

3. Run Migrations (if any)

python manage.py migrate

That's it! The "Do Not Translate" button will now appear in the translation editor for all translatable fields. No code changes to your blocks or models required.

How It Works

This library works by:

1. Adding UI controls - JavaScript adds "Do Not Translate" checkboxes to the translation editor
2. Storing markers - When checked, a marker string (__DO_NOT_TRANSLATE__) is stored in the translation
3. Automatic replacement - When rendering pages, a monkey-patch intercepts segment retrieval and replaces markers with source values
4. Progress tracking - Marked segments count as "translated" for progress calculation

Key benefit: No code changes to your blocks or models. The library handles everything automatically through monkey-patching wagtail-localize's internal methods.

Usage

In the Translation Editor

1. Open a page translation in wagtail-localize's editor
2. For each segment, you'll see a "Mark 'Do Not Translate'" checkbox
3. Check it to mark that segment as do not translate
4. The segment counts as translated (shows green, contributes to progress)
5. When the page renders, it automatically shows the source value for that field

Common Use Cases

• Brand names and trademarks - Keep consistent across locales
• Product codes and SKUs - No translation needed
• URLs - Pages may contain the translations for different languages, but a URL is the same for all languages
• IDs - Not language-specific identifiers

Configuration

You can customize behavior in your Django settings:

# settings.py

# Disable the feature globally
WAGTAIL_LOCALIZE_INTENTIONAL_BLANKS_ENABLED = True

# Custom marker (advanced)
WAGTAIL_LOCALIZE_INTENTIONAL_BLANKS_MARKER = "__DO_NOT_TRANSLATE__"

# Require specific permission (default: None = any translator)
WAGTAIL_LOCALIZE_INTENTIONAL_BLANKS_REQUIRED_PERMISSION = 'cms.can_mark_do_not_translate'

Advanced Usage

Programmatic API

You can programmatically mark segments as "do not translate" using the provided utilities:

from wagtail_localize_intentional_blanks.utils import (
    mark_segment_do_not_translate,
    unmark_segment_do_not_translate,
    get_source_fallback_stats,
)
from wagtail_localize.models import Translation, StringSegment

# Mark a segment
translation = Translation.objects.get(id=123)
segment = StringSegment.objects.get(id=456)
mark_segment_do_not_translate(translation, segment, user=request.user)

# Unmark a segment
unmark_segment_do_not_translate(translation, segment)

# Get statistics
stats = get_source_fallback_stats(translation)
print(f"{stats['do_not_translate']} segments marked as do not translate")
print(f"{stats['manually_translated']} segments manually translated")

Requirements

• Python 3.10+
• Django 4.2+
• Wagtail 5.2+
• wagtail-localize 1.8+

License

MIT License - see LICENSE file for details.

Development

Setting Up for Development

1. Clone the repository:

git clone https://github.com/lincolnloop/wagtail-localize-intentional-blanks.git
cd wagtail-localize-intentional-blanks

2. Install the package with development dependencies:

pip install -e ".[dev]"

This installs the package in editable mode along with testing tools (pytest, black, flake8, etc.).

Running Tests

Run the test suite with pytest:

pytest

Run tests with coverage:

pytest --cov=wagtail_localize_intentional_blanks

Run specific test files:

pytest tests/test_utils.py
pytest tests/test_views.py

Code Quality

Format code with black:

black .

Sort imports with isort:

isort .

Check code style with flake8:

flake8 wagtail_localize_intentional_blanks tests

Type checking with mypy:

mypy wagtail_localize_intentional_blanks

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Credits

Created by Lincoln Loop, LLC for the Wagtail community.