Welcome to Django i18n Fields documentation!

DJANGO i18n FIELDS

A modern Django package providing structured internationalization (i18n) for model fields. Store and manage multilingual content directly in your Django models using a clean, database-agnostic approach.

Improved alternative to django-localized-fields - Works with all databases, not just PostgreSQL.

Key Features

🌍 Comprehensive Field Types: CharField, TextField, IntegerField, FloatField, BooleanField, FileField, UniqueSlugField, and MartorField (Markdown) with multilingual support
🎯 Database Agnostic: Works with PostgreSQL, MySQL, SQLite - any database that supports JSONField
📝 Rich Admin Integration: Beautiful tab and dropdown interfaces for managing translations in Django admin, with Markdown editor support via martor
🔍 Powerful Querying: Filter, order, and annotate queries with language-specific values using L() expressions
🚀 Django REST Framework Support: Automatic serialization with LocalizedModelSerializer - returns simple values in the active language
🛠️ Full Type Safety: Complete type hints with mypy and pyright compatibility

Quick Start

Installation

pip install django-i18n-fields

# With Markdown editor support (martor)
pip install django-i18n-fields[md]

Basic Usage

# models.py
from django.db import models
from i18n_fields import LocalizedCharField, LocalizedTextField

class Article(models.Model):
    title = LocalizedCharField(max_length=200, required=['en'])
    content = LocalizedTextField(blank=True)

# Create with translations
article = Article.objects.create(
    title={'en': 'Hello World', 'es': 'Hola Mundo'},
    content={'en': 'Content in English', 'es': 'Contenido en español'}
)

# Access in current language
print(article.title)  # Automatically uses active language

# Query by specific language
Article.objects.filter(title__en='Hello World')

# Order by translated field
from i18n_fields import L
Article.objects.order_by(L('title'))

Django Admin

# admin.py - Option 1: Using the base class (recommended)
from i18n_fields import LocalizedFieldsAdmin

@admin.register(Article)
class ArticleAdmin(LocalizedFieldsAdmin):
    list_display = ['title', 'created_at']
    # Automatic tab/dropdown widgets for all localized fields!

# admin.py - Option 2: Using the mixin with your own base class
from django.contrib import admin
from i18n_fields import LocalizedFieldsAdminMixin

@admin.register(Article)
class ArticleAdmin(LocalizedFieldsAdminMixin, admin.ModelAdmin):
    list_display = ['title', 'created_at']

Django REST Framework

# serializers.py
from i18n_fields.drf import LocalizedModelSerializer

class ArticleSerializer(LocalizedModelSerializer):
    class Meta:
        model = Article
        fields = ['id', 'title', 'content']

# Returns: {"id": 1, "title": "Hello World", "content": "..."}
# Automatically uses active language!

Configuration

# settings.py
INSTALLED_APPS = [
    # ...
    'i18n_fields',
]

LANGUAGES = [
    ('en', 'English'),
    ('es', 'Spanish'),
    ('fr', 'French'),
]

I18N_FIELDS = {
    'DISPLAY': 'tab',  # or 'dropdown' for admin
    'FALLBACKS': {
        'en-us': ['en'],
        'es-mx': ['es'],
    },
}

Why Django i18n Fields?

vs django-localized-fields

✅ Works with all databases (not just PostgreSQL)
✅ Actively maintained with regular updates
✅ Better type hints and IDE support
✅ Built-in DRF support with automatic serialization
✅ Enhanced admin UI with tab/dropdown modes
✅ Query expressions (L() and LocalizedRef)
✅ Comprehensive documentation

Documentation

📚 Full documentation: https://django-i18n-fields.readthedocs.io/

Quick Links:

Requirements

Python 3.10+
Django 5.0+
Django REST Framework 3.0+ (optional, for DRF integration)
martor (optional, for Markdown editor support — install with pip install django-i18n-fields[md])

Contributing

We welcome contributions! Please see our Contributing Guide for detailed instructions.

Development Setup:

git clone https://github.com/huynguyengl99/django-i18n-fields.git
cd django-i18n-fields
uv venv
source .venv/bin/activate
uv sync --all-extras
pytest

License

MIT License - see LICENSE for details.

Support

🐛 Bug Reports: GitHub Issues
💬 Questions: GitHub Discussions
📖 Documentation: https://django-i18n-fields.readthedocs.io/

Contents

Getting Started

User Guides

API Reference

Development