Skip to content

Translation memory models

These models are responsible for storing individual source strings and their translations.

graph TD
A[String] --> B[wagtail.Locale]
C[StringTranslation] --> B
C --> A
C --> D[TranslationContext]
D --> E[TranslatableObject]
F[Template]

style B stroke-dasharray: 5 5
style E stroke-dasharray: 5 5

String

Bases: Model

Represents a unique string of translatable text.

Attributes:

Name Type Description
locale ForeignKey to Locale

The locale of the string.

data TextField

The string.

data_hash UUIDField

A hash of the string, for more efficient indexing of long strings.

Source code in wagtail_localize/models.py
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
class String(models.Model):
    """
    Represents a unique string of translatable text.

    Attributes:
        locale (ForeignKey to Locale): The locale of the string.
        data (TextField): The string.
        data_hash (UUIDField): A hash of the string, for more efficient indexing of long strings.
    """

    UUID_NAMESPACE = uuid.UUID("59ed7d1c-7eb5-45fa-9c8b-7a7057ed56d7")

    locale = models.ForeignKey(
        "wagtailcore.Locale", on_delete=models.CASCADE, related_name="source_strings"
    )

    data_hash = models.UUIDField()
    data = models.TextField()

    class Meta:
        unique_together = [("locale", "data_hash")]

    def __str__(self):
        return f"String: {self.locale_id}, {self.data_hash}"

    def save(self, *args, **kwargs):
        if self.data and self.data_hash is None:
            self.data_hash = self._get_data_hash(self.data)

        return super().save(*args, **kwargs)

    @classmethod
    def _get_data_hash(cls, data):
        """
        Generates a UUID from the given string.

        Args:
            data (string): The string to generate a hash of.

        Returns:
            UUID: The UUID hash.
        """
        return uuid.uuid5(cls.UUID_NAMESPACE, data)

    @classmethod
    def from_value(cls, locale, stringvalue):
        """
        Gets or creates a String instance from a StringValue object.

        Args:
            locale (ForeignKey to Locale) The locale of the string.
            stringvalue (StringValue): The value of the string.

        Returns:
            String: The String instance that corresponds with the given stringvalue and locale.
        """
        string, created = cls.objects.get_or_create(
            locale_id=pk(locale),
            data_hash=cls._get_data_hash(stringvalue.data),
            defaults={"data": stringvalue.data},
        )

        return string

    def as_value(self):
        """
        Creates a StringValue object from the contents of this string.

        Returns:
            StringValue: A StringValue instance with the content of this String.
        """
        return StringValue(self.data)

_get_data_hash(data) classmethod

Generates a UUID from the given string.

Parameters:

Name Type Description Default
data string

The string to generate a hash of.

required

Returns:

Name Type Description
UUID

The UUID hash.

Source code in wagtail_localize/models.py
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
@classmethod
def _get_data_hash(cls, data):
    """
    Generates a UUID from the given string.

    Args:
        data (string): The string to generate a hash of.

    Returns:
        UUID: The UUID hash.
    """
    return uuid.uuid5(cls.UUID_NAMESPACE, data)

as_value()

Creates a StringValue object from the contents of this string.

Returns:

Name Type Description
StringValue

A StringValue instance with the content of this String.

Source code in wagtail_localize/models.py
1463
1464
1465
1466
1467
1468
1469
1470
def as_value(self):
    """
    Creates a StringValue object from the contents of this string.

    Returns:
        StringValue: A StringValue instance with the content of this String.
    """
    return StringValue(self.data)

from_value(locale, stringvalue) classmethod

Gets or creates a String instance from a StringValue object.

Parameters:

Name Type Description Default
stringvalue StringValue

The value of the string.

required

Returns:

Name Type Description
String

The String instance that corresponds with the given stringvalue and locale.

Source code in wagtail_localize/models.py
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
@classmethod
def from_value(cls, locale, stringvalue):
    """
    Gets or creates a String instance from a StringValue object.

    Args:
        locale (ForeignKey to Locale) The locale of the string.
        stringvalue (StringValue): The value of the string.

    Returns:
        String: The String instance that corresponds with the given stringvalue and locale.
    """
    string, created = cls.objects.get_or_create(
        locale_id=pk(locale),
        data_hash=cls._get_data_hash(stringvalue.data),
        defaults={"data": stringvalue.data},
    )

    return string

TranslationContext

Bases: Model

Represents a context that a string may be translated in.

Strings can be translated differently in different contexts. A context is a combination of an object and content path.

Attributes:

Name Type Description
object ForeignKey to TranslatableObject

The object.

path TextField

The content path.

field_path TextField

the field path.

