Allow defining translatable_fields/override_translatable_fields on StructBlock

docs/how-to/field-configuration.md

@@ -1,9 +1,5 @@
 # Configuring translatable fields
 
-!!! attention
-
-    It is not currently possible to configure `StructBlock` translatable fields. See [Issue #307](https://github.com/wagtail/wagtail-localize/issues/307) for more details.
-
 By default, Wagtail Localize will decide for you which fields are translatable and which fields should just be synchronised.
 This is decided by some simple rules described in the [Auto-generation of Translatable Fields](/concept/translatable-fields-autogen)
 explanation.
@@ -105,3 +101,48 @@ class BlogPage(Page):
         SynchronizedField("slug"),
     ]
 ```
+
+## Specifying Translatable Fields within a StructBlock
+
+**By default, all sub-fields within a StructBlock are included for translation.** However, there may be instances where certain fields within the StructBlock should be excluded from translation. To facilitate this, we've introduced the **`translatable_blocks`** parameter.
+
+The **`translatable_blocks`** parameter allows you to specify a list of block names that should be processed for translation. Any fields within the StructBlock that are not included in this list will be excluded from translation.
+
+For instance, consider a YouTubeBlock that contains a CharBlock for a video ID and a TextBlock for a video description. The video ID is not something we'd want to send for translation, but the description is. To exclude the video ID from translation, we would use the **`translatable_blocks`** parameter as follows:
+
+```python
+class YouTubeBlock(blocks.StructBlock):
+    video_id = blocks.CharBlock(
+        required=True, help_text="Add a YouTube video ID. You can find this in the url."
+    )
+    description = blocks.TextBlock(
+        required=False, help_text="Add a description for the video."
+    )
+
+    translatable_blocks = ["description"]
+```
+
+In this example, only the description field will be included for translation. The video_id field will be excluded from both the translation UI in Wagtail and the exported PO file.
+
+##### Managing Images and Overrideable Segments within a StructBlock
+
+When dealing with overrideable segments such as images within a StructBlock, it's important to note that ignoring these segments could result in losing the ability to use a different image for different languages. If you want to maintain the ability to override an image, include it in the list of translatable_blocks to preserve the default behavior.
+
+Consider the following example of a **`LocationImageBlock`** that contains an **`ImageChooserBlock`** for an image and a **`TextBlock`** for a caption, along with a **`TextBlock`** for an address:
+
+```python
+class LocationImageBlock(blocks.StructBlock):
+    """Location image block with caption."""
+
+    image = ImageChooserBlock(required=True, help_text="Add a banner image.")
+    caption = blocks.TextBlock(
+        required=False, help_text="Add a description for the image."
+    )
+    address = blocks.TextBlock(
+        required=True, help_text="Enter the address for this location."
+    )
+
+    translatable_blocks = ["caption", "image"]
+```
+
+In this example, the image is still overrideable, but the address, which is unique to this location, is locked in by translatable_blocks. This allows you to maintain the flexibility of using different images for different languages, while ensuring that certain unique information remains consistent across all translations.

wagtail_localize/segments/extract.py

@@ -123,7 +123,15 @@ def handle_related_object_block(self, related_object):
     def handle_struct_block(self, struct_block, raw_value=None):
         segments = []
 
+        translatable_blocks = getattr(struct_block.block, "translatable_blocks", None)
+
         for field_name, block_value in struct_block.items():
+            if (
+                translatable_blocks is not None
+                and field_name not in translatable_blocks
+            ):
+                continue
+
             block_type = struct_block.block.child_blocks[field_name]
             try:
                 block_raw_value = raw_value["value"].get(field_name)

wagtail_localize/segments/tests/test_segment_extraction.py

@@ -533,6 +533,40 @@ def test_customstructblock(self):
             ],
         )
 
+    def test_structblockwithoverrides(self):
+        block_id = uuid.uuid4()
+        page = make_test_page_with_streamfield_block(
+            str(block_id),
+            "test_structblockwithoverrides",
+            {"field_a": "Test content", "field_b": "Non-translatable content"},
+        )
+
+        segments = extract_segments(page)
+
+        self.assertEqual(
+            segments,
+            [
+                StringSegmentValue(
+                    f"test_streamfield.{block_id}.field_a",
+                    "Test content",
+                )
+            ],
+        )
+
+    def test_structblockignoreall(self):
+        block_id = uuid.uuid4()
+        page = make_test_page_with_streamfield_block(
+            str(block_id),
+            "test_structblockignoreall",
+            {
+                "field_a": "Non-translatable content",
+                "field_b": "Non-translatable content",
+            },
+        )
+
+        segments = extract_segments(page)
+        self.assertEqual(segments, [])
+
     def test_customblockwithoutextractmethod(self):
         block_id = uuid.uuid4()
         page = make_test_page_with_streamfield_block(

wagtail_localize/test/models.py

@@ -119,6 +119,20 @@ class TestNestedStreamBlock(blocks.StreamBlock):
     chooser_in_list = blocks.ListBlock(blocks.PageChooserBlock())
 
 
+class TestStructBlockOverride(blocks.StructBlock):
+    field_a = blocks.TextBlock()
+    field_b = blocks.TextBlock()
+
+    translatable_blocks = ["field_a"]
+
+
+class TestStructBlockIgnoreAll(blocks.StructBlock):
+    field_a = blocks.TextBlock()
+    field_b = blocks.TextBlock()
+
+    translatable_blocks = []
+
+
 class TestNestedChooserStructBlock(blocks.StructBlock):
     nested_page = TestChooserStructBlock()
 
@@ -196,6 +210,8 @@ class TestStreamBlock(blocks.StreamBlock):
     test_nestedstreamblock = TestNestedStreamBlock()
     test_streamblock_in_structblock = TestStreamBlockInStructBlock()
     test_customstructblock = CustomStructBlock()
+    test_structblockwithoverrides = TestStructBlockOverride()
+    test_structblockignoreall = TestStructBlockIgnoreAll()
     test_customblockwithoutextractmethod = CustomBlockWithoutExtractMethod()
     test_pagechooserblock = blocks.PageChooserBlock()
     test_pagechooserblock_with_restricted_types = blocks.PageChooserBlock(