Reference: QuerySets

This module contains the querysets for the Translations app.

Important

The examples are assumed to CRUD this dataset.

Type\Lang	English	German
Continent	Europe	Europa
	Asia	Asien
Country	Germany	Deutschland
	South Korea	Südkorea
City	Cologne	Köln
	Seoul	Seul

Please memorize this dataset in order to understand the examples better.

class translations.querysets.TranslatableQuerySet

A queryset which provides custom translation functionalities.

Provides functionalities like translate() and translate_related() to translate the TranslatableQuerySet and the relations of it and also some other functionalities like probe(), filter() and exclude() to query the TranslatableQuerySet.

To use TranslatableQuerySet:

from sample.models import Continent

continents = Continent.objects.all(
).distinct(           # familiar distinct
).probe(['en', 'de']  # probe (filter, exclude, etc.) in English and German
).filter(             # familiar filtering
    countries__cities__name__startswith='Köln'
).translate('de'      # translate the results in German
).translate_related(  # translate these relations as well
    'countries', 'countries__cities',
)

print(continents)
print(continents[0].countries.all())
print(continents[0].countries.all()[0].cities.all())

<TranslatableQuerySet [
    <Continent: Europa>,
]>
<TranslatableQuerySet [
    <Country: Deutschland>,
]>
<TranslatableQuerySet [
    <City: Köln>,
]>

__init__(*args, **kwargs)

Initialize a TranslatableQuerySet with QuerySet arguments.

This is an overriden version of the QuerySet‘s __init__() method. It defines custom translation configurations on the TranslatableQuerySet.

Parameters:

• args (list) – The arguments of the QuerySet‘s __init__() method.

• kwargs (dict) – The keyword arguments of the QuerySet‘s __init__() method.

To initialize a TranslatableQuerySet:

from sample.models import Continent

# initialize queryset
continents = Continent.objects.all()

print(continents)

<TranslatableQuerySet [
    <Continent: Asia>,
    <Continent: Europe>,
]>

_chain(**kwargs)

Return a copy of the current TranslatableQuerySet.

This is an overriden version of the QuerySet‘s _chain() method. It copies the custom translation configurations from the current TranslatableQuerySet to the copied TranslatableQuerySet.

Parameters:

kwargs (dict) – The keyword arguments of the QuerySet‘s _chain() method.

Returns:

The copy of the current TranslatableQuerySet.

Return type:

TranslatableQuerySet

To get a copy of the current TranslatableQuerySet:

from sample.models import Continent

# chain the queryset
continents = Continent.objects.all()._chain()

print(continents)

<TranslatableQuerySet [
    <Continent: Asia>,
    <Continent: Europe>,
]>

_fetch_all()

Evaluate the TranslatableQuerySet.

This is an overriden version of the QuerySet‘s _fetch_all() method. It translates the TranslatableQuerySet and some relations of it (specified using the translate_related() method) in a language (specified using the translate() method).

To evaluate the TranslatableQuerySet (using the default language):

from sample.models import Continent

continents = Continent.objects.all()

# evaluate the queryset
print(continents)

<TranslatableQuerySet [
    <Continent: Asia>,
    <Continent: Europe>,
]>

To evaluate the TranslatableQuerySet (using a custom language):

from sample.models import Continent

continents = Continent.objects.translate('de')

# evaluate the queryset
print(continents)

<TranslatableQuerySet [
    <Continent: Asien>,
    <Continent: Europa>,
]>

translate(lang=None)

Translate the TranslatableQuerySet in a language.

Causes the TranslatableQuerySet to be translated in the specified language in the evaluation.

Parameters:

lang (str or None) – The language to translate the TranslatableQuerySet in. None means use the active language code.

Returns:

The TranslatableQuerySet which will be translated in the specified language.

Return type:

TranslatableQuerySet

Raises:

ValueError – If the language code is not included in the LANGUAGES setting.

To translate the TranslatableQuerySet (an instance) in a language:

from sample.models import Continent

# translate the instance
europe = Continent.objects.translate('de').get(code='EU')

print(europe)

Europa

To translate the TranslatableQuerySet (a queryset) in a language:

from sample.models import Continent

# translate the queryset
continents = Continent.objects.translate('de').all()

print(continents)

<TranslatableQuerySet [
    <Continent: Asien>,
    <Continent: Europa>,
]>

Note

Translating only affects the TranslatableMeta.fields that have a translation.

translate_related(*fields)

Translate some TranslatableQuerySet relations.

Causes the TranslatableQuerySet relations to be translated in the evaluation.

Parameters:

relations (list(str)) – The TranslatableQuerySet relations to translate. Each relation may be divided into separate parts by LOOKUP_SEP (usually __) to represent a deeply nested relation. Each part must be a related_name.

Returns:

The TranslatableQuerySet which the relations of will be translated.

Return type:

TranslatableQuerySet

Raises:

TypeError – If the models of the relations are not Translatable.

To translate some TranslatableQuerySet relations:

from sample.models import Continent

# translate the queryset relations
continents = Continent.objects.translate_related(
    'countries',
    'countries__cities',
).translate('de')

print(continents)
print(continents[0].countries.all())
print(continents[0].countries.all()[0].cities.all())

