Metadata-Version: 1.1
Name: nece
Version: 0.4.4
Summary: A content translation framework using Postgresql's jsonb field in the background
Home-page: https://github.com/tatterdemalion/django-nece
Author: Can Mustafa Özdemir
Author-email: canmustafaozdemir@gmail.com
License: BSD License
Download-URL: https://github.com/tatterdemalion/django-nece/tarball/0.4.4
Description: nece?
        =====
        
        .. image:: https://img.shields.io/travis/tatterdemalion/django-nece/master.svg
            :target: https://travis-ci.org/tatterdemalion/django-nece
        
        .. image:: https://img.shields.io/coveralls/tatterdemalion/django-nece.svg
            :target: https://coveralls.io/r/tatterdemalion/django-nece
        
        .. image:: https://img.shields.io/pypi/v/nece.svg
            :target: https://pypi.python.org/pypi/nece
        
        .. image:: https://img.shields.io/pypi/pyversions/nece.svg
            :target: https://pypi.python.org/pypi/nece/
        
        Introduction
        ------------
        
        .. figure:: https://raw.githubusercontent.com/tatterdemalion/django-nece/master/images/nece.png
           :alt: nece
        
        A “Content Translation Framework” using Postgresql’s jsonb field. It
        simply sets and gets translations from a jsonb field called
        ``translations``.
        
        Why?
        ~~~~
        
        You might ask why you should use django-nece since there are other, and
        more mature content translation frameworks like `django-hvad`_ and
        `django-modeltranslation`_. Both of them are good in some ways, worst in
        others.
        
        For instance, it is very hard for ``django-hvad`` users to get default
        language if there is no corresponding translation for an object. And it
        holds translated values in a different table, so every translation query
        results in another hit to the database.
        
        On the other hand ``django-modeldtranslation`` adds multiple additional
        fields for multiple languages. The number of fields inceases by the
        number of languages you need to support. At the end it becomes a huge
        chunk of an object if you need to add more than 20 languages.
        
        ``nece?`` more or less works like the latter one with an important
        difference. It uses Postgresql’s new ``JSONB`` field to hold translation
        information. And overrides the original one on query.
        
        Dependencies
        ------------
        
        ::
        
            postgresql >= 9.4
            Django >= 1.8
            psycopg2 >= 2.5.4
        
        
        Installation
        ------------
        
        via pypi:
        ~~~~~~~~~
        
        ::
        
            pip install nece
        
        via setup.py
        ~~~~~~~~~~~~
        
        ::
        
            python setup.py install
        
        Usage
        -----
        
        Lets say we have a model called ``Fruit``:
        
        ::
        
            from nece.models import TranslationModel
        
            class Fruit(TranslationModel):
                name = CharField(max_length=255)
                translatable_fields = ['name']
        
                def __str__(self):
                    return self.name
        
        ``TranslationModel`` adds a jsonb field to this table and sets
        translations in a notation like the one below:
        
        ::
        
            {u'de_de': {u'name': u'Apfel'},
             u'tr_tr': {u'name': u'elma'}}
        
        When we need the German translation we can simply choose the language
        and get the attribute as usual:
        
        ::
        
            >> f = Fruit.objects.get(name='apple')
            >> print(f.name)
            apple
            >> f.language('de_de')
            >> print(f.name)
            Apfel
        
        You can also filter out the ones containing any language translation:
        
        ::
        
            >> Fruit.objects.all()
            [<Fruit: apple>, <Fruit: pear>, <Fruit: banana>]
            >> Fruit.objects.language('tr_tr')
            [<Fruit: elma>, <Fruit: armut>]  # there is no translation for banana
            >> Fruit.objects.language_or_default('tr_tr')
            [<Fruit: elma>, <Fruit: armut>, <Fruit: banana>]
            >> Fruit.objects.language('tr_tr').filter(name='elma')
            [<Fruit: elma>]
            >> Fruit.objects.language('tr_tr').get(name='elma')
            <Fruit: elma>
        
        Updating translations
        ~~~~~~~~~~~~~~~~~~~~~
        
        ::
        
            >> fruit._language_code
            tr_tr
            >> fruit.name
            elma
            >> fruit.translate(name='armut').save()
            >> fruit.name
            armut
            >> fruit.language('en')
            >> fruit.translate('it_it', name='pera')
            >> fruit.language('it_it')
            >> fruit.name
            pera
        
        Settings
        --------
        
        TRANSLATIONS_DEFAULT
        ~~~~~~~~~~~~~~~~~~~~
        
        Default language code. Default value: ```en_us```
        
        TRANSLATIONS_MAP
        ~~~~~~~~~~~~~~~~
        
        Shortcuts for ```languagecode_countrycode``` notation. 
        
        Example:
        
        ::
        
            TRANSLATIONS_MAP = {
                "en": "en_us",
                "tr": "tr_tr",
                "ar": "ar_sy",
                "bg": "bg_bg",
                "cs": "cs_cz",
                "da": "da_dk",
                "de": "de_de",
                "el": "el_gr",
                "es": "es_es",
                "fi": "fi_fi",
                "fr": "fr_fr",
                "hu": "hu_hu",
                "it": "it_it",
                "ja": "ja_ja",
                "nl": "nl_nl",
                "pl": "pl_pl",
                "pt": "pt_pt",
                "ro": "ro_ro",
                "ru": "ru_ru",
                "sv": "sv_se",
                "zh": "zh_cn"
            }
        
        
        Default:
        
        ::
        
            {'en': 'en_us'}
        
        
        
        
        
        
        .. _django-hvad: https://github.com/kristianoellegaard/django-hvad
        .. _django-modeltranslation: https://github.com/deschler/django-modeltranslation
        
Keywords: translations,i18n,language,multilingual
Platform: UNKNOWN
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Database
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Text Processing :: Linguistic