path_id UUIDField

A hash of the path for efficient indexing of long content paths.

Source code in wagtail_localize/models.py
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
class TranslationContext(models.Model):
    """
    Represents a context that a string may be translated in.

    Strings can be translated differently in different contexts. A context is a combination of an object and content
    path.

    Attributes:
        object (ForeignKey to TranslatableObject): The object.
        path (TextField): The content path.
        field_path (TextField): the field path.
        path_id (UUIDField): A hash of the path for efficient indexing of long content paths.
    """

    object = models.ForeignKey(
        TranslatableObject, on_delete=models.CASCADE, related_name="+"
    )
    path_id = models.UUIDField()
    path = models.TextField()
    field_path = models.TextField()

    class Meta:
        unique_together = [
            ("object", "path_id"),
        ]

    def __str__(self):
        return f"TranslationContext: {self.object_id}, {self.path_id}, {self.path}, {self.field_path}"

    def save(self, *args, **kwargs):
        if self.path and self.path_id is None:
            self.path_id = self._get_path_id(self.path)

        return super().save(*args, **kwargs)

    @classmethod
    def _get_path_id(cls, path):
        """
        Generates a UUID from the given content path.

        Args:
            path (string): The content path to generate a hash of.

        Returns:
            UUID: The UUID hash.
        """
        return uuid.uuid5(uuid.UUID("fcab004a-2b50-11ea-978f-2e728ce88125"), path)

    def get_field_path(self, instance):
        """
        Gets the field path for this context

        Field path's were introduced in version 1.0, any contexts that were created before that release won't have one.
        """
        if not self.field_path:

            def get_field_path_from_field(instance, path_components):
                field_name = path_components[0]
                field = instance._meta.get_field(field_name)

                if isinstance(field, StreamField):

                    def get_field_path_from_streamfield_block(value, path_components):
                        if isinstance(value, blocks.StructValue):
                            blocks_by_id = dict(value)
                        else:
                            if isinstance(value, ListValue):
                                blocks_by_id = {
                                    block.id: block for block in value.bound_blocks
                                }
                            else:
                                blocks_by_id = {block.id: block for block in value}

                        block_id = path_components[0]
                        block = blocks_by_id[block_id]

                        if isinstance(value, blocks.StructValue):
                            block_type = block_id
                            block_def = value.block.child_blocks[block_type]
                            block_value = block
                        else:
                            if isinstance(value, ListValue):
                                block_type = "item"
                                block_def = value.list_block.child_block
                            else:
                                block_type = block.block_type
                                block_def = value.stream_block.child_blocks[block_type]
                            block_value = block.value

                        if isinstance(
                            block_def,
                            (blocks.StructBlock, blocks.StreamBlock, blocks.ListBlock),
                        ):
                            return [block_type] + get_field_path_from_streamfield_block(
                                block_value, path_components[1:]
                            )
                        else:
                            return [block_type]

                    return [field_name] + get_field_path_from_streamfield_block(
                        field.value_from_object(instance), path_components[1:]
                    )

                elif (
                    isinstance(field, models.ManyToOneRel)
                    and isinstance(field.remote_field, ParentalKey)
                    and issubclass(field.related_model, TranslatableMixin)
                ):
                    manager = getattr(instance, field_name)
                    child_instance = manager.get(translation_key=path_components[1])
                    return [field_name] + get_field_path_from_field(
                        child_instance, path_components[2:]
                    )

                else:
                    return [field_name]

            self.field_path = ".".join(
                get_field_path_from_field(instance, self.path.split("."))
            )
            self.save(update_fields=["field_path"])

        return self.field_path

_get_path_id(path) classmethod

Generates a UUID from the given content path.

Parameters:

Name Type Description Default
path string

The content path to generate a hash of.

required

Returns:

Name Type Description
UUID

The UUID hash.

Source code in wagtail_localize/models.py
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
@classmethod
def _get_path_id(cls, path):
    """
    Generates a UUID from the given content path.

    Args:
        path (string): The content path to generate a hash of.

    Returns:
        UUID: The UUID hash.
    """
    return uuid.uuid5(uuid.UUID("fcab004a-2b50-11ea-978f-2e728ce88125"), path)

get_field_path(instance)

Gets the field path for this context

Field path's were introduced in version 1.0, any contexts that were created before that release won't have one.

