Dj_translation supports various database backends, including PostgreSQL, MySQL, SQLite, and Oracle. Developers choose based on performance, scalability, and compatibility with their tech stack.
Project description
============== DJ-Translation
Description
The Translation Package is a Django package that simplifies the handling of translations in your Django projects. It provides a convenient way to store translation values as JSON and includes a model field, form field, and widget to facilitate translation management.
.. image:: ./docs/translation_field.png :width: 100% :align: center :alt: DJ-Translation Logo
Contents
Features <#features>
_Installation <#installation>
_Configuration <#configuration>
_Usage <#usage>
_Additional Functionality <#additional-functionality>
_Using DJ-Translation in the Django Admin <#using-dj-translation-in-the-django-admin>
_API Reference <#api-reference>
_Contributing <#contributing>
_
Features
- JSON-based Translation Storage: JSON-based Translation Storage: The package allows you to store translation values as JSON, making it easy to manage and update translations.
- Model Field: It includes a custom model field that seamlessly integrates with your Django models, allowing you to store and retrieve translations effortlessly.
- Ability to handle translations for multiple languages out of the box.
- Support for rich text translation with optional CKEditor 5 integration.
- Customizable CKEditor 5 configuration for tailored editing experience.
Installation
Before installing DJ-Translation, please ensure you have Django 4.x installed. You can install DJ-Translation using pip, as follows:
.. code-block::
$ pip install dj-translation
If you prefer to install from source, you can clone the repository from GitHub and install it manually:
.. code-block::
$ git clone https://github.com/fritill-team/django-translation.git
$ cd dj-translation
$ python setup.py install
Note: It is recommended to create a virtual environment before installing DJ-Translation to keep your Django projects isolated.
Configuration
Once DJ-Translation is installed, you need to add it to your Django project's settings. Open your project's settings.py
file and add 'dj_translation'
to the INSTALLED_APPS
setting:
.. code-block::
INSTALLED_APPS = [
# Other apps...
'dj_translation',
]
Finally, run the database migrations to create the necessary tables for DJ-Translation:
.. code-block::
python manage.py migrate
Once DJ-Translation is installed, you need to add it to your Django project's settings. Open your project's settings.py
file and make the following additions:
Add the following language-related settings:
.. code-block::
LANGUAGE_CODE = 'en-us'
ARABIC_LANGUAGE_CODE = 'ar'
ENGLISH_LANGUAGE_CODE = 'en'
SPANISH_LANGUAGE_CODE = 'es'
# Languages we provide translations for, out of the box.
LANGUAGES = [
(ARABIC_LANGUAGE_CODE, gettext_noop('Arabic')),
(ENGLISH_LANGUAGE_CODE, gettext_noop('English')),
(SPANISH_LANGUAGE_CODE, gettext_noop('Español'))
]
# Languages using BiDi (right-to-left) layout
LANGUAGES_BIDI = ["he", "ar", "ar-dz", "fa", "ur"]
Note: Adjust the language codes and names according to your specific requirements.
Add the CKEditor configuration for DJ-Translation (optional):
.. code-block::
DJ_TRANSLATION_CKEDITOR_CONFIG = {
'toolbar': {
'items': ['heading', '|', 'bold', 'italic', 'link', 'bulletedList', 'numberedList', '|', 'undo', 'redo']
}
}
Note: The CKEditor configuration is optional and can be used to customize the CKEditor toolbar items according to your needs.
Usage
To utilize the translation capabilities provided by DJ-Translation, follow these guidelines:
- Define Models: Declare a model field of type
TranslatedField
in your Django models to store translated values. You can use the additional attributerich_text=True
to enable CKEditor integration for the field:
.. code-block::
from dj_translation.fields import TranslatedField
class YourModel(models.Model):
translated_field = TranslatedField(rich_text=True)
- Forms Integration: Use the
TranslatedFormField
in your Django forms to enable translation input and display. If you have a translated field with CKEditor enabled, make sure to include CKEditor assets in your form template:
.. code-block::
{% extends "base.html" %}
{% block content %}
<form method="post">
{% csrf_token %}
{{ form.media }}
{{ form.translated_field }}
<button type="submit">Save</button>
</form>
{% endblock %}
-
Widget Customization: Customize the appearance and behavior of the
TranslatedWidget
to match your application's requirements. -
Retrieving Translations: Retrieve translated values from the
TranslatedField
and display them in your templates or API responses.
Additional Functionality
TranslatedValue Class
The `TranslatedValue` class is provided by DJ-Translation to work with translated values. You can pass the value returned from the `TranslatedField` to create a `TranslatedValue` instance.
``Translate Function``
~~~~~~~~~~~~~~~~~~
The `TranslatedValue` class provides a `translate` function that can be used to retrieve the translated value based on the activated language or a specific language.
Example usage:
.. code-block::
# Create a TranslatedValue instance
translated_value = TranslatedValue(value_from_field)
# Retrieve the translated value for the activated language
activated_language_translation = translated_value.translate()
# Retrieve the translated value for a specific language
specific_language_translation = translated_value.translate(language='fr')
``Using DJ-Translation in the Django Admin``
DJ-Translation can be seamlessly integrated into the Django admin interface to manage translations. To enable DJ-Translation in the admin, follow these steps:
- Create your model and use
TranslationField
.. code-block::
class TranslatableModel(models.Model):
title = TranslationField(blank=True, null=True, default=dict, rich_text=False)
description = TranslationField(blank=True, null=True, default=dict, rich_text=True)
created_at = models.DateTimeField(auto_created=True, default=now, blank=True)
updated_at = models.DateTimeField(auto_now=True, null=True, blank=True)
def __str__(self):
return TranslatedValue(self.title).translate()
- Register your models with translated fields in the admin site by creating an admin.py file in your app directory (if not already created) and define a custom ModelAdmin class:
.. code-block::
class CustomModelAdmin(admin.ModelAdmin):
form = TranslatableForm
admin.site.register(TranslatableModel, CustomModelAdmin) # Register your model and admin class
- Now, when you access the admin interface for your models, the translated fields will be available for input and display.
API Reference
The package provides the following API elements:
TranslatedField
A model field that handles the storage and retrieval of translated values.
``TranslatedFormField``
A form field for translation input.
TranslatedWidget
A widget for displaying translations.
Contributing
=============
We welcome contributions to DJ-Translation! If you would like to contribute code, report issues, or submit pull requests, please refer to our guidelines at [link to contribution guidelines].
Project details
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
Hashes for dj_translation-1.0.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4fd53eb0201d2492b9d0dd822ea871a43da75c1804a6a508b894bcff3dcaa18c |
|
MD5 | 62c774a3a84ce691455fe27b85d76b90 |
|
BLAKE2b-256 | 18fc2022124aa2e5c778c0066760898b00c28ea6451f656d7a227d2da694e5c4 |