Wagtail Localize

A Template Segment is used to manage the structure of rich text fields and blocks. It is an HTML blob that preserves the layout while marking where translated text should be inserted.

Instead of translating the HTML directly, Wagtail localize extracts the text into String Segments and replaces them in the template with <text> tags containing a position attribute. This allows the system to recombine the translated strings with the original HTML structure.

Key behaviors:

• Block tags (e.g., <p>, <li>, <h1>) are left in the template.
• Inline tags (e.g., <b>, <a>) are extracted along with the string segments. However, if an inline tag completely encapsulates a string segment, that tag remains in the template.
• Non-translatable elements like images or embeds are preserved in the template.

<h1><text position="0"></h1>
<p>
    <text position="1">
    <ul>
        <li><b><text position="2"></b></li>
    </ul>
</p>

When interpreting benchmark results, be aware of the following constraints:

• Synthetic Data: The fixtures are fixed and synthetic; results describe specific workloads, not all possible sites or content models.
• Database Environment: SQLite is used for cheap, reproducible local runs, but production database behavior and query costs may differ.
• Query Count Metric: A 'query count' refers to the number of entries in Django's query log. It is not a measure of database statement count or individual statement cost (e.g., a commit counts as one entry, as does an executemany regardless of row count).
• Timing: Measurements include cold Python and framework state; they do not model concurrent traffic or warmed application workers.
• Attribution: run.py can detect scaling issues but cannot attribute their cause. To find the cause, use run_attribution.py (to see where a flow's growth comes from) or run_query_doctor.py (for an external tool's opinion).

The benchmark catalog is defined in catalog.py. Each Flow in the catalog represents a specific measurement scenario and must implement three distinct responsibilities to ensure measurement accuracy:

1. setup: Asserts or establishes the pre-measurement scenario (e.g., creating data).
2. run: Performs only the specific operation being measured.
3. verify: Proves the operation occurred and returns the observed workload.

Best Practices:

• Keep fixture construction and verification logic outside of the run method.
• When writing tests for the catalog, prefer asserting properties like stable workload or a flat small-to-large query slope rather than asserting absolute query counts.

# Conceptual structure of a Flow in catalog.py
class MyFlow:
    def setup(self):
        # Establish pre-measurement scenario
        pass

    def run(self):
        # Perform ONLY the operation being measured
        pass

    def verify(self):
        # Prove operation happened and return observed workload
        pass

When you do not explicitly define a translatable_fields attribute on a model, Wagtail Localize uses an automatic discovery process to determine which fields should be translatable (translated per language) and which should be synchronised (copied from the source language to all translations).

The Discovery Process

1. Manual Override Check: If the model has a translatable_fields attribute defined, the auto-generation process is completely bypassed.
2. Field Discovery: The system inspects Django ORM fields. It excludes auto-fields (id), non-editable fields (editable=False), ManyToManyField, ParentalKey, parent link fields (page_ptr), and specific inherited fields (like MP_Node or Page metadata).
   • Text Fields: RichTextField and StreamField are marked as translatable. However, URLField, EmailField, and CharField with choices are marked as synchronised.
   • Relationships: ForeignKey and OneToOneField are translatable if the target model inherits from TranslatableMixin; otherwise, they are synchronised.
   • Custom Logic: Any field defining a get_translatable_segments method is marked as translatable.
   • Default: All other valid fields are marked as synchronised.
3. Child Relationship Discovery: The system identifies relationships created via ParentalKey (often used for inline panels). If the child model inherits from TranslatableMixin, the relationship is translatable. Otherwise, it is synchronised. (Note: For Page models, the comments relation is always excluded).
4. Override Application: Finally, the system checks for an override_translatable_fields attribute on the model to apply developer-defined adjustments to the automatic decisions.

Wagtail Localize categorizes fields into three distinct behaviors that determine how content is handled during translation:

1. Translatable:
   • Text fields: Content is extracted for manual translation by editors.
   • Foreign keys: The referenced model is also translatable. When a translation is created/updated, the field automatically links to the translation of the referenced object.
   • StreamFields: Translatable fields within blocks are extracted, while some blocks may remain synchronised.
   • Child relations (ParentalKey): The child model is translatable and contains its own translatable fields.
2. Synchronised: The value is copied from the source to the translation whenever the translation is updated. Depending on the field type, these may be overridable (editable on the translation, but stops receiving source updates until 'Revert to source version' is clicked) or non-overridable.
3. Neither / excluded: The field is not updated after the initial translation creation. This is typically used for internal fields like id or page paths.