========================================
django-hvad |package| |coverage| |build|
========================================
**Model translations made easy.**
This project adds support for model translations in Django. It is designed to be
unobtrusive, efficient and reliable. On the technical side, it uses an automatically
created `Translations Model` to store translatable fields in arbitrary
languages with a foreign key to the main model, enabling fast queries.
Started in 2011, hvad has grown mature and is now used on large scale applications.
Quick links:
- `Documentation`_.
- `Release notes`_.
- `Issue tracker`_.
Features
--------
* **Simple** - only 3 new queryset methods.
* **Natural** - use Django ORM as usual, it just became language aware.
* **Fast** - no additional queries for reads, just an inner join to an indexed key.
* **Complete** - relationships, custom managers and querysets, proxy models, and abstract models.
* **Batteries included** - translation-enabled forms and admin are provided.
* **Reliable** - more than 300 test cases and counting. |coverage| |build|
* **Compatible** - follows Django compatibility matrix.
Django-hvad also features support for `Django REST framework`_ 3.1 or newer, including
translation-aware serializers.
Example Uses
------------
Declaring a translatable ``Book`` model::
class Book(TranslatableModel):
author = models.ForeignKey(Author)
release = models.Date()
translations = TranslatedFields(
title = models.CharField(max_length=250)
)
Thus, only the title will vary based on the language. Release date and
author are shared among all languages. Let's now create a ``Book`` instance::
# The recommended way:
book = Book.objects.language('en').create(
author = Author.objects.get(name='Antoine de Saint Exupéry'),
release = datetime.date(1943, 4, 6),
title = "The Little Prince",
)
# Also works
book = Book(language_code='en')
book.author = Author.objects.get(name='Antoine de Saint Exupéry')
book.release = datetime.date(1943, 4, 6)
book.title = "The Little Prince"
book.save()
Providing some translations::
book.translate('fr')
book.title = "Le Petit Prince"
book.save()
book.translate('de')
book.title = "Der kleine Prinz"
book.save()
Every call to ``translate()`` creates a new translation from scratch and switches
to that translation; ``save()`` only saves the latest translation. Let's now perform
some language-aware queries::
Book.objects.all()
Compatible by default: returns all objects, without any translated fields attached.
Starting from v1.0, default behavior can be overriden to work like next query::
Book.objects.language().all()
Returns all objects as translated instances, but only the ones that are translated
into the currect language. You can also specify which language to get, using e.g.::
Book.objects.language("en").all()
Usual queryset methods work like they always did: let's get all books as translated instances,
filtering on the ``title`` attribute, returning those that have
``Petit Prince`` in their French title, ordered by publication date (in their
French edition)::
Book.objects.language("fr").filter(title__contains='Petit Prince').order_by('release')
Other random examples::
# last German book published in year 1948
Book.objects.language("de").filter(release__year=1948).latest()
# other books from the same author as mybook. Cache author as well.
Book.objects.language().select_related('author').filter(author__books=mybook)
# books that have "Django" in their title, regardless of the language
Book.objects.language('all').filter(title__icontains='Django')
More examples in the `quickstart guide`_.
Releases
--------
Django-hvad uses the same release pattern as Django. The following versions
are thus available:
* Legacy branch 1.8, available through `PyPI`_ and git branch ``releases/1.8.x``.
* Stable branch 2.0, available through `PyPI`_ and git branch ``releases/2.0.x``.
* Development branch 2.1, available through git branch ``master``.
Stable branches have minor bugfix releases as needed, with guaranteed compatibility.
See the `installation guide`_ for details, or have a look at the `release notes`_.
Thanks to
---------
Jonas Obrist (https://github.com/ojii) for making django-nani and for helping me with this project.
Kristian Øllegaard (https://github.com/KristianOellegaard/) for django-hvad and trusting me
to continue the development.
.. |package| image:: https://img.shields.io/pypi/v/lotrek-django-hvad?style=flat-square
:target: https://pypi.org/project/lotrek-django-hvad
.. |build| image:: https://img.shields.io/github/workflow/status/lotrekagency/django-hvad/Test,%20Coverage%20and%20Release?style=flat-square
.. |coverage| image:: https://img.shields.io/codecov/c/github/lotrekagency/django-hvad?style=flat-square
.. _documentation: http://django-hvad.readthedocs.org/
.. _release notes: https://django-hvad.readthedocs.org/en/latest/public/release_notes.html
.. _issue tracker: https://github.com/KristianOellegaard/django-hvad/issues
.. _PyPI: https://pypi.python.org/pypi/django-hvad
.. _Django REST framework: http://www.django-rest-framework.org/
.. _installation guide: http://django-hvad.readthedocs.org/en/latest/public/installation.html
.. _quickstart guide: http://django-hvad.readthedocs.org/en/latest/public/quickstart.html
Raw data
{
"_id": null,
"home_page": "https://github.com/lotrekagency/django-hvad",
"name": "lotrek-django-hvad",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.0.*",
"maintainer_email": "",
"keywords": "cms,django,api cms",
"author": "Lotr\u00e8k",
"author_email": "dimmitutto@lotrek.it",
"download_url": "https://files.pythonhosted.org/packages/53/68/38f02963b845579ee4b62fb5217ec2edf7e41643d101000dc762b79b17e7/lotrek-django-hvad-2.0.7.tar.gz",
"platform": null,
"description": "========================================\ndjango-hvad |package| |coverage| |build|\n========================================\n\n**Model translations made easy.**\n\nThis project adds support for model translations in Django. It is designed to be\nunobtrusive, efficient and reliable. On the technical side, it uses an automatically\ncreated `Translations Model` to store translatable fields in arbitrary\nlanguages with a foreign key to the main model, enabling fast queries.\n\nStarted in 2011, hvad has grown mature and is now used on large scale applications.\n\nQuick links:\n\n- `Documentation`_.\n- `Release notes`_.\n- `Issue tracker`_.\n\nFeatures\n--------\n\n* **Simple** - only 3 new queryset methods.\n* **Natural** - use Django ORM as usual, it just became language aware.\n* **Fast** - no additional queries for reads, just an inner join to an indexed key.\n* **Complete** - relationships, custom managers and querysets, proxy models, and abstract models.\n* **Batteries included** - translation-enabled forms and admin are provided.\n* **Reliable** - more than 300 test cases and counting. |coverage| |build|\n* **Compatible** - follows Django compatibility matrix.\n\nDjango-hvad also features support for `Django REST framework`_ 3.1 or newer, including\ntranslation-aware serializers.\n\nExample Uses\n------------\n\nDeclaring a translatable ``Book`` model::\n\n class Book(TranslatableModel):\n author = models.ForeignKey(Author)\n release = models.Date()\n\n translations = TranslatedFields(\n title = models.CharField(max_length=250)\n )\n\nThus, only the title will vary based on the language. Release date and\nauthor are shared among all languages. Let's now create a ``Book`` instance::\n\n # The recommended way:\n book = Book.objects.language('en').create(\n author = Author.objects.get(name='Antoine de Saint Exup\u00e9ry'),\n release = datetime.date(1943, 4, 6),\n title = \"The Little Prince\",\n )\n\n # Also works\n book = Book(language_code='en')\n book.author = Author.objects.get(name='Antoine de Saint Exup\u00e9ry')\n book.release = datetime.date(1943, 4, 6)\n book.title = \"The Little Prince\"\n book.save()\n\nProviding some translations::\n\n book.translate('fr')\n book.title = \"Le Petit Prince\"\n book.save()\n book.translate('de')\n book.title = \"Der kleine Prinz\"\n book.save()\n\nEvery call to ``translate()`` creates a new translation from scratch and switches\nto that translation; ``save()`` only saves the latest translation. Let's now perform\nsome language-aware queries::\n\n Book.objects.all()\n\nCompatible by default: returns all objects, without any translated fields attached.\nStarting from v1.0, default behavior can be overriden to work like next query::\n\n Book.objects.language().all()\n\nReturns all objects as translated instances, but only the ones that are translated\ninto the currect language. You can also specify which language to get, using e.g.::\n\n Book.objects.language(\"en\").all()\n\nUsual queryset methods work like they always did: let's get all books as translated instances,\nfiltering on the ``title`` attribute, returning those that have\n``Petit Prince`` in their French title, ordered by publication date (in their\nFrench edition)::\n\n Book.objects.language(\"fr\").filter(title__contains='Petit Prince').order_by('release')\n\nOther random examples::\n\n # last German book published in year 1948\n Book.objects.language(\"de\").filter(release__year=1948).latest()\n\n # other books from the same author as mybook. Cache author as well.\n Book.objects.language().select_related('author').filter(author__books=mybook)\n\n # books that have \"Django\" in their title, regardless of the language\n Book.objects.language('all').filter(title__icontains='Django')\n\n\nMore examples in the `quickstart guide`_.\n\nReleases\n--------\n\nDjango-hvad uses the same release pattern as Django. The following versions\nare thus available:\n\n* Legacy branch 1.8, available through `PyPI`_ and git branch ``releases/1.8.x``.\n* Stable branch 2.0, available through `PyPI`_ and git branch ``releases/2.0.x``.\n* Development branch 2.1, available through git branch ``master``.\n\nStable branches have minor bugfix releases as needed, with guaranteed compatibility.\nSee the `installation guide`_ for details, or have a look at the `release notes`_.\n\nThanks to\n---------\n\nJonas Obrist (https://github.com/ojii) for making django-nani and for helping me with this project.\n\nKristian \u00d8llegaard (https://github.com/KristianOellegaard/) for django-hvad and trusting me\nto continue the development.\n\n.. |package| image:: https://img.shields.io/pypi/v/lotrek-django-hvad?style=flat-square\n :target: https://pypi.org/project/lotrek-django-hvad\n.. |build| image:: https://img.shields.io/github/workflow/status/lotrekagency/django-hvad/Test,%20Coverage%20and%20Release?style=flat-square\n.. |coverage| image:: https://img.shields.io/codecov/c/github/lotrekagency/django-hvad?style=flat-square\n\n.. _documentation: http://django-hvad.readthedocs.org/\n.. _release notes: https://django-hvad.readthedocs.org/en/latest/public/release_notes.html\n.. _issue tracker: https://github.com/KristianOellegaard/django-hvad/issues\n.. _PyPI: https://pypi.python.org/pypi/django-hvad\n.. _Django REST framework: http://www.django-rest-framework.org/\n.. _installation guide: http://django-hvad.readthedocs.org/en/latest/public/installation.html\n.. _quickstart guide: http://django-hvad.readthedocs.org/en/latest/public/quickstart.html\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A content translation framework for django integrated automatically in the normal ORM. Removes the pain of having to think about translations in a django project.",
"version": "2.0.7",
"split_keywords": [
"cms",
"django",
"api cms"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "23c14aac25b8163b50ee26766f3695dc",
"sha256": "4d063357130670a92b37eb52d151e2d48663094e7cf1cee6a9cf7b7c2ceff980"
},
"downloads": -1,
"filename": "lotrek_django_hvad-2.0.7-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "23c14aac25b8163b50ee26766f3695dc",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.0.*",
"size": 106800,
"upload_time": "2022-12-21T18:02:17",
"upload_time_iso_8601": "2022-12-21T18:02:17.138865Z",
"url": "https://files.pythonhosted.org/packages/ea/4c/79878243192f93c6345cda0a51c40903645066ab62a420235957db9a1be3/lotrek_django_hvad-2.0.7-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "499f6b7fa786815598a80850a42f1d4d",
"sha256": "98b66fd58b2a4c6ecf7cc72e4e5184ee75fe852f6695ba334032a958b9f868b5"
},
"downloads": -1,
"filename": "lotrek-django-hvad-2.0.7.tar.gz",
"has_sig": false,
"md5_digest": "499f6b7fa786815598a80850a42f1d4d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.0.*",
"size": 108862,
"upload_time": "2022-12-21T18:02:18",
"upload_time_iso_8601": "2022-12-21T18:02:18.835777Z",
"url": "https://files.pythonhosted.org/packages/53/68/38f02963b845579ee4b62fb5217ec2edf7e41643d101000dc762b79b17e7/lotrek-django-hvad-2.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-21 18:02:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "lotrekagency",
"github_project": "django-hvad",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "lotrek-django-hvad"
}
JSON
