# Quick start guide

## Installing django-parler

The package can be installed using:

    pip install django-parler

Add the following settings:

    INSTALLED_APPS += (
        'parler',
    )

## A brief overview

### Creating models

Using the `TranslatedFields` wrapper, model fields can be marked as translatable:

    from django.db import models
    from parler.models import TranslatableModel, TranslatedFields

    class MyModel(TranslatableModel):
        translations = TranslatedFields(
            title = models.CharField(_("Title"), max_length=200)
        )

        def __unicode__(self):
            return self.title

### Accessing fields

Translatable fields can be used like regular fields:

    >>> object = MyModel.objects.all()[0]
    >>> object.get_current_language()
    'en'
    >>> object.title
    u'cheese omelet'

    >>> object.set_current_language('fr')       # Only switches
    >>> object.title = "omelette du fromage"    # Translation is created on demand.
    >>> object.save()

Internally, django-parler stores the translated fields in a separate model, with one row per language.

### Filtering translations

To query translated fields, use the `translated()` method:

    MyObject.objects.translated(title='cheese omelet')

To access objects in both the current and the configured fallback languages, use:

    MyObject.objects.active_translations(title='cheese omelet')

This returns objects in the languages which are considered “active”, which are:

- The current language

- The fallback languages when `hide_untranslated=False` in the PARLER_LANGUAGES setting.

Note

Due to ORM restrictions the query should be performed in a single `translated()` or `active_translations()` call.

The `active_translations()` method typically needs to include a `distinct()` call to avoid duplicate results of the same object.

### Changing the language

The queryset can be instructed to return objects in a specific language:

    >>> objects = MyModel.objects.language('fr').all()
    >>> objects[0].title
    u'omelette du fromage'

This only sets the language of the object. By default, the current Django language is used.

Use `get_current_language()` and `set_current_language()` to change the language on individual objects. There is a context manager to do this temporary:

    from parler.utils.context import switch_language

    with switch_language(model, 'fr'):
        print model.title

And a function to query just a specific field:

    model.safe_translation_getter('title', language_code='fr')

## Configuration

By default, the fallback languages are the same as: `[LANGUAGE_CODE]`. The fallback language can be changed in the settings:

    PARLER_DEFAULT_LANGUAGE_CODE = 'en'

Optionally, the admin tabs can be configured too:

    PARLER_LANGUAGES = {
        None: (
            {'code': 'en',},
            {'code': 'en-us',},
            {'code': 'it',},
            {'code': 'nl',},
        ),
        'default': {
            'fallbacks': ['en'],          # defaults to PARLER_DEFAULT_LANGUAGE_CODE
            'hide_untranslated': False,   # the default; let .active_translations() return fallbacks too.
        }
    }

Replace `None` with the :django:setting:`SITE_ID` when you run a multi-site project with the sites framework. Each :django:setting:`SITE_ID` can be added as additional entry in the dictionary.