Skip to content

Translatable Fields

This module provides the classes used to configure translatable fields and a couple of related utility functions

BaseTranslatableField

Source code in wagtail_localize/fields.py
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
class BaseTranslatableField:
    def __init__(self, field_name):
        self.field_name = field_name

    def get_field(self, model):
        return model._meta.get_field(self.field_name)

    def get_value(self, obj):
        return self.get_field(obj.__class__).value_from_object(obj)

    def is_editable(self, obj):
        """
        Returns True if the field is editable on the given object
        """
        return True

    def is_translated(self, obj):
        """
        Returns True if the value of this field on the given object should be
        extracted and submitted for translation
        """
        return False

    def is_synchronized(self, obj):
        """
        Returns True if the value of this field on the given object should be
        copied when translations are created/updated
        """
        return False

    def is_overridable(self, obj):
        """
        Returns True if the value of this field can be overridden. This is only
        applicable to fields that are synchronized
        """
        return self.is_synchronized(obj)

    def __eq__(self, other):
        return self.__class__ == other.__class__ and self.field_name == other.field_name

is_editable(obj)

Returns True if the field is editable on the given object

Source code in wagtail_localize/fields.py
19
20
21
22
23
def is_editable(self, obj):
    """
    Returns True if the field is editable on the given object
    """
    return True

is_overridable(obj)

Returns True if the value of this field can be overridden. This is only applicable to fields that are synchronized

Source code in wagtail_localize/fields.py
39
40
41
42
43
44
def is_overridable(self, obj):
    """
    Returns True if the value of this field can be overridden. This is only
    applicable to fields that are synchronized
    """
    return self.is_synchronized(obj)

is_synchronized(obj)

Returns True if the value of this field on the given object should be copied when translations are created/updated

Source code in wagtail_localize/fields.py
32
33
34
35
36
37
def is_synchronized(self, obj):
    """
    Returns True if the value of this field on the given object should be
    copied when translations are created/updated
    """
    return False

is_translated(obj)

Returns True if the value of this field on the given object should be extracted and submitted for translation

Source code in wagtail_localize/fields.py
25
26
27
28
29
30
def is_translated(self, obj):
    """
    Returns True if the value of this field on the given object should be
    extracted and submitted for translation
    """
    return False

SynchronizedField

Bases: BaseTranslatableField

A field that should always be kept in sync with the original page.

Source code in wagtail_localize/fields.py
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
class SynchronizedField(BaseTranslatableField):
    """
    A field that should always be kept in sync with the original page.
    """

    def __init__(self, field_name, overridable=True):
        super().__init__(field_name)
        self.overridable = overridable

    def is_synchronized(self, obj):
        return self.is_editable(obj)

    def is_overridable(self, obj):
        return self.is_synchronized(obj) and self.overridable

    def __repr__(self):
        return f"<SynchronizedField {self.field_name}>"

TranslatableField

Bases: BaseTranslatableField

A field that should be translated whenever the original page changes

Source code in wagtail_localize/fields.py
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
class TranslatableField(BaseTranslatableField):
    """
    A field that should be translated whenever the original page changes
    """

    def is_translated(self, obj):
        return True

    def is_synchronized(self, source):
        field = self.get_field(source.__class__)

        # Child relations should all be synchronised before translation
        if isinstance(field, models.ManyToOneRel) and isinstance(
            field.remote_field, ParentalKey
        ):
            return True

        # We have a text field that has been cleared so we should mark it as synchronised
        if (
            isinstance(field, (RichTextField, models.TextField, models.CharField))
            and getattr(source, field.attname) == ""
        ):
            return True

        # Streamfields need to be re-synchronised before translation so
        # the structure and non-translatable content is copied over
        return isinstance(field, StreamField)

    def __repr__(self):
        return f"<TranslatableField {self.field_name}>"

copy_synchronised_fields(source, target)

Copies data in synchronised fields from the source instance to the target instance.

Note: Both instances must have the same model class

Parameters:

Name Type Description Default
source Model

The source instance to copy data from.

required
target Model

The target instance to copy data to.

required
Source code in wagtail_localize/fields.py
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
def copy_synchronised_fields(source, target):
    """
    Copies data in synchronised fields from the source instance to the target instance.

    Note: Both instances must have the same model class

    Arguments:
        source (Model): The source instance to copy data from.
        target (Model): The target instance to copy data to.
    """
    for translatable_field in get_translatable_fields(source.__class__):
        if translatable_field.is_synchronized(source):
            field = translatable_field.get_field(target.__class__)

            if isinstance(field, models.ManyToOneRel) and isinstance(
                field.remote_field, ParentalKey
            ):
                # Use modelcluster's copy_child_relation for child relations

                if issubclass(field.related_model, TranslatableMixin):
                    # Get a list of the primary keys for the existing child objects
                    existing_pks_by_translation_key = {
                        child_object.translation_key: child_object.pk
                        for child_object in getattr(target, field.name).all()
                    }

                    # Copy the new child objects across (note this replaces existing ones)
                    child_object_map = source.copy_child_relation(field.name, target)

                    # Update locale of each child object and recycle PK
                    for (
                        _child_relation,
                        source_pk,
                    ), child_objects in child_object_map.items():
                        if source_pk is None:
                            # This is a list of the child objects that were never saved
                            for child_object in child_objects:
                                child_object.pk = existing_pks_by_translation_key.get(
                                    child_object.translation_key
                                )
                                child_object.locale = target.locale
                        else:
                            child_object = child_objects

                            child_object.pk = existing_pks_by_translation_key.get(
                                child_object.translation_key
                            )
                            child_object.locale = target.locale

                else:
                    source.copy_child_relation(field.name, target)

            elif isinstance(field, ParentalManyToManyField):
                parental_field = getattr(source, field.name)
                if hasattr(parental_field, "all"):
                    values = parental_field.all()
                    if values:
                        setattr(target, field.attname, values)

            else:
                # For all other fields, just set the attribute
                setattr(target, field.attname, getattr(source, field.attname))

