<commit_before>Linguo
======


Overview
--------
Linguo is a Django application that provides the ability to have multilingual models (ie. translatable fields on models). This means that you can have fields on a model with different values for different languages (similar to ugettext, but for models).

It does this by creating additional columns for each language and using accessors to make it transparent to you.

For example:
::

    product.name
    -> 'Foo'

    # If you switch languages, you get the translated value for the field:
    translation.activate('fr')

    product.name
    -> 'French Foo'


Features
~~~~~~~~
* Automatically retrieves translated values in the current active language.
* Supports filtering and ordering on translatable fields.
* Can support ModelForms for translatable models that automatically save values to the active language.
* Supports Django versions 1.2 to 1.4
* Comprehensive test coverage


Usage
-----

Subclass ``MultilingualModel`` and specify the fields to be translated in the ``Meta`` class ``translate`` property:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::

    from linguo.models import MultilingualModel
    from linguo.managers import MultilingualManager

    class Product(MultilingualModel):
        name = models.CharField(max_length=255, verbose_name=_('name'))
        description = models.TextField(verbose_name=_('description'))
        price = models.FloatField(verbose_name=_('price'))

        objects = MultilingualManager()

        class Meta:
            # name and description are translatable fields
            translate = ('name', 'description')

``MultilingualManager`` allows you to transparently perform filtering and ordering on translatable fields (more on this below).


Assuming your ``LANGUAGES`` settings looks like this ...
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::

    LANGUAGES = (
        ('en', ugettext('English')),
        ('fr', ugettext('French')),
    )


Then, you can do this:
~~~~~~~~~~~~~~~~~~~~~~

**Create a product:** It automatically sets the values for the current active language.
::

    translation.activate('en')
    product = Product.objects.create(
        name='English Name',
        description='English description',
        price=10
    )


**Translate the fields** on that product.
::

    product.translate(language='fr',
        name='French Name', description='French description'
    )
    product.save()
    # You don't have to specify price, because it is not a translatable field


If you **switch languages**, it will automatically retrieve the corresponding translated values.
::

    translation.activate('fr')

    product.name
    -> 'French Name'

    product.description
    -> 'French description'


If you **modify translatable fields**, it will automatically assign it to current active language.
::

    translation.activate('fr')

    product.name = 'New French Name'
    product.save()

    translation.activate('en')

    product.name  # This remains untouched in English
    -> 'English Name'


Non-translated fields will have the same value regardless of the language we are operating in.
::

    translation.activate('en')
    product.price = 99
    product.save()

    translation.activate('fr')
    product.price
    -> 99


Querying the database
~~~~~~~~~~~~~~~~~~~~~

**Filtering and ordering** works as you would expect it to. It will filter/order in the language you are operating in. You need to use ``MultilingualManager`` on the model in order for this feature to work.
::

    translation.activate('fr')
    Product.objects.filter(name='French Name').order_by('name')


Model Forms for Multilingual models
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Model Forms work transparently in the sense that it automatically saves the form data to the current active language.

But by default, a Model Form for a Multlingual model will contains **all** the fields for **every language** (eg. ``name``, ``name_fr``, etc.). Typically this is not what you want. You just need to specify the ``fields`` attribute so that it doesn't generate separate fields for each language.
::

    class ProductForm(forms.ModelForm):
        class Meta:
            fields = ('name', 'description', 'price',)
            model = Product

<commit_msg>Updated README with 1.3.0 change warning<commit_after>Linguo
======

**NOTE:** Version 1.3.0 changes the way translations are created/retrieved to make it more in line with Django's i18n framework (and ugettext). Please re-read the usage instructions below.


Overview
--------
Linguo is a Django application that provides the ability to have multilingual models (ie. translatable fields on models). This means that you can have fields on a model with different values for different languages (similar to ugettext, but for models).

It does this by creating additional columns for each language and using accessors to make it transparent to you.

For example:
::

    product.name
    -> 'Foo'

    # If you switch languages, you get the translated value for the field:
    translation.activate('fr')

    product.name
    -> 'French Foo'


Features
~~~~~~~~
* Automatically retrieves translated values in the current active language.
* Supports filtering and ordering on translatable fields.
* Can support ModelForms for translatable models that automatically save values to the active language.
* Supports Django versions 1.2 to 1.4
* Comprehensive test coverage


Usage
-----

Subclass ``MultilingualModel`` and specify the fields to be translated in the ``Meta`` class ``translate`` property:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::

    from linguo.models import MultilingualModel
    from linguo.managers import MultilingualManager

    class Product(MultilingualModel):
        name = models.CharField(max_length=255, verbose_name=_('name'))
        description = models.TextField(verbose_name=_('description'))
        price = models.FloatField(verbose_name=_('price'))

        objects = MultilingualManager()

        class Meta:
            # name and description are translatable fields
            translate = ('name', 'description')

``MultilingualManager`` allows you to transparently perform filtering and ordering on translatable fields (more on this below).


Assuming your ``LANGUAGES`` settings looks like this ...
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::

    LANGUAGES = (
        ('en', ugettext('English')),
        ('fr', ugettext('French')),
    )


Then, you can do this:
~~~~~~~~~~~~~~~~~~~~~~

**Create a product:** It automatically sets the values for the current active language.
::

    translation.activate('en')
    product = Product.objects.create(
        name='English Name',
        description='English description',
        price=10
    )


**Translate the fields** on that product.
::

    product.translate(language='fr',
        name='French Name', description='French description'
    )
    product.save()
    # You don't have to specify price, because it is not a translatable field


If you **switch languages**, it will automatically retrieve the corresponding translated values.
::

    translation.activate('fr')

    product.name
    -> 'French Name'

    product.description
    -> 'French description'


If you **modify translatable fields**, it will automatically assign it to current active language.
::

    translation.activate('fr')

    product.name = 'New French Name'
    product.save()

    translation.activate('en')

    product.name  # This remains untouched in English
    -> 'English Name'


Non-translated fields will have the same value regardless of the language we are operating in.
::

    translation.activate('en')
    product.price = 99
    product.save()

    translation.activate('fr')
    product.price
    -> 99


Querying the database
~~~~~~~~~~~~~~~~~~~~~

**Filtering and ordering** works as you would expect it to. It will filter/order in the language you are operating in. You need to use ``MultilingualManager`` on the model in order for this feature to work.
::

    translation.activate('fr')
    Product.objects.filter(name='French Name').order_by('name')


Model Forms for Multilingual models
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Model Forms work transparently in the sense that it automatically saves the form data to the current active language.

But by default, a Model Form for a Multlingual model will contain **all** the fields for **every language** (eg. ``name``, ``name_fr``, etc.). Typically this is not what you want. You just need to specify the ``fields`` attribute so that it doesn't generate separate fields for each language.
::

    class ProductForm(forms.ModelForm):
        class Meta:
            fields = ('name', 'description', 'price',)
            model = Product


{'fraction_non_alphanumeric': 0.14391226499552373, 'fraction_numerical': 0.0038048343777976725, 'mean_word_length': 3.7689434364994665, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1237616', 'n_tokens_mistral': 2291, 'n_tokens_neox': 2095, 'n_words': 908}