99 A special value used with :meth: `~hvad.models.TranslatableModel.__init__ `
1010 to prevent automatic creation of a translation.
1111
12- .. function :: create_translations_model(model, related_name, meta, **fields)
13-
14- A model factory used to create the :term: `Translations Model `. Makes sure
15- that the *unique_together * option on the options (meta) contain
16- ``('language_code', 'master') `` as they always have to be unique together.
17- Sets the ``master `` foreign key to *model * onto the
18- :term: `Translations Model ` as well as the ``language_code `` field, which is
19- a database indexed char field with a maximum of 15 characters.
20-
21- Returns the new model.
22-
23- .. function :: contribute_translations(cls, rel)
24-
25- Gets called from :func: `prepare_translatable_model ` to set the
26- descriptors of the fields on the :term: `Translations Model ` onto the
27- model.
28-
2912.. function :: prepare_translatable_model(sender)
30-
31- Gets called from :class: ` ~django.db.models.Model `'s metaclass to
32- customize model creation. Performs checks, then contributes translations
33- and translation manager onto models that inherit
13+ Gets called from :class: ` ~django.db.models.Model ` after Django has
14+ completed its setup. It customizes model creation for translations.
15+ Most notably, it performs checks, overrides `` _meta `` methods and defines
16+ translation-aware manager on models that inherit
3417 :class: `~hvad.models.TranslatableModel `.
3518
3619****************
@@ -41,15 +24,64 @@ TranslatedFields
4124
4225 A wrapper for the translated fields which is set onto
4326 :class: `TranslatableModel ` subclasses to define what fields are translated.
44-
45- Internally this is just used because Django calls the
46- :meth: `contribute_to_class ` method on all attributes of a model, if such a
47- method is available.
4827
4928 .. method :: contribute_to_class(self, cls, name)
5029
51- Calls :func: `create_translations_model `.
30+ Invoked by Django while setting up a model that defines translated fields.
31+ Django passes is the model being built as ``cls `` and the field name
32+ used for translated fields as ``name ``.
33+
34+ It triggers translations model creation from the list of field the
35+ ``TranslatedFields `` object was created with, and glues the shared
36+ model and the translations model together.
37+
38+ .. method :: create_translations_model(self, model, related_name)
39+
40+ A model factory used to create the :term: `Translations Model ` for the
41+ given shared ``model ``. The translations model will include:
42+
43+ * A foreign key back to the shared model, named ``master ``, with the
44+ given ``related_name ``.
45+ * A ``language_code `` field, indexed together with ``master ``, for
46+ looking up a shared model instance's translations.
47+ * All fields passed to ``TranslatedFields `` object.
48+
49+ Adds the new model to the shared model's module and returns it.
50+
51+ .. method :: contribute_translations(self, model, translations_model, related_name)
52+
53+ Glues the shared ``model `` and the ``translations_model `` together.
54+ This step includes setting up attribute descriptors for all translatable
55+ fields onto the shared ``model ``.
56+
57+ .. method :: _scan_model_bases(self, model)
58+
59+ Recursively walks all ``model ``'s base classes, looking for translation
60+ models and collecting translatable fields. Used to build the inheritance
61+ tree of a :term: `Translations Model `.
62+
63+ Returns the list of bases and the list of fields.
64+
65+ .. method :: _build_meta_class(self, model, tfields)
66+
67+ Creates the :djterm: `Meta <meta-options> ` class for the
68+ :term: `Translations Model ` passed as ``model ``. Takes ``tfields `` as a
69+ list of all fields names referring to translatable fields.
70+
71+ Returns the created meta class.
72+
73+ .. staticmethod :: _split_together(constraints, fields, name)
74+
75+ Helper method that partitions constraint tuples into shared-model
76+ constraints and translations model constraints. Argument ``constraints ``
77+ is an iterable of contrain tuples, ``fields `` is the list of translated
78+ field names and ``name `` is the name of the option being handled (used
79+ for raising exceptions).
5280
81+ Returns two list of constraints. First for shared model, second for
82+ translations model. Raises an
83+ :exc: `~django.core.exceptions.ImproperlyConfigured ` exception if a
84+ constraint has both translated and untranslated fields.
5385
5486********************
5587BaseTranslationModel
0 commit comments