Source code in wagtail_localize/models.py
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
def get_field_path(self, instance):
    """
    Gets the field path for this context

    Field path's were introduced in version 1.0, any contexts that were created before that release won't have one.
    """
    if not self.field_path:

        def get_field_path_from_field(instance, path_components):
            field_name = path_components[0]
            field = instance._meta.get_field(field_name)

            if isinstance(field, StreamField):

                def get_field_path_from_streamfield_block(value, path_components):
                    if isinstance(value, blocks.StructValue):
                        blocks_by_id = dict(value)
                    else:
                        if isinstance(value, ListValue):
                            blocks_by_id = {
                                block.id: block for block in value.bound_blocks
                            }
                        else:
                            blocks_by_id = {block.id: block for block in value}

                    block_id = path_components[0]
                    block = blocks_by_id[block_id]

                    if isinstance(value, blocks.StructValue):
                        block_type = block_id
                        block_def = value.block.child_blocks[block_type]
                        block_value = block
                    else:
                        if isinstance(value, ListValue):
                            block_type = "item"
                            block_def = value.list_block.child_block
                        else:
                            block_type = block.block_type
                            block_def = value.stream_block.child_blocks[block_type]
                        block_value = block.value

                    if isinstance(
                        block_def,
                        (blocks.StructBlock, blocks.StreamBlock, blocks.ListBlock),
                    ):
                        return [block_type] + get_field_path_from_streamfield_block(
                            block_value, path_components[1:]
                        )
                    else:
                        return [block_type]

                return [field_name] + get_field_path_from_streamfield_block(
                    field.value_from_object(instance), path_components[1:]
                )

            elif (
                isinstance(field, models.ManyToOneRel)
                and isinstance(field.remote_field, ParentalKey)
                and issubclass(field.related_model, TranslatableMixin)
            ):
                manager = getattr(instance, field_name)
                child_instance = manager.get(translation_key=path_components[1])
                return [field_name] + get_field_path_from_field(
                    child_instance, path_components[2:]
                )

            else:
                return [field_name]

        self.field_path = ".".join(
            get_field_path_from_field(instance, self.path.split("."))
        )
        self.save(update_fields=["field_path"])

    return self.field_path

Template

Bases: Model

A Template stores the structure of a RichTextField or RichTextBlock.

When a RichTextField/RichTextBlock is converted into segments, all translatable segments are stripped out of the block and stored as String instances. The remaining HTML is saved as a Template and is used for recombining the translated strings back into a rich text value.

Attributes:

Name Type Description
template TextField

The template value

uuid UUIDField

A hash of the template contents for efficient indexing.

template_format CharField

The format of the template (currently, only 'html' is supported).

string_count PositiveIntegerField

The number of translatable stirngs that were extracted from the template.

Source code in wagtail_localize/models.py
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
class Template(models.Model):
    """
    A Template stores the structure of a RichTextField or RichTextBlock.

    When a RichTextField/RichTextBlock is converted into segments, all translatable segments are stripped out of the
    block and stored as String instances. The remaining HTML is saved as a Template and is used for recombining the
    translated strings back into a rich text value.

    Attributes:
        template (TextField): The template value
        uuid (UUIDField): A hash of the template contents for efficient indexing.
        template_format (CharField): The format of the template (currently, only 'html' is supported).
        string_count (PositiveIntegerField): The number of translatable stirngs that were extracted from the template.
    """

    BASE_UUID_NAMESPACE = uuid.UUID("4599eabc-3f8e-41a9-be61-95417d26a8cd")

    uuid = models.UUIDField(unique=True)
    template = models.TextField()
    template_format = models.CharField(max_length=100)
    string_count = models.PositiveIntegerField()

    def __str__(self):
        return f"Template: {self.uuid}, {self.template_format}, {self.string_count}"

    @classmethod
    def from_value(cls, template_value):
        """
        Gets or creates a Template instance from a TemplateValue object.

        Args:
            template_value (TemplateValue): The value of the template.

        Returns:
            Template: The Template instance that corresponds with the given template_value.
        """
        uuid_namespace = uuid.uuid5(cls.BASE_UUID_NAMESPACE, template_value.format)

        template, created = cls.objects.get_or_create(
            uuid=uuid.uuid5(uuid_namespace, template_value.template),
            defaults={
                "template": template_value.template,
                "template_format": template_value.format,
                "string_count": template_value.string_count,
            },
        )

        return template

from_value(template_value) classmethod

Gets or creates a Template instance from a TemplateValue object.

Parameters:

Name Type Description Default
template_value TemplateValue

The value of the template.

required

Returns:

Name Type Description
Template

The Template instance that corresponds with the given template_value.

