##########
Quickstart
##########

***************************
Define a multilingual model
***************************

Defining a multilingual model is very similar to defining a normal Django model,
with the difference that instead of subclassing :class:`django.db.models.Model`
you have to subclass :class:`nani.models.TranslatableModel` and that all fields
which should be translatable have to be wrapped inside a 
:class:`nani.models.TranslatedFields`.

Let's write an easy model which describes Django applications with translatable
descriptions and information about who wrote the description::

    from django.db import models
    from nani.models import TranslatableModel, TranslatedFields
    
    
    class DjangoApplication(TranslatableModel):
        name = models.CharField(max_length=255, unique=True)
        author = models.CharField(max_length=255)
        
        translations = TranslatedFields(
            description = models.TextField(),
            description_author = models.CharField(max_length=255),
        )
        
        def __unicode__(self):
            return self.name

The fields ``name`` and ``author`` will not get translated, the fields
``description`` and ``description_author`` will.


*************************
Using multilingual models
*************************

Now that we have defined our model, let's play around with it a bit. The
following code examples are taken from a Python shell.

.. highlight:: pycon

Import our model::

    >>> from myapp.models import DjangoApplication

Create an **untranslated** instance::

    >>> nani = DjangoApplication.objects.create(name='django-nani', author='Jonas Obrist')
    >>> nani.name
    'django-nani'
    >>> nani.author
    'Jonas Obrist'

Turn the **untranslated** instance into a **translated** instance with the
language ``'en'`` (English)::

    >>> nani.translate('en')
    <DjangoApplication: django-nani>

Set some translated fields and save the instance::

    >>> nani.description = 'A project to do multilingual models in Django'
    >>> nani.description_author = 'Jonas Obrist'
    >>> nani.save()

Get the instance again and check that the fields are correct::

    >>> obj = DjangoApplication.objects.language('en').get(name='django-nani')
    >>> obj.name
    u'django-nani'
    >>> obj.author
    u'Jonas Obrist'
    >>> obj.description
    u'A project to do multilingual models in Django'
    >>> obj.description_author
    u'Jonas Obrist'

.. note:: I use :meth:`nani.manager.TranslationQueryset.language` here because
          I'm in an interactive shell, which is not necessarily in English, in
          your normal views, you can usually omit the call to that method, since
          the environment should already be in a valid language when in a
          request/response cycle.

Let's get all Django applications which have a description written by
``'Jonas Obrist'`` (in English)::

    >>> DjangoApplication.objects.language('en').filter(description_author='Jonas Obrist')
    [<DjangoApplication: django-nani>]