Translate Django model data using gettext
Project description
==================
django-vinaigrette
==================
Vinaigrette translates Django model data -- stored in the database -- using GNU gettext
and Django's standard internationalization features.
Installing
==========
Add ``vinaigrette`` to INSTALLED_APPS in your settings.
Then, tell vinaigrette which fields you want to translate. In the appropriate ``models.py`` files::
import vinaigrette
vinaigrette.register(Ingredient, ['name', 'description'])
This tells vinaigrette to translate the ``name`` and ``description`` fields on Ingredient objects.
Using
=====
After installing vinaigrette, the PO files generated by ``manage.py makemessages`` will include
strings from the registered fields. If a particular string is translated, the model value will
be the string translated into the appropriate language::
>>> from django.utils.translation import activate
>>> i = Ingredient(name=u'Lettuce')
>>> i.name
u'Lettuce'
>>> activate('fr')
>>> i.name
u'Laitue'
Et cetera
=========
There are a couple of options to restrict which objects translation strings will be collected
from. See the docstring for ``vinaigrette.register``.
Vinaigrette adds a ``--keep-obsolete`` option to ``manage.py makemessages``, which prevents gettext
from deactivating translated messages no longer present in code or in registered database fields.
Vinaigrette is designed for database content that is:
- always edited in the default language
- edited by site administrators, not users
Only model instances are translated. Data accessed via the Django QuerySet ``values`` method will
not be translated.
In general, when a field is accessed, it will always return the translated version, if one exists.
However, if a value is set, the exact value entered (and not the translated version) should be saved
to the database. For example:
>>> from django.utils.translation import activate
>>> i = Ingredient(name=u'Lettuce')
>>> activate('fr')
>>> i.name
u'Laitue'
>>> i.name = 'Cabbage'
>>> i.name
u'Chou'
>>> i.save()
>>> Ingredient.objects.get(name='Cabbage').name
u'Chou'
Help! The Admin is messing up all the vinaigrette fields whenever I save changes!
---------------------------------------------------------------------------------
Add ``vinaigrette.middleware.VinaigretteAdminLanguageMiddleware`` to your
``settings.MIDDLEWARE`` to force the admin to always use the main language, and
not have vinaigrette mess with your change views.
Contributing
============
Testing
-------
* Create a virtualenv for the project
* Install ``tox``. When tox is run, it will create the test environments for
supported Django and Python versions and then run tests against them
=============
Release Notes
=============
Upcoming
--------
1.2.0a
------
* Update middleware to the 1.10+ style
* Maintains backwards-compat with 1.9 and below
* Will now work in either ``MIDDLEWARE_CLASSES`` or ``MIDDLEWARE``
* Deprecates ``VinaigrettteAdminLanguageMiddleware`` for ``VinaigretteAdminLanguageMiddleware``
* Users should change to ``vinaigrette.middleware.VinaigretteAdminLanguageMiddleware``
* ``vinaigrette.VinaigrettteAdminLanguageMiddleware`` will continue to work until next major version
* Adds tox and pytest for development and testing
1.1.1
-----
* Update contact info
1.1.0
-----
* Django 2.0 support
1.0.1
-----
* Remembered to update version properly
1.0.0
-----
* Add the ``--keep-vinaigrette-temp`` option which keeps the temporary file containing the generated list of translations
* Added support for Django 1.9
* Remove support for Django versions < 1.8
0.5.0
-----
* Can specify properties to use instead of database field names in .register() function.
0.4.0
-----
* Support for Django 1.7
0.3.0
-----
* Support for python 3.3.
0.2.0
-----
* Bug fix for the --all option, it now works again.
* New VinaigrettteAdminLanguageMiddleware middleware.
0.1.3
-----
* Support for Django 1.6.
django-vinaigrette
==================
Vinaigrette translates Django model data -- stored in the database -- using GNU gettext
and Django's standard internationalization features.
Installing
==========
Add ``vinaigrette`` to INSTALLED_APPS in your settings.
Then, tell vinaigrette which fields you want to translate. In the appropriate ``models.py`` files::
import vinaigrette
vinaigrette.register(Ingredient, ['name', 'description'])
This tells vinaigrette to translate the ``name`` and ``description`` fields on Ingredient objects.
Using
=====
After installing vinaigrette, the PO files generated by ``manage.py makemessages`` will include
strings from the registered fields. If a particular string is translated, the model value will
be the string translated into the appropriate language::
>>> from django.utils.translation import activate
>>> i = Ingredient(name=u'Lettuce')
>>> i.name
u'Lettuce'
>>> activate('fr')
>>> i.name
u'Laitue'
Et cetera
=========
There are a couple of options to restrict which objects translation strings will be collected
from. See the docstring for ``vinaigrette.register``.
Vinaigrette adds a ``--keep-obsolete`` option to ``manage.py makemessages``, which prevents gettext
from deactivating translated messages no longer present in code or in registered database fields.
Vinaigrette is designed for database content that is:
- always edited in the default language
- edited by site administrators, not users
Only model instances are translated. Data accessed via the Django QuerySet ``values`` method will
not be translated.
In general, when a field is accessed, it will always return the translated version, if one exists.
However, if a value is set, the exact value entered (and not the translated version) should be saved
to the database. For example:
>>> from django.utils.translation import activate
>>> i = Ingredient(name=u'Lettuce')
>>> activate('fr')
>>> i.name
u'Laitue'
>>> i.name = 'Cabbage'
>>> i.name
u'Chou'
>>> i.save()
>>> Ingredient.objects.get(name='Cabbage').name
u'Chou'
Help! The Admin is messing up all the vinaigrette fields whenever I save changes!
---------------------------------------------------------------------------------
Add ``vinaigrette.middleware.VinaigretteAdminLanguageMiddleware`` to your
``settings.MIDDLEWARE`` to force the admin to always use the main language, and
not have vinaigrette mess with your change views.
Contributing
============
Testing
-------
* Create a virtualenv for the project
* Install ``tox``. When tox is run, it will create the test environments for
supported Django and Python versions and then run tests against them
=============
Release Notes
=============
Upcoming
--------
1.2.0a
------
* Update middleware to the 1.10+ style
* Maintains backwards-compat with 1.9 and below
* Will now work in either ``MIDDLEWARE_CLASSES`` or ``MIDDLEWARE``
* Deprecates ``VinaigrettteAdminLanguageMiddleware`` for ``VinaigretteAdminLanguageMiddleware``
* Users should change to ``vinaigrette.middleware.VinaigretteAdminLanguageMiddleware``
* ``vinaigrette.VinaigrettteAdminLanguageMiddleware`` will continue to work until next major version
* Adds tox and pytest for development and testing
1.1.1
-----
* Update contact info
1.1.0
-----
* Django 2.0 support
1.0.1
-----
* Remembered to update version properly
1.0.0
-----
* Add the ``--keep-vinaigrette-temp`` option which keeps the temporary file containing the generated list of translations
* Added support for Django 1.9
* Remove support for Django versions < 1.8
0.5.0
-----
* Can specify properties to use instead of database field names in .register() function.
0.4.0
-----
* Support for Django 1.7
0.3.0
-----
* Support for python 3.3.
0.2.0
-----
* Bug fix for the --all option, it now works again.
* New VinaigrettteAdminLanguageMiddleware middleware.
0.1.3
-----
* Support for Django 1.6.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Close
Hashes for django-vinaigrette-1.2.0a0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | fdc599f5c65306a38eddb1e720fe49a0b36d107411bd2017383e5bc1543e0c74 |
|
MD5 | a997cc7c21687fc9ecf9c52ee0571ac4 |
|
BLAKE2b-256 | 466ea8f725b0d4fd8baabdef52a84e3ee2eb30df9c03e71d87135fce29673a21 |
Close
Hashes for django_vinaigrette-1.2.0a0-py2-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8dda43921b337d160ea0a9a3dd92cc010638180379152c8e5474b64970af7932 |
|
MD5 | 9f9eb264615bd38fb251faa4eb91bede |
|
BLAKE2b-256 | 13ceebb4bdd2f28218298a7276467c2e32bef64b427c283ce3124148e2412ece |