Source code in wagtail_localize/models.py
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
@classmethod
def from_value(cls, template_value):
    """
    Gets or creates a Template instance from a TemplateValue object.

    Args:
        template_value (TemplateValue): The value of the template.

    Returns:
        Template: The Template instance that corresponds with the given template_value.
    """
    uuid_namespace = uuid.uuid5(cls.BASE_UUID_NAMESPACE, template_value.format)

    template, created = cls.objects.get_or_create(
        uuid=uuid.uuid5(uuid_namespace, template_value.template),
        defaults={
            "template": template_value.template,
            "template_format": template_value.format,
            "string_count": template_value.string_count,
        },
    )

    return template

StringTranslation

Bases: Model

Represents a translation of a string.

Attributes:

Name Type Description
translation_of ForeignKey to String

The String that this is a translation of.

locale ForeignKey to Locale

The Locale of this translation.

context ForeignKey to TranslationContext

The context that this translation was made in. This allows different fields/pages to have different translations of the same source string.

data TextField

The translation.

translation_type CharField with choices 'manual' or 'machine'

Whether the translationw as performed by a human or machine.

tool_name CharField

The name of the tool that was used to make this translation.

last_translated_by ForeignKey to User

The user who last updated this translation.

created_at DateTimeField

The date/time that this translation was first created.

updated_at DateFimeField

The date/time that this translation was last updated.

has_error BooleanField

Set to True if the value of this translation has an error. We store translations 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. Note that this only makes sense if the context is not null.

