wagtail-localize-dashboard 0.3.0

Translation dashboard for wagtail-localize with caching

wagtail-localize-dashboard

A translation dashboard for Wagtail sites using wagtail-localize.

Features

• Translation Dashboard: Visual overview of translation progress for all pages
• Auto-Updates: Signals automatically update percentages when translations change
• Performance: Translation percentages are stored in the database, for fast loading
• Filtering: Search by title, filter by language, translation key, or language group
• Color-Coded Status: Green (100%), Yellow (80-99%), Red (<80%)
• Admin Integration: Adds menu item to Wagtail admin
• Configurable: Enable/disable features via Django settings

Installation

pip install wagtail-localize-dashboard

Quick Start

1. Add to INSTALLED_APPS

# settings.py

INSTALLED_APPS = [
    # ... other apps
    "wagtail_localize",
    "wagtail_localize_dashboard",  # Add after wagtail-localize
    # ... other apps
]

2. Include URLs

# urls.py

from django.urls import path, include

urlpatterns = [
    # ... other patterns
    path("translations/", include("wagtail_localize_dashboard.urls")),
    # ... other patterns
]

3. Run Migrations

python manage.py migrate wagtail_localize_dashboard

4. Calculate Percentages

python manage.py rebuild_translation_progress

5. Access Dashboard

Navigate to /translations/ in your Wagtail admin, or click "Translations" in the admin menu.

Configuration

Customize behavior in your Django settings:

# settings.py
from django.utils.translation import gettext_lazy as _

# Enable/disable the entire feature (default: True)
WAGTAIL_LOCALIZE_DASHBOARD_ENABLED = True

# Enable automatic TranslationProgress updates via signals (default: True)
WAGTAIL_LOCALIZE_DASHBOARD_AUTO_UPDATE = True

# Track translation progress for Pages (default: True)
WAGTAIL_LOCALIZE_DASHBOARD_TRACK_PAGES = True

# Show dashboard in Wagtail admin menu (default: True)
WAGTAIL_LOCALIZE_DASHBOARD_SHOW_IN_MENU = True

# Menu item configuration (default label is translated via i18n;
# use gettext_lazy to keep it translatable when overriding)
WAGTAIL_LOCALIZE_DASHBOARD_MENU_LABEL = _("Translations")
WAGTAIL_LOCALIZE_DASHBOARD_MENU_ICON = "wagtail-localize-language"
WAGTAIL_LOCALIZE_DASHBOARD_MENU_ORDER = 800

# Items per page in dashboard (default: 50)
WAGTAIL_LOCALIZE_DASHBOARD_ITEMS_PER_PAGE = 50

# Column filter: group locales into named sets so users can filter
# which language columns are visible on the dashboard (default: [])
# Each tuple is (id, label, list_of_locale_codes).
WAGTAIL_LOCALIZE_DASHBOARD_COLUMN_FILTER_OPTIONS = [
    ("spanish", "Spanish", ["es-es", "es-ar", "es-mx", "es-cl"]),
    ("french", "French", ["fr-fr", "fr-ca", "fr-be"]),
]

When WAGTAIL_LOCALIZE_DASHBOARD_COLUMN_FILTER_OPTIONS is configured, a "Show languages" dropdown appears on the dashboard. Selecting a group limits the displayed language columns to the locales in that group. Rows are not hidden — pages with no translations in the selected group will still appear.

Usage

Dashboard

The dashboard shows:

• All original pages (not translations)
• Translation progress for each locale (0-100%)
• Color-coded status badges
• Quick links to edit pages

Management Commands

# Recalculate translation percentages for all pages
python manage.py rebuild_translation_progress

# Clean orphaned records and rebuild
python manage.py rebuild_translation_progress --clean-orphans

Programmatic API

from wagtail_localize_dashboard.utils import (
    get_translation_percentages,
    create_translation_progress,
    rebuild_all_progress,
)

# Get translation percentage for a specific locale
from wagtail.models import Locale
page = Page.objects.get(id=123)
locale_de = Locale.objects.get(language_code="de")
percent = get_translation_percentages(page, locale_de)

# Update progress for a page
create_translation_progress(page)

# Rebuild all progress
stats = rebuild_all_progress()
print(f"Processed {stats['pages']} pages")

Internationalization (i18n)

All user-facing strings in the dashboard are translatable using Django's standard i18n framework. The package ships with English, Spanish, and Russian translations.

Adding a new translation

1. Generate the .po file for your locale (e.g. fr for French):

cd wagtail_localize_dashboard
django-admin makemessages -l fr --no-wrap

2. Edit locale/fr/LC_MESSAGES/django.po and fill in the msgstr values.

3. Compile the translations:

django-admin compilemessages -l fr

4. Restart the dev server to pick up the new translations.

Updating translations after code changes

If you add or change translatable strings, re-run makemessages for each locale:

cd wagtail_localize_dashboard
django-admin makemessages --all --no-wrap
django-admin compilemessages

How It Works

1. Database Table: The TranslationProgress model stores pre-calculated percentages
2. Signals: Listen for translation changes and update TranslationProgress table automatically
3. Dashboard: Displays TranslationProgress data for each page
4. Management Command: Rebuilds TranslationProgress objects when needed

Requirements

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

Contributing

Contributions are welcome!

Development

Setting Up for Development

1. Clone the repository:

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

2. Install the package with development dependencies:

pip install -e ".[dev]"

This installs the package in editable mode along with testing tools.

Running Tests

Run the test suite with pytest:

pytest

Run tests with coverage:

pytest --cov=wagtail_localize_dashboard

Run specific test files:

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

Run accessibility tests (requires pip install -e ".[test,accessibility]"):

pytest -m accessibility

Code Quality

Check code with ruff:

ruff check .

Format with ruff:

ruff format .

Release

In order to make a release, we add a git tag and push it to GitHub. We have a GitHub Action that releases the code to PyPI when we add a new tag.

License

MIT License - see LICENSE file for details.

Credits

Created by Lincoln Loop for the Wagtail community.

Inspired by the translation dashboard in the Springfield CMS.