Overridable segments models

These models are responsible for storing details about overridable segments in a translation source and storing the overridden data as well.

Overriding segments within an object allows non-text data to be modified for each locale.

graph TD


A[OverridableSegment] --> C[TranslationSource]
A[OverridableSegment] --> D[TranslationContext]
B[SegmentOverride] --> D
B[SegmentOverride] --> E[wagtail.Locale]

style C stroke-dasharray: 5 5
style D stroke-dasharray: 5 5
style E stroke-dasharray: 5 5

`SegmentOverride`

Bases: Model

Stores the overridden value of an OverridableSegment.

Some segments are not translatable, but can be optionally overridden in translations. For example, images.

If an overridable segment is overridden by a user for a locale, the value to override the segment with is stored in this model.

Attributes:

Name	Type	Description
`locale`	`ForeignKey to Locale`	The Locale to override.
`context`	`ForeignKey to TranslationContext`	The context to override. With the Locale, this tells us specifically which object/content path to override.
`last_translated_by`	`User`	The user who last updated this override.
`created_at`	`DateTimeField`	The date/time when the override was first created.
`updated_at`	`DateTimeField`	The date/time when the override was last updated.
`data_json`	`TextField with JSON contents`	The value to override the field with.
`has_error`	`BooleanField`	Set to True if the value of this overtride has an error. We store overrides with errors in case they were edited from an external system. This allows us to display the error in Wagtail.
`field_error`	`TextField`	if there was a database-level validation error while saving the translated object, that error is tored here.

Source code in wagtail_localize/models.py

class SegmentOverride(models.Model):
    """
    Stores the overridden value of an OverridableSegment.

    Some segments are not translatable, but can be optionally overridden in translations. For example, images.

    If an overridable segment is overridden by a user for a locale, the value to override the segment with is stored
    in this model.

    Attributes:
        locale (ForeignKey to Locale): The Locale to override.
        context (ForeignKey to TranslationContext): The context to override. With the Locale, this tells us specifically
            which object/content path to override.
        last_translated_by (User): The user who last updated this override.
        created_at (DateTimeField): The date/time when the override was first created.
        updated_at (DateTimeField): The date/time when the override was last updated.
        data_json (TextField with JSON contents): The value to override the field with.
        has_error (BooleanField): Set to True if the value of this overtride has an error. We store overrides with
            errors in case they were edited from an external system. This allows us to display the error in Wagtail.
        field_error (TextField): if there was a database-level validation error while saving the translated object, that
            error is tored here.
    """

    locale = models.ForeignKey(
        "wagtailcore.Locale", on_delete=models.CASCADE, related_name="overrides"
    )
    # FIXME: This should be a required field
    context = models.ForeignKey(
        TranslationContext,
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name="overrides",
    )
    last_translated_by = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name="+",
    )
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)
    data_json = models.TextField()
    has_error = models.BooleanField(default=False)

    field_error = models.TextField(blank=True)

    def __str__(self):
        return f"SegmentOverride: {self.locale_id}, {self.context_id}"

    @property
    def data(self):
        return json.loads(self.data_json)

    def set_field_error(self, error):
        """
        Returns a string containing any validation errors on the saved value.

        Returns:
            str: The validation error if there is one.
            None: If there isn't an error.
        """
        self.has_error = True
        # TODO (someday): We currently only support one error at a time
        self.field_error = error[0].messages[0]
        self.save(update_fields=["has_error", "field_error"])

    def get_error(self):
        """
        Returns a string containing any validation errors on the saved value.

        Returns:
            str: The validation error if there is one.
            None: If there isn't an error.
        """
        # Check if a database error was raised when we last attempted to publish
        if self.has_error and self.context is not None and self.field_error:
            return self.field_error

`get_error()`

Returns a string containing any validation errors on the saved value.

Returns:

Name	Type	Description
`str`		The validation error if there is one.
`None`		If there isn't an error.

Source code in wagtail_localize/models.py

def get_error(self):
    """
    Returns a string containing any validation errors on the saved value.

    Returns:
        str: The validation error if there is one.
        None: If there isn't an error.
    """
    # Check if a database error was raised when we last attempted to publish
    if self.has_error and self.context is not None and self.field_error:
        return self.field_error

`set_field_error(error)`

Returns a string containing any validation errors on the saved value.

Returns:

Name	Type	Description
`str`		The validation error if there is one.
`None`		If there isn't an error.

Source code in wagtail_localize/models.py

def set_field_error(self, error):
    """
    Returns a string containing any validation errors on the saved value.

    Returns:
        str: The validation error if there is one.
        None: If there isn't an error.
    """
    self.has_error = True
    # TODO (someday): We currently only support one error at a time
    self.field_error = error[0].messages[0]
    self.save(update_fields=["has_error", "field_error"])