Skip to content

Translatable segments models

These models are responsible for storing details about translatable segments within a translation source.

graph TD A[StringSegment] --> F[TranslationSource] B[TemplateSegment] --> F C[RelatedObjectSegment] --> F A[StringSegment] --> G[TranslationContext] B[TemplateSegment] --> G C[RelatedObjectSegment] --> G A[StringSegment] --> H[String] B[TemplateSegment] --> I[Template] style F stroke-dasharray: 5 5 style G stroke-dasharray: 5 5 style H stroke-dasharray: 5 5 style I stroke-dasharray: 5 5

OverridableSegment

Represents an overridable segment that was extracted from a TranslationSource.

Attributes:

Name Type Description
data_json TextField with JSON content

The value of the overridable segment as it is in the source.
source ForeignKey to TranslationSource

The source content that the string was extracted from.
context ForeignKey to TranslationContext

The context, which contains the position of the string in the source content.
order PositiveIntegerField

The index that this segment appears on the page.

data property readonly

Returns the decoded JSON data that's stored in .data_json

RelatedObjectSegment

Represents a related object segment that was extracted from a TranslationSource.

Attributes:

Name Type Description
object ForeignKey to TranslatableObject

The TranslatableObject instance that represents the related object.
source ForeignKey to TranslationSource

The source content that the string was extracted from.
context ForeignKey to TranslationContext

The context, which contains the position of the string in the source content.
order PositiveIntegerField

The index that this segment appears on the page.

SegmentOverride

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.

get_error(self)

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

Returns:

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(self, error)

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

Returns:

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"])

StringSegment

Represents a translatable string that was extracted from a TranslationSource.

Attributes:

Name Type Description
string ForeignKey to String

The string that was extracted.
attrs TextField with JSON contents

The HTML attributes that were extracted from the string.

When we extract the segment, we replace HTML attributes with id attributes and the attributes that were removed are stored in this field. When the translated strings come back, we replace the id attributes with the original HTML attributes.

For example, for this segment:

<a href="https://www.example.com">Link to example.com</a>

We will remove the href tag from it and replace it with an id:

<a id="a1">Link to example.com</a>

And then this field will be populated with the following JSON:

{
    "a#a1": {
        "href": "https://www.example.com"
    }
}
source ForiegnKey[TranslationSource]

The source content that the string was extracted from.
context ForeignKey to TranslationContext

The context, which contains the position of the string in the source content.
order PositiveIntegerField

The index that this segment appears on the page.

from_value(source, language, value) classmethod

Gets or creates a TemplateSegment instance from a TemplateValue object.

Parameters:

Name Type Description Default
source TranslationSource

The source the template value was extracted from.

 required
template_value TemplateValue

The value of the template.

 required

Returns:

Type Description
TemplateSegment

The TemplateSegment instance that corresponds with the given template_value and source.
Source code in wagtail_localize/models.py 
@classmethod
def from_value(cls, source, language, value):
    """
    Gets or creates a TemplateSegment instance from a TemplateValue object.

    Args:
        source (TranslationSource): The source the template value was extracted from.
        template_value (TemplateValue): The value of the template.

    Returns:
        TemplateSegment: The TemplateSegment instance that corresponds with the given template_value and source.
    """
    string = String.from_value(language, value.string)
    context, context_created = TranslationContext.objects.get_or_create(
        object_id=source.object_id,
        path=value.path,
    )

    segment, created = cls.objects.get_or_create(
        source=source,
        context=context,
        order=value.order,
        string=string,
        attrs=json.dumps(value.attrs),
    )

    return segment

TemplateSegment

Represents a template segment that was extracted from a TranslationSource.

Attributes:

Name Type Description
template ForeignKey to Template

The template that was extracted.
source ForiegnKey[TranslationSource]

The source content that the string was extracted from.
context ForeignKey to TranslationContext

The context, which contains the position of the string in the source content.
order PositiveIntegerField

The index that this segment appears on the page.

from_value(source, value) classmethod

Gets or creates a TemplateSegment instance from a TemplateValue object.

Parameters:

Name Type Description Default
source TranslationSource

The source the template value was extracted from.

 required
template_value TemplateValue

The value of the template.

 required

Returns:

Type Description
TemplateSegment

The TemplateSegment instance that corresponds with the given template_value and source.
Source code in wagtail_localize/models.py 
@classmethod
def from_value(cls, source, value):
    """
    Gets or creates a TemplateSegment instance from a TemplateValue object.

    Args:
        source (TranslationSource): The source the template value was extracted from.
        template_value (TemplateValue): The value of the template.

    Returns:
        TemplateSegment: The TemplateSegment instance that corresponds with the given template_value and source.
    """
    template = Template.from_value(value)
    context, context_created = TranslationContext.objects.get_or_create(
        object_id=source.object_id,
        path=value.path,
    )

    segment, created = cls.objects.get_or_create(
        source=source,
        context=context,
        order=value.order,
        template=template,
    )

    return segment