mirror of
https://github.com/Hopiu/wagtail-modeltranslation.git
synced 2026-04-07 16:41:07 +00:00
103 lines
4.3 KiB
ReStructuredText
103 lines
4.3 KiB
ReStructuredText
|
|
Accessing translated fields
|
|
===========================
|
|
|
|
Modeltranslation changes the behaviour of the translated fields. To explain this consider the Foo
|
|
example from the :ref:`Registering Models` chapter again. The original ``Foo`` model:
|
|
|
|
.. code-block:: console
|
|
|
|
class FooModel(TranslationMixin, Page):
|
|
introduction = models.CharField(max_length=255)
|
|
body = RichtextField(blank=True)
|
|
|
|
Now that it is registered with wagtail-modeltranslation, the model looks like this - note the additional fields automatically added by the app:
|
|
|
|
.. code-block:: console
|
|
|
|
class FooModel(TranslationMixin, Page):
|
|
introduction = models.CharField(max_length=255) # original/translated field
|
|
introduction_pt = models.CharField(null=True, blank=True, max_length=255) # default translation field
|
|
introduction_es = models.CharField(null=True, blank=True, max_length=255) # translation field
|
|
introduction_fr = models.CharField(null=True, blank=True, max_length=255) # translation field
|
|
body = RichTextField(blank=True) # original/translated field
|
|
body_pt = RichTextField(null=True, blank=True) # default translation field
|
|
body_es = RichTextField(null=True, blank=True) # translation field
|
|
body_fr = RichTextField(null=True, blank=True) # translation field
|
|
|
|
The example above assumes that the default language is ``pt``, therefore the ``introduction_pt`` and ``body_pt`` fields are marked as the *default translation fields*. If the default language were ``fr``, then ``introduction_fr`` and ``body_fr`` would be the *default translation fields*.
|
|
|
|
.. warning::
|
|
|
|
The ``title`` field is inherited from the Page model; if you try to create a field called ``title`` in one of your ``models`` you will get a warning messaqe. You can include the ``title field`` in ``translation.py`` and in the ``content_panels`` since it is inherited.
|
|
|
|
.. code-block:: console
|
|
|
|
# Indicate fields to include in Wagtail admin panel(s)
|
|
FooModel.content_panels = [
|
|
FieldPanel('title', classname="full title"),
|
|
FieldPanel('introduction', classname="full"),
|
|
FieldPanel('body', classname="full"),
|
|
]
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
# translation.py
|
|
from .models import Foo
|
|
from wagtail_modeltranslation.translation import TranslationOptions
|
|
from wagtail_modeltranslation.decorators import register
|
|
|
|
@register(Foo)
|
|
class FooTR(TranslationOptions):
|
|
fields = (
|
|
'title',
|
|
'introduction',
|
|
'body',
|
|
)
|
|
|
|
.. _rules:
|
|
|
|
Rules for Translated Field Access
|
|
---------------------------------
|
|
|
|
The following rules apply to setting and getting the value of the original and the translation fields:
|
|
|
|
**Rule 1**
|
|
|
|
Reading the value from the original field returns the value translated to
|
|
the current language.
|
|
|
|
**Rule 2**
|
|
|
|
Assigning a value to the original field updates the value in the associated
|
|
current language translation field.
|
|
|
|
**Rule 3**
|
|
|
|
If both fields - the original and the current language translation field -
|
|
are updated at the same time, the current language translation field wins.
|
|
|
|
.. note:: This can only happen in the model's constructor or
|
|
``objects.create``. There is no other situation which can be considered
|
|
*changing several fields at the same time*.
|
|
|
|
|
|
Examples of translated field access
|
|
------------------------------------
|
|
|
|
Because the whole point of using the wagtail-modeltranslation app is translating dynamic content, the fields marked for
|
|
translation are somehow special when it comes to accessing them. The value returned by a translated field is depending on
|
|
the current language setting. **Language setting** refers to the Django ``set_language`` view and the corresponding ``get_lang``
|
|
function.
|
|
|
|
Assuming the current language is ``pt`` in the Foo example above, the translated ``introduction`` field will return the value from the ``introduction_pt`` field::
|
|
|
|
# Assuming the current language is "pt"
|
|
n = News.objects.all()[0]
|
|
t = n.introduction # returns the Portuguese translation
|
|
|
|
# Assuming the current language is "pt"
|
|
t = n.introduction # returns the Portuguese translation
|
|
|
|
This feature is implemented using Python descriptors making it happen without the need to touch the original model classes in any way. The descriptor uses the ``django.utils.i18n.get_language`` function to determine the current language.
|