This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

Update: Version 1.4.0 adds support for Django 1.6 and 1.7 and drops support for Django < 1.4

Linguo

Linguo aims to make model translation easy. It is designed to let you use the built-in Django features (Query API, Model Forms, Admin, etc) as intended. Linguo integrates relatively easily with your existing code and performs the translation retrieval logic transparently (similar to ugettext). It does this by creating additional columns for each language and using proxy properties to make it transparent to you.

Features

  • Automatically references the correct translation based on the current active language.
  • Lets you use the Django ORM normally (no need to worry about which fields are translatable, linguo figures it out for you).
  • Support ModelForms by automatically retrieving/saving values based on the active language.
  • Supports Django versions 1.4.9 to 1.7.1
  • Comprehensive test coverage

Usage

Subclass MultilingualModel and define the 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.

from django.utils import translation  # import the translation package

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 have 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. However, if you want to edit multiple languages at the same time (eg. name, name_fr, etc.) see section below on ‘Admin Model Forms’.

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

When saving the form, it will automatically save the form data to the fields in the current active language.

translation.activate('fr') # Activate French

data = {'name': 'French Name', 'description': 'French Description', 'price': 37}
form = ProductForm(data=data)

new_product = form.save()

new_product.name
-> 'French Name'

new_product.description
-> 'French Description'

new_product.price
-> 37.0


# Other languages will not be affected

translation.activate('en')

new_product.name
-> ''

new_product.description
-> ''

new_product.price
-> 37
# Of course, non-translatable fields will have a consistent value

Admin Model Forms (editing multiple languages at the same time)

In the admin, you most probably want to include fields for each language (eg. name, name_fr, etc.). In this case you must subclass MultilingualModelForm and use it as the admin form.

# Form definition
from linguo.forms import MultilingualModelForm

class ProductAdminForm(MultilingualModelForm):
    class Meta:
        model = Product
        fields = forms.ALL_FIELDS

# Admin definition
class ProductAdmin(admin.ModelAdmin):
    form = ProductAdminForm

MultilingualModelForm can be used anytime you want to allow editing multiple language simultaneously (not just in the admin). Basically, it just disables the automatic routing to the current active language.

Installation

  1. Add linguo to your INSTALLED_APPS setting.
  2. Ensure the LANGUAGES setting contains all the languages for your site.

Adding new languages

  1. Append the new language to the LANGUAGES setting.
    • You should avoid changing the primary language (ie. the first language in the list). If you do that, you will have to migrate the data in that column.
  2. Generate migrations (since new fields will be added to your models):
    ./manage.py makemigrations <app-name>
    

Running the tests

./manage.py test linguo.tests --settings=linguo.tests.settings

Troubleshooting

If you run into this message when generating migrations:

$ ./manage.py schemamigration yourapp --auto
? The field 'YourModel.field_text_de' does not have a default specified, yet is NOT NULL.
? Since you are adding this field, you MUST specify a default
? value to use for existing rows. Would you like to:
?  1. Quit now, and add a default to the field in models.py
?  2. Specify a one-off value to use for existing columns now
? Please select a choice:

It means you have blank=False, default=None on one or more of your models.

Behind The Scenes (How It Works)

For each field marked as translatable, linguo will create additional database fields for each additional language.

For example, if you mark the following field as translatable …

name = models.CharField(_('name'), max_length=255)

class Meta:
    translate = ('name',)

… and you have three languages (en, fr, de). Your model will have the following db fields:

name = models.CharField(_('name'), max_length=255) # This is for the FIRST language "en"
name_fr = models.CharField(_('name (French)'), max_length=255) # This is for "fr"
name_de = models.CharField(_('name (German)'), max_length=255) # This is for "de"

On the instantiated model, “name” becomes a property that appropriately gets/sets the values for the corresponding field that matches the language we are working with.

For example, if the current language is “fr” …

product = Product()
product.name = "test" # --> sets name_fr

… this will set product.name_fr (not product.name)

Database filtering works because MultingualQueryset rewrites the query.

For example, if the current language is “fr”, and we run the following query …

Product.objects.filter(name="test")

… it will be rewritten to be …

Product.objects.filter(name_fr="test")

License

This app is licensed under the BSD license. See the LICENSE file for details. Basically, feel free to do what you want with this code, but I’m not liable if your computer blows up.

Release History

Release History

1.4.0

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.3.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.3.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.3.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.3.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.2.5

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.2.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.2.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.2.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.2.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.2.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
django-linguo-1.4.0.tar.gz (18.1 kB) Copy SHA256 Checksum SHA256 Source Jan 2, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting