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

wagtail_localize_intentional_blanks/views.py

@@ -0,0 +1,340 @@
+"""
+Views for handling AJAX requests from the translation editor.
+"""
+
+import logging
+
+from django.contrib.auth.decorators import login_required
+from django.core.exceptions import PermissionDenied
+from django.db.models import Q
+from django.http import JsonResponse
+from django.views.decorators.cache import never_cache
+from django.views.decorators.http import require_POST
+from wagtail_localize.models import (
+    StringSegment,
+    StringTranslation,
+    Translation,
+)
+
+from .constants import get_setting
+from .utils import (
+    get_backup_separator,
+    is_do_not_translate,
+    mark_segment_do_not_translate,
+    unmark_segment_do_not_translate,
+    validate_configuration,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def check_permission(user):
+    """
+    Check if user has permission to mark segments as "do not translate".
+
+    Args:
+        user: Django User instance
+
+    Raises:
+        PermissionDenied if user doesn't have permission
+    """
+    required_permission = get_setting("REQUIRED_PERMISSION")
+
+    if required_permission is None:
+        # No specific permission required
+        return True
+
+    if not user.has_perm(required_permission):
+        raise PermissionDenied(
+            f"User does not have required permission: {required_permission}"
+        )
+
+    return True
+
+
+@login_required
+@require_POST
+def mark_segment_do_not_translate_view(request, translation_id, segment_id):
+    """
+    Mark a translation segment as "do not translate".
+
+    Args:
+        translation_id: The Translation ID
+        segment_id: The StringSegment ID (not String ID)
+
+    POST params:
+        do_not_translate: bool - True to mark as do not translate, False to unmark
+
+    Returns:
+        JSON response with success status and source value
+
+    Example AJAX call:
+        fetch('/intentional-blanks/translations/123/segment/456/do-not-translate/', {
+            method: 'POST',
+            headers: {'X-CSRFToken': csrfToken},
+            body: new FormData({do_not_translate: 'true'})
+        })
+    """
+    try:
+        # Check permissions
+        check_permission(request.user)
+
+        # Get objects
+        translation = Translation.objects.get(id=translation_id)
+
+        # segment_id is the StringSegment ID (matches wagtail-localize's segment.id)
+        logger.info(
+            f"Marking segment as do not translate: translation_id={translation_id}, segment_id={segment_id}"
+        )
+
+        segment = StringSegment.objects.get(id=segment_id, source=translation.source)
+        string = segment.string
+
+        if not string:
+            logger.error(f"StringSegment {segment_id} has no associated String")
+            return JsonResponse(
+                {
+                    "success": False,
+                    "error": f"Segment {segment_id} has no associated String. The translation may be corrupted.",
+                },
+                status=400,
+            )
+
+        # Get action - only accept explicit 'true' or 'false'
+        do_not_translate_param = request.POST.get("do_not_translate", "").lower()
+        if do_not_translate_param not in ("true", "false"):
+            return JsonResponse(
+                {
+                    "success": False,
+                    "error": 'Invalid do_not_translate parameter. Must be "true" or "false".',
+                },
+                status=400,
+            )
+
+        do_not_translate = do_not_translate_param == "true"
+
+        if do_not_translate:
+            mark_segment_do_not_translate(translation, segment, user=request.user)
+            message = "Segment marked as do not translate"
+        else:
+            unmark_segment_do_not_translate(translation, segment)
+            message = "Segment unmarked, ready for manual translation"
+
+        # Get the source text to display in UI
+        source_text = segment.string.data if segment.string else ""
+
+        # Get the translated value (if any) for unmarking
+        translated_value = None
+        if not do_not_translate:
+            try:
+                existing_translation = StringTranslation.objects.get(
+                    translation_of=segment.string,
+                    locale=translation.target_locale,
+                    context=segment.context,
+                )
+                validate_configuration()
+                marker = get_setting("MARKER")
+                backup_separator = get_backup_separator()
+                # Make sure it's not the marker or encoded marker format
+                if (
+                    existing_translation.data != marker
+                    and not existing_translation.data.startswith(
+                        marker + backup_separator
+                    )
+                ):
+                    translated_value = existing_translation.data
+            except StringTranslation.DoesNotExist:
+                pass
+
+        return JsonResponse(
+            {
+                "success": True,
+                "source_value": source_text,
+                "translated_value": translated_value,
+                "do_not_translate": do_not_translate,
+                "message": message,
+            }
+        )
+
+    except Translation.DoesNotExist:
+        return JsonResponse(
+            {"success": False, "error": "Translation not found"}, status=404
+        )
+
+    except StringSegment.DoesNotExist:
+        logger.error(
+            f"StringSegment {segment_id} does not exist for translation {translation_id}"
+        )
+        return JsonResponse(
+            {
+                "success": False,
+                "error": f"Segment {segment_id} not found. The translation may need to be re-synced.",
+            },
+            status=404,
+        )
+
+    except PermissionDenied as e:
+        return JsonResponse({"success": False, "error": str(e)}, status=403)
+
+    except Exception as e:
+        # Log the error
+        logger.exception("Error in mark_segment_do_not_translate_view")
+
+        return JsonResponse({"success": False, "error": str(e)}, status=400)
+
+
+@login_required
+def get_segment_status(request, translation_id, segment_id):
+    """
+    Get the current status of a segment (marked as do not translate or not).
+
+    Args:
+        translation_id: The Translation ID
+        segment_id: The StringSegment ID (not String ID)
+
+    Returns:
+        JSON response with status info
+
+    Example:
+        GET /intentional-blanks/translations/123/segment/456/status/
+    """
+    try:
+        check_permission(request.user)
+
+        translation = Translation.objects.get(id=translation_id)
+
+        # segment_id is the StringSegment ID (matches wagtail-localize's segment.id)
+        segment = StringSegment.objects.get(id=segment_id, source=translation.source)
+        string = segment.string
+
+        if not string:
+            return JsonResponse(
+                {
+                    "success": False,
+                    "error": f"Segment {segment_id} has no associated String.",
+                },
+                status=400,
+            )
+
+        try:
+            string_translation = StringTranslation.objects.get(
+                translation_of=segment.string,  # translation_of expects a String, not StringSegment
+                locale=translation.target_locale,
+            )
+            do_not_translate = is_do_not_translate(string_translation)
+            translated_text = string_translation.data if not do_not_translate else None
+        except StringTranslation.DoesNotExist:
+            do_not_translate = False
+            translated_text = None
+
+        source_text = segment.string.data if segment.string else ""
+
+        return JsonResponse(
+            {
+                "success": True,
+                "do_not_translate": do_not_translate,
+                "source_text": source_text,
+                "translated_text": translated_text,
+            }
+        )
+
+    except Translation.DoesNotExist:
+        return JsonResponse(
+            {"success": False, "error": "Translation not found"}, status=404
+        )
+
+    except StringSegment.DoesNotExist:
+        logger.error(
+            f"StringSegment {segment_id} does not exist for translation {translation_id}"
+        )
+        return JsonResponse(
+            {
+                "success": False,
+                "error": f"Segment {segment_id} not found. The translation may need to be re-synced.",
+            },
+            status=404,
+        )
+
+    except PermissionDenied as e:
+        return JsonResponse({"success": False, "error": str(e)}, status=403)
+
+    except Exception as e:
+        return JsonResponse({"success": False, "error": str(e)}, status=400)
+
+
+@login_required
+@never_cache
+def get_translation_status(request, translation_id):
+    """
+    Get the status of all segments for a translation in one request.
+
+    Args:
+        translation_id: The Translation ID
+
+    Returns:
+        JSON response with a mapping of StringSegment IDs to their status
+
+    Example:
+        GET /intentional-blanks/translations/123/status/
+        Response: {
+            "success": true,
+            "segments": {
+                "456": {"do_not_translate": true, "source_text": "Hello"},
+                "457": {"do_not_translate": false, "source_text": "World"}
+            }
+        }
+        (Keys are StringSegment IDs, not String IDs)
+    """
+    try:
+        check_permission(request.user)
+
+        translation = Translation.objects.get(id=translation_id)
+
+        # Get all string translations for this translation source that are marked as "do not translate"
+        validate_configuration()
+        marker = get_setting("MARKER")
+        backup_separator = get_backup_separator()
+
+        # Get all StringSegments for this source
+        all_segments = StringSegment.objects.filter(
+            source=translation.source
+        ).select_related("string")
+        string_ids = list(all_segments.values_list("string_id", flat=True))
+
+        # Get marked translations
+        marked_translations = (
+            StringTranslation.objects.filter(
+                locale=translation.target_locale, translation_of_id__in=string_ids
+            )
+            .filter(Q(data=marker) | Q(data__startswith=marker + backup_separator))
+            .select_related("translation_of")
+        )
+
+        # Build a map: String ID -> StringSegment ID
+        string_to_segment_map = {seg.string_id: seg.id for seg in all_segments}
+
+        # Build a mapping of StringSegment ID -> status
+        segments = {}
+        for st in marked_translations:
+            string_id = st.translation_of.id
+            segment_id = string_to_segment_map.get(string_id)
+
+            if segment_id:
+                segments[str(segment_id)] = {
+                    "do_not_translate": True,
+                    "source_text": st.translation_of.data,
+                }
+
+        return JsonResponse({"success": True, "segments": segments})
+
+    except Translation.DoesNotExist:
+        return JsonResponse(
+            {"success": False, "error": "Translation not found"}, status=404
+        )
+
+    except PermissionDenied as e:
+        return JsonResponse({"success": False, "error": str(e)}, status=403)
+
+    except Exception as e:
+        logger.exception("Error in get_translation_status")
+        return JsonResponse({"success": False, "error": str(e)}, status=400)

wagtail_localize_intentional_blanks/wagtail_hooks.py

@@ -0,0 +1,8 @@
+"""
+Wagtail hooks for intentional blanks integration.
+"""
+
+# Placeholder for future Wagtail hooks
+# The intentional blanks functionality is now implemented via a monkey-patch
+# to wagtail-localize's TranslationSource._get_segments_for_translation()
+# See patch.py for the implementation.

wagtail_localize_intentional_blanks-0.1.0.dist-info/METADATA

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: wagtail-localize-intentional-blanks
+Version: 0.1.0
+Summary: Allow translators to mark wagtail-localize segments as 'do not translate'
+Author-email: "Lincoln Loop, LLC" <info@lincolnloop.com>
+License: MIT
+Project-URL: Homepage, https://github.com/lincolnloop/wagtail-localize-intentional-blanks
+Project-URL: Documentation, https://github.com/lincolnloop/wagtail-localize-intentional-blanks
+Project-URL: Repository, https://github.com/lincolnloop/wagtail-localize-intentional-blanks
+Project-URL: Bug Tracker, https://github.com/lincolnloop/wagtail-localize-intentional-blanks/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Wagtail
+Classifier: Framework :: Wagtail :: 5
+Classifier: Framework :: Wagtail :: 6
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Internationalization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Requires-Dist: wagtail>=5.2
+Requires-Dist: wagtail-localize>=1.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-django>=4.5; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: selenium>=4.0; extra == "dev"
+Requires-Dist: pillow>=10.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: isort>=5.12; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0; extra == "docs"
+Dynamic: license-file
+
+# wagtail-localize-intentional-blanks
+
+A Wagtail library that extends [wagtail-localize](https://github.com/wagtail/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.
+
+<img width="985" height="236" alt="url_intentionally_blank" src="https://github.com/user-attachments/assets/310c5ad0-780c-43a6-a73f-1783c1d5f30e" />
+<img width="1088" height="230" alt="number_intentionally_blank" src="https://github.com/user-attachments/assets/e9be46c7-86cd-43b7-a0d7-1747714c4bf9" />
+
+
+## Features
+
+- ✅ **Translator Control**: Translators decide which fields to not translate
+- ✅ **Per-Locale Flexibility**: One language can translate a value while another language can use the source value
+- ✅ **Progress Tracking**: "Do not translate" segments count as translated by `wagtail-localize`
+- ✅ **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
+
+```bash
+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.
+
+```python
+# 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
+
+```python
+# urls.py
+
+from django.urls import path, include
+
+urlpatterns = [
+    # ... other patterns
+    path(
+        'intentional-blanks/', include('wagtail_localize_intentional_blanks.urls')
+    ),
+]
+```
+
+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 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 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)
+5. When the page renders, it automatically shows the source value for that field
+6. If the value in the original page changes, and the translated pages are synced, the segment still counts as translated (shows green) and when the page renders, it shows the updated 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:
+
+```python
+# settings.py
+
+# Enable/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:
+
+```python
+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](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome!
+
+## Development
+
+### Setting Up for Development
+
+1. Clone the repository:
+```bash
+git clone https://github.com/lincolnloop/wagtail-localize-intentional-blanks.git
+cd wagtail-localize-intentional-blanks
+```
+
+2. Install the package with development dependencies:
+```bash
+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:
+```bash
+pytest
+```
+
+Run tests with coverage:
+```bash
+pytest --cov=wagtail_localize_intentional_blanks
+```
+
+Run specific test files:
+```bash
+pytest tests/test_utils.py
+pytest tests/test_views.py
+```
+
+### Code Quality
+
+Check code with ruff:
+```bash
+ruff check .
+```
+
+Format with ruff:
+```bash
+ruff format .
+```
+
+## Credits
+
+Created by [Lincoln Loop, LLC](https://lincolnloop.com) for the Wagtail community.

wagtail_localize_intentional_blanks-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+wagtail_localize_intentional_blanks/__init__.py,sha256=T5-7FLF993ygWsaNKweK7utCRqxJVLwgB2Czi4Lj8_0,857
+wagtail_localize_intentional_blanks/apps.py,sha256=wTgWJ_1whFkExZmUhBEnHj17sbgqwiHVRA2TPzcv1PI,897
+wagtail_localize_intentional_blanks/constants.py,sha256=yhrGeuoe9wmHpqdwztaYQ-7ctz8RsWx64myQU73iKg4,1352
+wagtail_localize_intentional_blanks/patch.py,sha256=e-SpjXvFtyZEOhhj67RvWYvrYgFqbAZTkPOUaHL6VAA,6590
+wagtail_localize_intentional_blanks/urls.py,sha256=KvZ-Jp0ci2qsV6Gc8yajkDYNBlZkCDkqSi4l80bIFN0,685
+wagtail_localize_intentional_blanks/utils.py,sha256=tRCQA3pIRiRFJKRfKcSvQ2K4DLVNahtnPYxnyw3FjGY,14423
+wagtail_localize_intentional_blanks/views.py,sha256=ffvXdve9vl4NwVsmoXj3RBy2W4XOV0IvYVFpaAfqnnI,11244
+wagtail_localize_intentional_blanks/wagtail_hooks.py,sha256=Bk9bpdsquvO_ccbF1bTjpK8q6Yo975fcN_SrrEY1mO0,288
+wagtail_localize_intentional_blanks/static/wagtail_localize_intentional_blanks/css/translation-editor.css,sha256=Iw_3iA35_8EreFaMvFya852RBlUQLiPDPN_8PElxl7k,2363
+wagtail_localize_intentional_blanks/static/wagtail_localize_intentional_blanks/js/translation-editor.js,sha256=JE1g4wDxkWfbc6_FPFI-f2ZgEoOjqrgik4t6dmAxj9s,22753
+wagtail_localize_intentional_blanks/templates/wagtail_localize/admin/edit_translation.html,sha256=ePGwLgWV8__Y3W0LxXAbDv2XCN49l1ZQ__aSkxMbck4,635
+wagtail_localize_intentional_blanks/templatetags/__init__.py,sha256=7wPp_kk5jsll7wxkgUqWBBfHOPDP1tc_D2Cx7gJyH1o,63
+wagtail_localize_intentional_blanks/templatetags/intentional_blanks.py,sha256=66yrni7vY-XPLteVMRcO_aS-Fp0eHuPWe0y3lxV3Bq0,1390
+wagtail_localize_intentional_blanks-0.1.0.dist-info/licenses/LICENSE,sha256=b99OiFRYnxpXDbpBxCVdf-9VJ4htEBKvbky52Jhq08g,1138
+wagtail_localize_intentional_blanks-0.1.0.dist-info/METADATA,sha256=gdwODZ1FJeqRQpz47VAd48otMJDVxe7FpPY0l48rBiQ,7933
+wagtail_localize_intentional_blanks-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+wagtail_localize_intentional_blanks-0.1.0.dist-info/top_level.txt,sha256=H6IKrSKJO-H7vBnwcudF-yPhvlz8A_DD6XcKfioV8dQ,36
+wagtail_localize_intentional_blanks-0.1.0.dist-info/RECORD,,

wagtail_localize_intentional_blanks-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wagtail_localize_intentional_blanks-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,23 @@
+All original code is provided under the MIT License:
+
+The MIT License (MIT)
+
+Copyright (c) 2025 Lincoln Loop, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

wagtail_localize_intentional_blanks-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+wagtail_localize_intentional_blanks