get_translatable_fields(model)

Derives a list of translatable fields from the given model class.

Parameters:

Name Type Description Default
model Model class

The model class to derive translatable fields from.

required

Returns:

Type Description

list[TranslatableField or SynchronizedField]: A list of TranslatableField and SynchronizedFields that were derived from the model.

Source code in wagtail_localize/fields.py
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
def get_translatable_fields(model):
    """
    Derives a list of translatable fields from the given model class.

    Arguments:
        model (Model class): The model class to derive translatable fields from.

    Returns:
        list[TranslatableField or SynchronizedField]: A list of TranslatableField and SynchronizedFields that were
            derived from the model.

    """
    # Note: If you update this, please update "docs/concept/translatable-fields-autogen.md"
    if hasattr(model, "translatable_fields"):
        return model.translatable_fields

    translatable_fields = []

    for field in model._meta.get_fields():
        # Ignore automatically generated IDs
        if isinstance(field, models.AutoField):
            continue

        # Ignore non-editable fields
        if not field.editable:
            continue

        # Ignore many to many fields (not supported yet)
        # TODO: Add support for these
        if isinstance(field, models.ManyToManyField):
            continue

        # Ignore fields defined by MP_Node mixin
        if issubclass(model, MP_Node) and field.name in ["path", "depth", "numchild"]:
            continue

        # Ignore some editable fields defined on Page
        if issubclass(model, Page) and field.name in [
            "go_live_at",
            "expire_at",
            "first_published_at",
            "content_type",
            "owner",
        ]:
            continue

        # URL, Email and choices fields are an exception to the rule below.
        # Text fields are translatable, but these are synchronised.
        if (
            isinstance(field, (models.URLField, models.EmailField))
            or isinstance(field, models.CharField)
            and field.choices
        ):
            translatable_fields.append(SynchronizedField(field.name))

        # Translatable text fields should be translatable
        elif isinstance(
            field, (StreamField, RichTextField, models.TextField, models.CharField)
        ):
            translatable_fields.append(TranslatableField(field.name))

        # Foreign keys to translatable models should be translated. Others should be synchronised
        elif isinstance(field, models.ForeignKey):
            # Ignore if this is a link to a parent model
            if isinstance(field, ParentalKey):
                continue

            # Ignore parent links
            if (
                isinstance(field, models.OneToOneField)
                and field.remote_field.parent_link
            ):
                continue

            # All FKs to translatable models should be translatable.
            # With the exception of pages that are special because we can localize them at runtime easily.
            # TODO: Perhaps we need a special type for pages where it links to the translation if availabe,
            # but falls back to the source if it isn't translated yet?
            # Note: This exact same decision was made for page chooser blocks in segments/extract.py
            if issubclass(field.related_model, TranslatableMixin) and not issubclass(
                field.related_model, Page
            ):
                translatable_fields.append(TranslatableField(field.name))
            else:
                translatable_fields.append(SynchronizedField(field.name))

        # Fields that support extracting segments are translatable
        elif hasattr(field, "get_translatable_segments"):
            translatable_fields.append(TranslatableField(field.name))

        else:
            # Everything else is synchronised
            translatable_fields.append(SynchronizedField(field.name))

    # Add child relations for clusterable models
    if issubclass(model, ClusterableModel):
        for child_relation in get_all_child_relations(model):
            # Ignore comments
            if (
                issubclass(model, Page)
                and child_relation.name == COMMENTS_RELATION_NAME
            ):
                continue

            if issubclass(child_relation.related_model, TranslatableMixin):
                translatable_fields.append(TranslatableField(child_relation.name))
            else:
                translatable_fields.append(SynchronizedField(child_relation.name))

    # Combine with any overrides defined on the model
    override_translatable_fields = getattr(model, "override_translatable_fields", [])

    if override_translatable_fields:
        override_translatable_fields = {
            field.field_name: field for field in override_translatable_fields
        }

        combined_translatable_fields = []
        for field in translatable_fields:
            if field.field_name in override_translatable_fields:
                combined_translatable_fields.append(
                    override_translatable_fields.pop(field.field_name)
                )
            else:
                combined_translatable_fields.append(field)

        if override_translatable_fields:
            combined_translatable_fields.extend(override_translatable_fields.values())

        return combined_translatable_fields

    else:
        return translatable_fields