wagtail-localize-intentional-blanks 0.1.0__py3-none-any.whl

wagtail_localize_intentional_blanks/__init__.py

@@ -0,0 +1,29 @@
+"""
+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 not needing
+to be translated, and fall back to the source page's value when rendered.
+
+:copyright: (c) 2025 by Lincoln Loop, LLC
+:license: MIT, see LICENSE for more details.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Lincoln Loop, LLC"
+__license__ = "MIT"
+
+# Public API
+from .constants import DO_NOT_TRANSLATE_MARKER
+
+# Utility functions can be imported from their modules if needed:
+#   from wagtail_localize_intentional_blanks.utils import mark_segment_do_not_translate
+
+__all__ = [
+    "DO_NOT_TRANSLATE_MARKER",
+]
+
+
+# Default Django app config
+default_app_config = "wagtail_localize_intentional_blanks.apps.IntentionalBlanksConfig"

wagtail_localize_intentional_blanks/apps.py

@@ -0,0 +1,29 @@
+from django.apps import AppConfig
+
+
+class IntentionalBlanksConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "wagtail_localize_intentional_blanks"
+    verbose_name = "Wagtail Localize Intentional Blanks"
+
+    def ready(self):
+        """
+        Run when Django starts.
+
+        Register signal handlers, check dependencies, etc.
+        """
+        # Check that wagtail-localize is installed
+        try:
+            import wagtail_localize  # noqa: F401
+        except ImportError:
+            raise ImportError(
+                "wagtail-localize must be installed to use wagtail-localize-intentional-blanks. Install it with: pip install wagtail-localize"
+            )
+
+        # Apply monkey-patch to wagtail-localize
+        from .patch import apply_patch
+
+        apply_patch()
+
+        # Import wagtail hooks
+        from . import wagtail_hooks  # noqa

wagtail_localize_intentional_blanks/constants.py

@@ -0,0 +1,44 @@
+"""
+Constants used throughout the library.
+"""
+
+# The marker value stored in StringTranslation.data to indicate "do not translate"
+DO_NOT_TRANSLATE_MARKER = "__DO_NOT_TRANSLATE__"
+
+# The separator used when encoding backup values in the marker
+# Format: MARKER + BACKUP_SEPARATOR + original_value
+# Example: "__DO_NOT_TRANSLATE__|backup|original_value"
+BACKUP_SEPARATOR = "|backup|"
+
+# Settings keys (can be overridden in Django settings)
+SETTINGS_PREFIX = "WAGTAIL_LOCALIZE_INTENTIONAL_BLANKS"
+
+# Default configuration
+DEFAULTS = {
+    # Whether to enable the feature globally
+    "ENABLED": True,
+    # Custom marker (if you want to use a different value)
+    "MARKER": DO_NOT_TRANSLATE_MARKER,
+    # Custom backup separator (if you want to use a different value)
+    "BACKUP_SEPARATOR": BACKUP_SEPARATOR,
+    # Permission required to mark segments as "do not translate"
+    # None = any translator, or specify a permission string
+    "REQUIRED_PERMISSION": None,
+}
+
+
+def get_setting(key, default=None):
+    """
+    Get a setting value from Django settings.
+
+    Args:
+        key: Setting key (without prefix)
+        default: Default value if not found
+
+    Returns:
+        The setting value
+    """
+    from django.conf import settings
+
+    full_key = f"{SETTINGS_PREFIX}_{key}"
+    return getattr(settings, full_key, DEFAULTS.get(key, default))

wagtail_localize_intentional_blanks/patch.py

@@ -0,0 +1,182 @@
+"""
+Monkey-patch for wagtail-localize to support intentional blanks.
+
+This patches TranslationSource._get_segments_for_translation() to check for
+the __DO_NOT_TRANSLATE__ marker and use source values instead of translations
+when the marker is present.
+"""
+
+import json
+import logging
+
+from wagtail_localize.models import TranslationSource
+from wagtail_localize.segments import (
+    OverridableSegmentValue,
+    RelatedObjectSegmentValue,
+    StringSegmentValue,
+    TemplateSegmentValue,
+)
+from wagtail_localize.strings import StringValue
+
+from .constants import get_setting
+
+logger = logging.getLogger(__name__)
+
+# Store the original method so we can call it if needed
+_original_get_segments_for_translation = TranslationSource._get_segments_for_translation
+
+
+def _get_segments_for_translation_with_intentional_blanks(self, locale, fallback=False):
+    """
+    Enhanced version of _get_segments_for_translation that handles intentional blanks.
+
+    When a StringTranslation contains the __DO_NOT_TRANSLATE__ marker, this method
+    uses the source value instead, allowing translators to mark segments as
+    "do not translate" while still completing the translation.
+
+    This works correctly for all field types including multi-segment RichTextField.
+    """
+    if not get_setting("ENABLED"):
+        # Feature disabled, use original implementation
+        return _original_get_segments_for_translation(self, locale, fallback)
+
+    marker = get_setting("MARKER")
+    backup_separator = get_setting("BACKUP_SEPARATOR")
+
+    # Import here to avoid circular imports
+    from wagtail_localize.models import MissingTranslationError, StringSegment
+
+    string_segments = (
+        StringSegment.objects.filter(source=self)
+        .annotate_translation(locale)
+        .select_related("context", "string")
+    )
+
+    segments = []
+
+    for string_segment in string_segments:
+        if string_segment.translation:
+            # Check if this translation is marked as "do not translate"
+            translation_data = string_segment.translation
+
+            # Check for marker (exact match or with encoded backup)
+            if translation_data == marker or translation_data.startswith(
+                marker + backup_separator
+            ):
+                # Use source value instead of translation
+                logger.debug(
+                    f"Intentional blank detected for segment {string_segment.string_id} in locale {locale}, using source value"
+                )
+                string = StringValue(string_segment.string.data)
+            else:
+                # Use the translated value
+                string = StringValue(translation_data)
+        elif fallback:
+            string = StringValue(string_segment.string.data)
+        else:
+            raise MissingTranslationError(string_segment, locale)
+
+        segment_value = StringSegmentValue(
+            string_segment.context.path,
+            string,
+            attrs=json.loads(string_segment.attrs),
+        ).with_order(string_segment.order)
+
+        segments.append(segment_value)
+
+    # Handle template segments (templates are locale-independent)
+    template_segments = self.templatesegment_set.all().select_related("template")
+    for template_segment in template_segments:
+        segment_value = TemplateSegmentValue(
+            template_segment.context.path,
+            template_segment.template.template_format,
+            template_segment.template.template,
+            template_segment.template.string_count,
+        ).with_order(template_segment.order)
+
+        segments.append(segment_value)
+
+    # Handle related object segments
+    related_object_segments = self.relatedobjectsegment_set.all().select_related(
+        "object"
+    )
+    for related_object_segment in related_object_segments:
+        try:
+            instance = related_object_segment.object.get_instance(locale)
+        except related_object_segment.object.content_type.model_class().DoesNotExist:
+            if fallback:
+                instance = related_object_segment.object.get_instance(self.locale)
+            else:
+                raise
+
+        segment_value = RelatedObjectSegmentValue(
+            related_object_segment.context.path,
+            related_object_segment.object.content_type,
+            instance.pk,
+        ).with_order(related_object_segment.order)
+
+        segments.append(segment_value)
+
+    # Handle overridable segments (no locale filter needed - they're source-specific)
+    overridable_segments = self.overridablesegment_set.all().select_related("context")
+    for overridable_segment in overridable_segments:
+        segment_value = OverridableSegmentValue(
+            overridable_segment.context.path,
+            overridable_segment.data_json,  # Use data_json field
+        ).with_order(overridable_segment.order)
+
+        segments.append(segment_value)
+
+    return segments
+
+
+def apply_patch():
+    """
+    Apply the monkey-patch to TranslationSource.
+
+    This should be called from the app's ready() method.
+    """
+    TranslationSource._get_segments_for_translation = (
+        _get_segments_for_translation_with_intentional_blanks
+    )
+
+    # Also patch update_from_db to migrate markers after syncing translated pages.
+    # If a user 1. marks a field as 'Do Not Translate', then 2. updates the
+    # source field value, then 3. clicks 'Sync translated pages', we want to
+    # make sure that the field remains marked as 'Do Not Translate'.
+    _patch_update_from_db()
+
+
+# Store the original update_from_db method
+_original_update_from_db = TranslationSource.update_from_db
+
+
+def _update_from_db_with_marker_migration(self):
+    """
+    Enhanced version of update_from_db that migrates markers after updating.
+
+    This ensures that when source content changes and is synced, any 'Do Not Translate'
+    markers are automatically migrated to the new Strings.
+    """
+    # Call the original method to perform the update
+    result = _original_update_from_db(self)
+
+    if not get_setting("ENABLED"):
+        return result
+
+    # After updating, migrate any orphaned markers for all target locales
+    from wagtail_localize.models import Translation
+
+    from .utils import migrate_do_not_translate_markers
+
+    translations = Translation.objects.filter(source=self)
+
+    for translation in translations:
+        migrate_do_not_translate_markers(self, translation.target_locale)
+
+    return result
+
+
+def _patch_update_from_db():
+    """Patch the update_from_db method to migrate markers after sync."""
+    TranslationSource.update_from_db = _update_from_db_with_marker_migration

wagtail_localize_intentional_blanks/static/wagtail_localize_intentional_blanks/css/translation-editor.css

@@ -0,0 +1,114 @@
+/**
+ * Styles for Intentional Blanks UI
+ */
+
+/* Checkbox container */
+.do-not-translate-checkbox-container {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    padding: 4px 8px;
+    border-radius: 3px;
+    transition: background-color 0.2s;
+    vertical-align: middle;
+}
+
+.do-not-translate-checkbox-container:hover {
+    background-color: #f5f5f5;
+}
+
+/* Checkbox styling */
+.do-not-translate-checkbox {
+    width: 16px;
+    height: 16px;
+    cursor: pointer;
+    margin: 0;
+    accent-color: #007d7e;
+}
+
+.do-not-translate-checkbox:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+
+/* Label styling */
+.do-not-translate-label {
+    font-size: 13px;
+    color: #333;
+    cursor: pointer;
+    margin: 0;
+    user-select: none;
+    white-space: nowrap;
+}
+
+.do-not-translate-checkbox:disabled + .do-not-translate-label {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+
+/* Segment marked as do not translate */
+.do-not-translate {
+    background-color: #e8f5e9;
+    border-left: 4px solid #4caf50;
+    padding-left: 12px;
+    position: relative;
+    transition: background-color 0.3s ease, border-left 0.3s ease;
+}
+
+/* Badge that appears after field name */
+.do-not-translate-badge {
+    display: inline-block;
+    background: #4caf50;
+    color: white;
+    padding: 2px 8px;
+    border-radius: 3px;
+    font-size: 11px;
+    font-weight: bold;
+    margin-left: 8px;
+    text-transform: uppercase;
+    animation: fadeIn 0.3s ease-in;
+    vertical-align: middle;
+}
+
+@keyframes fadeIn {
+    from {
+        opacity: 0;
+        transform: translateY(-5px);
+    }
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
+}
+
+/* Input field when marked as do not translate */
+.do-not-translate input[readonly],
+.do-not-translate textarea[readonly] {
+    background-color: #f5f5f5;
+    cursor: not-allowed;
+    transition: background-color 0.3s ease, opacity 0.3s ease;
+}
+
+/* Smooth transitions for input fields */
+input[type="text"],
+textarea {
+    transition: background-color 0.3s ease, opacity 0.3s ease;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+    .do-not-translate-checkbox-container {
+        padding: 2px 4px;
+        gap: 6px;
+    }
+
+    .do-not-translate-label {
+        font-size: 12px;
+    }
+
+    .do-not-translate::before {
+        position: static;
+        display: block;
+        margin-bottom: 8px;
+    }
+}