Package: dj-translation
==============
DJ-TranslationDescriptionThe 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 LogoContentsFeatures <#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>_FeaturesJSON-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.InstallationBefore 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-translationIf 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 installNote: It is recommended to create a virtual environment before installing DJ-Translation to keep your Django projects isolated.ConfigurationOnce DJ-Translation is installed, you need to add it to your Django project's settings. Open your project'ssettings.pyfile and add'dj_translation'to theINSTALLED_APPSsetting:.. 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 migrateOnce DJ-Translation is installed, you need to add it to your Django project's settings. Open your project'ssettings.pyfile 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.UsageTo utilize the translation capabilities provided by DJ-Translation, follow these guidelines:Define Models: Declare a model field of typeTranslatedFieldin your Django models to store translated values. You can use the additional attributerich_text=Trueto 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 theTranslatedFormFieldin 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 theTranslatedWidgetto match your application's requirements.Retrieving Translations: Retrieve translated values from theTranslatedFieldand display them in your templates or API responses.Additional FunctionalityTranslatedValue ClassThe `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 useTranslationField.. 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 classNow, when you access the admin interface for your models, the translated fields will be available for input and display.API ReferenceThe package provides the following API elements:TranslatedFieldA model field that handles the storage and retrieval of translated values.

``TranslatedFormField``A form field for translation input.TranslatedWidgetA 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].