Source code in wagtail_localize/models.py
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
class StringTranslation(models.Model):
    """
    Represents a translation of a string.

    Attributes:
        translation_of (ForeignKey to String): The String that this is a translation of.
        locale (ForeignKey to Locale): The Locale of this translation.
        context (ForeignKey to TranslationContext): The context that this translation was made in. This allows different
            fields/pages to have different translations of the same source string.
        data (TextField): The translation.
        translation_type (CharField with choices 'manual' or 'machine'): Whether the translationw as performed by a human or machine.
        tool_name (CharField): The name of the tool that was used to make this translation.
        last_translated_by (ForeignKey to User): The user who last updated this translation.
        created_at (DateTimeField): The date/time that this translation was first created.
        updated_at (DateFimeField): The date/time that this translation was last updated.
        has_error (BooleanField): Set to True if the value of this translation has an error. We store translations 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. Note that this only makes sense if the context is not null.
    """

    TRANSLATION_TYPE_MANUAL = "manual"
    TRANSLATION_TYPE_MACHINE = "machine"
    TRANSLATION_TYPE_CHOICES = [
        (TRANSLATION_TYPE_MANUAL, gettext_lazy("Manual")),
        (TRANSLATION_TYPE_MACHINE, gettext_lazy("Machine")),
    ]

    translation_of = models.ForeignKey(
        String, on_delete=models.CASCADE, related_name="translations"
    )
    locale = models.ForeignKey(
        "wagtailcore.Locale",
        on_delete=models.CASCADE,
        related_name="string_translations",
    )
    context = models.ForeignKey(
        TranslationContext,
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name="translations",
    )
    data = models.TextField()
    translation_type = models.CharField(max_length=20, choices=TRANSLATION_TYPE_CHOICES)
    tool_name = models.CharField(max_length=255, blank=True)
    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)

    has_error = models.BooleanField(default=False)
    field_error = models.TextField(blank=True)

    class Meta:
        unique_together = [("locale", "translation_of", "context")]

    def __str__(self):
        return f"StringTranslation: {self.translation_of_id}, {self.locale_id}, {self.context_id}, {self.translation_type}"

    def save(self, *args, **kwargs):
        update_fields = kwargs.get("update_fields")
        super().save(*args, **kwargs)

        # Set has_error if the string is invalid.
        # Since we allow translations to be made by external tools, we need to allow invalid
        # HTML in the database so that it can be fixed in Wagtail. However, we do want to know
        # if any strings are invalid so we don't use them on a page.
        updating_data = update_fields is None or "data" in update_fields
        if updating_data and not self.has_error:
            try:
                StringValue.from_translated_html(self.data)
                validate_translation_links(self.translation_of.data, self.data)
            except ValueError:
                self.has_error = True
                self.save(update_fields=["has_error"])

    @classmethod
    def from_text(cls, translation_of, locale, context, data):
        """
        Gets or creates a StringTranslation instance from the given parameters.

        Args:
            translation_of (ForeignKey to String): The String that this is a translation of.
            locale (ForeignKey to Locale): The Locale of this translation.
            context (ForeignKey to TranslationContext): The context that this translation was made in. This allows different
                fields/pages to have different translations of the same source string.
            data (TextField): The translation.

        Returns:
            String: The String instance that corresponds with the given stringvalue and locale.
        """
        segment, created = cls.objects.get_or_create(
            translation_of=translation_of,
            locale_id=pk(locale),
            context_id=pk(context),
            defaults={"data": data},
        )

        return segment

    def set_field_error(self, error):
        """
        This sets the `has_error`/`field_error` fields to the value of the given ValidationError instance.

        Note: If the given ValidationError contains multiple errors, only the first one is stored.

        Note: This updates the database instance as well.

        Args:
            error (ValidationError): The validation error to store.
        """
        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.
        """
        if not self.has_error:
            return

        # Check for HTML validation errors
        try:
            StringValue.from_translated_html(self.data)
            validate_translation_links(self.translation_of.data, self.data)
        except ValueError as e:
            return e.args[0]

        # Check if a database error was raised when we last attempted to publish
        if self.context is not None and self.field_error:
            return self.field_error

    def get_comment(self):
        """
        Returns a comment to display to the user containing info on how and when the string was translated.

        Returns:
            str: A comment to display to the user.
        """
        if self.tool_name:
            return _("Translated with {tool_name} on {date}").format(
                tool_name=self.tool_name, date=self.updated_at.strftime(DATE_FORMAT)
            )

        elif self.translation_type == self.TRANSLATION_TYPE_MANUAL:
            return _("Translated manually on {date}").format(
                date=self.updated_at.strftime(DATE_FORMAT)
            )

        elif self.translation_type == self.TRANSLATION_TYPE_MACHINE:
            return _("Machine translated on {date}").format(
                date=self.updated_at.strftime(DATE_FORMAT)
            )

from_text(translation_of, locale, context, data) classmethod

Gets or creates a StringTranslation instance from the given parameters.

Parameters:

Name Type Description Default
translation_of ForeignKey to String

The String that this is a translation of.

required
locale ForeignKey to Locale

The Locale of this translation.

required
context ForeignKey to TranslationContext

The context that this translation was made in. This allows different fields/pages to have different translations of the same source string.

required
data TextField

The translation.

required

Returns:

Name Type Description
String

The String instance that corresponds with the given stringvalue and locale.

Source code in wagtail_localize/models.py
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
@classmethod
def from_text(cls, translation_of, locale, context, data):
    """
    Gets or creates a StringTranslation instance from the given parameters.

    Args:
        translation_of (ForeignKey to String): The String that this is a translation of.
        locale (ForeignKey to Locale): The Locale of this translation.
        context (ForeignKey to TranslationContext): The context that this translation was made in. This allows different
            fields/pages to have different translations of the same source string.
        data (TextField): The translation.

    Returns:
        String: The String instance that corresponds with the given stringvalue and locale.
    """
    segment, created = cls.objects.get_or_create(
        translation_of=translation_of,
        locale_id=pk(locale),
        context_id=pk(context),
        defaults={"data": data},
    )

    return segment

get_comment()

Returns a comment to display to the user containing info on how and when the string was translated.

Returns:

Name Type Description
str

A comment to display to the user.

Source code in wagtail_localize/models.py
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
def get_comment(self):
    """
    Returns a comment to display to the user containing info on how and when the string was translated.

    Returns:
        str: A comment to display to the user.
    """
    if self.tool_name:
        return _("Translated with {tool_name} on {date}").format(
            tool_name=self.tool_name, date=self.updated_at.strftime(DATE_FORMAT)
        )

    elif self.translation_type == self.TRANSLATION_TYPE_MANUAL:
        return _("Translated manually on {date}").format(
            date=self.updated_at.strftime(DATE_FORMAT)
        )

    elif self.translation_type == self.TRANSLATION_TYPE_MACHINE:
        return _("Machine translated on {date}").format(
            date=self.updated_at.strftime(DATE_FORMAT)
        )

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
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
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.
    """
    if not self.has_error:
        return

    # Check for HTML validation errors
    try:
        StringValue.from_translated_html(self.data)
        validate_translation_links(self.translation_of.data, self.data)
    except ValueError as e:
        return e.args[0]

    # Check if a database error was raised when we last attempted to publish
    if self.context is not None and self.field_error:
        return self.field_error

set_field_error(error)

This sets the has_error/field_error fields to the value of the given ValidationError instance.

Note: If the given ValidationError contains multiple errors, only the first one is stored.

Note: This updates the database instance as well.

Parameters:

Name Type Description Default
error ValidationError

The validation error to store.

required
Source code in wagtail_localize/models.py
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
def set_field_error(self, error):
    """
    This sets the `has_error`/`field_error` fields to the value of the given ValidationError instance.

    Note: If the given ValidationError contains multiple errors, only the first one is stored.

    Note: This updates the database instance as well.

    Args:
        error (ValidationError): The validation error to store.
    """
    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"])