mirror of
https://github.com/Hopiu/django-modeltranslation.git
synced 2026-04-14 10:20:58 +00:00
127 lines
4.4 KiB
ReStructuredText
127 lines
4.4 KiB
ReStructuredText
.. _usage:
|
|
|
|
Accessing Translated and Translation Fields
|
|
===========================================
|
|
|
|
The modeltranslation app changes the behaviour of the translated fields. To
|
|
explain this consider the news example from the :ref:`registration` chapter
|
|
again. The original ``News`` model looked like this:
|
|
|
|
.. code-block:: python
|
|
|
|
class News(models.Model):
|
|
title = models.CharField(max_length=255)
|
|
text = models.TextField()
|
|
|
|
Now that it is registered with the modeltranslation app the model looks
|
|
like this - note the additional fields automatically added by the app:
|
|
|
|
.. code-block:: python
|
|
|
|
class News(models.Model):
|
|
title = models.CharField(max_length=255) # original/translated field
|
|
title_de = models.CharField(null=True, blank=True, max_length=255) # default translation field
|
|
title_en = models.CharField(null=True, blank=True, max_length=255) # translation field
|
|
text = models.TextField() # original/translated field
|
|
text_de = models.TextField(null=True, blank=True) # default translation field
|
|
text_en = models.TextField(null=True, blank=True) # translation field
|
|
|
|
The example above assumes that the default language is ``de``, therefore the
|
|
``title_de`` and ``text_de`` fields are marked as the *default translation
|
|
fields*. If the default language is ``en``, the ``title_en`` and ``text_en``
|
|
fields would be the *default translation fields*.
|
|
|
|
.. _rules:
|
|
|
|
Rules for Translated Field Access
|
|
---------------------------------
|
|
|
|
.. versionchanged:: 0.5
|
|
|
|
So now when it comes to setting and getting the value of the original and the
|
|
translation fields the following rules apply:
|
|
|
|
**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 for Translated Field Access
|
|
------------------------------------
|
|
|
|
Because the whole point of using the 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" is referring to the Django
|
|
`set_language`_ view and the corresponding ``get_lang`` function.
|
|
|
|
Assuming the current language is ``de`` in the news example from above, the
|
|
translated ``title`` field will return the value from the ``title_de`` field:
|
|
|
|
.. code-block:: python
|
|
|
|
# Assuming the current language is "de"
|
|
n = News.objects.all()[0]
|
|
t = n.title # returns german translation
|
|
|
|
# Assuming the current language is "en"
|
|
t = n.title # returns english 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.
|
|
|
|
.. todo:: Add more examples.
|
|
|
|
|
|
.. _multilingual_manager:
|
|
|
|
Multilingual Manager
|
|
--------------------
|
|
|
|
.. versionadded:: 0.5
|
|
|
|
.. todo:: Write something smart.
|
|
|
|
|
|
The State of the Original Field
|
|
-------------------------------
|
|
|
|
.. versionchanged:: 0.5
|
|
|
|
As defined by the :ref:`rules`, accessing the original field is guaranteed to
|
|
work on the associated translation field of the current language. This applies
|
|
to both, read and write operations.
|
|
|
|
The actual field value (which *can* still be accessed through
|
|
``instance.__dict__['original_field_name']``) however has to be considered
|
|
**undetermined** once the field has been registered for translation.
|
|
Attempts to keep the value in sync with either the default or current
|
|
language's field value has raised a boatload of unpredictable side effects in
|
|
older versions of modeltranslation.
|
|
|
|
.. warning::
|
|
Do not rely on the underlying value of the *original field* in any way!
|
|
|
|
.. todo::
|
|
Perhaps outline effects this might have on the ``update_translation_field``
|
|
management command.
|
|
|
|
|
|
.. _set_language: https://docs.djangoproject.com/en/dev/topics/i18n/translation/#set-language-redirect-view
|