django-modeltranslation

You can use class inheritance to share translatable fields across multiple models, which is particularly useful when working with abstract base classes.

• Abstract Base Classes: A subclass of TranslationOptions will inherit all fields from its parents. For example, if BaseOptions has fields = ('title', 'text'), then ChildOptions(BaseOptions) with fields = ('image',) will result in fields == ('title', 'text', 'image').
• Non-Abstract Base Classes: If the base class is not abstract (i.e., it is already registered to a model), inheriting from it will not merge fields for the child model. Instead, you should define separate TranslationOptions classes for each model to avoid errors and ensure fields are added correctly to each specific model.

from modeltranslation.translator import translator, TranslationOptions
from news.models import News, NewsWithImage

class AbstractNewsTranslationOptions(TranslationOptions):
    fields = ('title', 'text',)

class NewsWithImageTranslationOptions(AbstractNewsTranslationOptions):
    fields = ('image',)

translator.register(News, NewsTranslationOptions)
translator.register(NewsWithImage, NewsWithImageTranslationOptions)

# NewsWithImageTranslationOptions.fields will be ('title', 'text', 'image')

When a model is registered with modeltranslation, the original fields (e.g., title) become 'translated fields' that act as proxies for the language-specific fields (e.g., title_en, title_de).

Access Rules:

1. Reading: Accessing the original field returns the value for the current active language (determined by Django's get_language()).
2. Writing: Assigning a value to the original field updates the corresponding language-specific field for the current language.
3. Conflict Resolution: If both the original field and the current language translation field are updated simultaneously (only possible during create() or in the model constructor), the current language translation field takes precedence.

Example Model Structure: If the default language is de, a registered News model will automatically have these fields:

• title: The original/translated field.
• title_de: The default translation field.
• title_en: The English translation field.

By default, all translation fields added to a model definition are nullable (null=True), regardless of the original field's nullability.

Because Django's default CharField formfield often saves empty values as empty strings ('') instead of None, django-modeltranslation patches these fields. The default behavior is:

• If the original field is not nullable: empty values are saved as ''.
• If the original field is nullable: empty values are saved as None.

You can override this behavior using the empty_values attribute in your TranslationOptions class. This is critical for fields with unique=True constraints, where multiple empty strings would cause a database error, but multiple None values would be allowed.

Valid values for empty_values entries:

• None: Saves None for empty inputs.
• '': Saves an empty string '' for empty inputs.
• 'both': Uses a special widget with a None-checkbox to allow storing both empty strings and None values.

class CategoryTranslationOptions(TranslationOptions):
    fields = ('name', 'slug')
    # Use None for slug to avoid unique constraint errors with empty strings
    empty_values = {'slug': None}

When a model is registered for translation, modeltranslation automatically adds translation fields to the model class. These fields are not explicitly declared in your models.py but are injected at runtime.

Field Naming Convention: The new fields are named by taking the original field name and appending the language identifier (e.g., title becomes title_de for German and title_en for English, based on your settings.LANGUAGES).

Database Schema Example: If you have a model with title and text, the resulting SQL table will include:

• title (original)
• title_de (German translation)
• title_en (English translation)
• text (original)
• text_de (German translation)
• text_en (English translation)

Important Note on Field Requirements: All added translation fields are automatically set to blank=True and null=True, regardless of whether the original field was required. This makes translations optional by default.

To separate translation fields into UI tabs using jQuery UI, you can use the specialized admin classes provided by modeltranslation. This is easier than manually configuring the Media class with specific JS/CSS files.

Option 1: Using Django's built-in jQuery

Use TabbedTranslationAdmin (an alias for TabbedDjangoJqueryTranslationAdmin). This is recommended if you want to stick to the jQuery library shipped with Django.

from modeltranslation.admin import TabbedTranslationAdmin

class NewsAdmin(TabbedTranslationAdmin):
    pass

Option 2: Using an external/newer jQuery version

If you need a specific version of jQuery (e.g., 1.9.1), you must manually configure the Media class in your TranslationAdmin subclass:

from modeltranslation.admin import TranslationAdmin

class NewsAdmin(TranslationAdmin):
    class Media:
        js = (
            '//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js',
            '//ajax.googleapis.com/ajax/libs/jqueryui/1.10.2/jquery-ui.min.js',
            'modeltranslation/js/tabbed_translation_fields.js',
        )
        css = {
            'screen': ('modeltranslation/css/tabbed_translation_fields.css',),
        }