<TranslatableQuerySet [
    <Continent: Asien>,
    <Continent: Europa>,
]>
<TranslatableQuerySet [
    <Country: Deutschland>,
]>
<TranslatableQuerySet [
    <City: Köln>,
]>

Note

It is recommended for the queryset relations to be prefetched before translating them, in order to reach optimal performance.

To do this use select_related(), prefetch_related() or prefetch_related_objects().

Warning

Any subsequent chained methods on the relations queryset which imply a database query will reset previously translated results:

from sample.models import Continent

continents = Continent.objects.translate_related(
    'countries',
).translate('de')

# Querying after translation
print(continents[0].countries.exclude(name=''))

<TranslatableQuerySet [
    <Country: Germany>,
]>

In some cases the querying can be done before the translation:

from django.db.models import Prefetch
from sample.models import Continent, Country

# Querying before translation
continents = Continent.objects.prefetch_related(
    Prefetch(
        'countries',
        queryset=Country.objects.exclude(name=''),
    ),
).translate_related(
    'countries',
).translate('de')

print(continents[0].countries.all())

<TranslatableQuerySet [
    <Country: Deutschland>,
]>

And in some cases the querying must be done anyway, in these cases:

from sample.models import Continent

continents = Continent.objects.translate_related(
    'countries',
).translate('de')

# Just `translate` the relation again after querying
print(continents[0].countries.exclude(name='').translate('de'))

<TranslatableQuerySet [
    <Country: Deutschland>,
]>

probe(lang=None)

Probe the TranslatableQuerySet in some language(s).

Causes the TranslatableQuerySet to be probed in the specified language(s) in the evaluation.

Parameters:

lang (str or list or None) – The language(s) to probe the TranslatableQuerySet in. None means use the active language code.

Returns:

The TranslatableQuerySet which will be probed in the specified language(s).

Return type:

TranslatableQuerySet

Raises:

ValueError – If the language code is not included in the LANGUAGES setting.

To probe the TranslatableQuerySet in some language(s) (a custom language):

from django.db.models import Q
from sample.models import Continent

# probe the queryset
continents = Continent.objects.probe('de').filter(
    Q(name='Europa') | Q(name='Asien'))

print(continents)

<TranslatableQuerySet [
    <Continent: Asia>,
    <Continent: Europe>,
]>

To probe the TranslatableQuerySet in some language(s) (multiple custom languages):

from django.db.models import Q
from sample.models import Continent

# probe the queryset
continents = Continent.objects.probe(['en', 'de']).filter(
    Q(name='Europa') | Q(name='Asien')).distinct()

print(continents)

<TranslatableQuerySet [
    <Continent: Asia>,
    <Continent: Europe>,
]>

Note

Probing only affects the TranslatableMeta.fields that have a translation.

Note

Make sure to use distinct() on the probed queryset when using multiple languages, otherwise it may return duplicate results.

filter(*args, **kwargs)

Filter the TranslatableQuerySet.

This is an overriden version of the QuerySet‘s filter() method. It filters the TranslatableQuerySet in the probe language(s).

Parameters:

• args (list) – The arguments of the QuerySet‘s filter() method.

• kwargs (dict) – The keyword arguments of the QuerySet‘s filter() method.

To filter the TranslatableQuerySet (using the default language):

from sample.models import Continent

# filter the queryset
continents = Continent.objects.filter(
    countries__name__icontains='Ger')

print(continents)

<TranslatableQuerySet [
    <Continent: Europe>,
]>

To filter the TranslatableQuerySet (using a custom language):

from sample.models import Continent

# filter the queryset
continents = Continent.objects.probe('de').filter(
    countries__name__icontains='Deutsch')

print(continents)

<TranslatableQuerySet [
    <Continent: Europe>,
]>

To filter the TranslatableQuerySet (using multiple custom languages):

from sample.models import Continent

# filter the queryset
continents = Continent.objects.probe(['en', 'de']).filter(
    countries__name__icontains='Deutsch').distinct()

print(continents)

<TranslatableQuerySet [
    <Continent: Europe>,
]>

exclude(*args, **kwargs)

Exclude the TranslatableQuerySet.

This is an overriden version of the QuerySet‘s exclude() method. It excludes the TranslatableQuerySet in the probe language(s).

Parameters:

• args (list) – The arguments of the QuerySet‘s exclude() method.

• kwargs (dict) – The keyword arguments of the QuerySet‘s exclude() method.

To exclude the TranslatableQuerySet (using the default language):

from sample.models import Continent

# exclude the queryset
continents = Continent.objects.exclude(
    countries__name__icontains='Ger')

print(continents)

<TranslatableQuerySet [
    <Continent: Asia>,
]>

To exclude the TranslatableQuerySet (using a custom language):

from sample.models import Continent

# exclude the queryset
continents = Continent.objects.probe('de').exclude(
    countries__name__icontains='Deutsch')

print(continents)

<TranslatableQuerySet [
    <Continent: Asia>,
]>

To exclude the TranslatableQuerySet (using multiple custom languages):

from sample.models import Continent

# exclude the queryset
continents = Continent.objects.probe(['en', 'de']).exclude(
    countries__name__icontains='Deutsch').distinct()

print(continents)

<TranslatableQuerySet [
    <Continent: Asia>,
]>