Django-hvad 使用教程

Django-hvad 使用教程

1. 项目介绍

Django-hvad 是一个用于 Django 模型翻译的开源项目。它通过创建自动翻译的模型，使得在 Django 中处理多语言变得简单高效。该项目始于2011年，经过多年的发展，已经成熟并应用于大型项目。Django-hvad 的特点包括：

• 简单：仅需要3个新的查询集方法。
• 自然：如同使用 Django ORM 一样自然，只是增加了语言感知功能。
• 快速：读取时无需额外查询，只需一个指向索引键的内联连接。
• 完整：支持关系、自定义管理器和查询集、代理模型和抽象模型。
• 开箱即用：提供了翻译启用的表单和后台管理。
• 可靠：超过300个测试用例，仍在增加中。
• 兼容性：与 Django 1.8 到 1.11 版本兼容，支持 Python 2.7, 3.4, 3.5 或 3.6。

2. 项目快速启动

首先，确保已经安装了 Django 和相应的依赖。以下是快速启动 Django-hvad 的基本步骤：

# 安装 django-hvad
pip install django-hvad

# 在 settings.py 中添加 'hvad' 到 INSTALLED_APPS
INSTALLED_APPS = [
    # 其他应用...
    'hvad',
]

# 在 settings.py 中配置 LANGUAGE_CODE 和 LANGUAGES
LANGUAGE_CODE = 'en'
LANGUAGES = (
    ('en', 'English'),
    ('fr', 'French'),
    # 其他语言...
)

# 创建迁移文件并应用迁移
python manage.py makemigrations
python manage.py migrate

接下来，定义一个可翻译的模型：

from django.db import models
from hvad.models import TranslatableModel, TranslatedFields

class Author(models.Model):
    name = models.CharField(max_length=100)

class Book(TranslatableModel):
    author = models.ForeignKey(Author, on_delete=models.CASCADE)
    release = models.DateField()
    translations = TranslatedFields(
        title=models.CharField(max_length=250)
    )

创建和保存模型的实例：

from django.utils import timezone
from myapp.models import Book, Author

author = Author.objects.create(name='Antoine de Saint Exupéry')
book = Book.objects.language('en').create(
    author=author,
    release=timezone.datetime(1943, 4, 6),
    title="The Little Prince"
)

3. 应用案例和最佳实践

翻译模型实例

# 翻译到一个新的语言
book.translate('fr')
book.title = "Le Petit Prince"
book.save()

# 获取特定语言的翻译
book = Book.objects.language('fr').get(id=book.id)
print(book.title)  # 输出 "Le Petit Prince"

查询集操作

# 获取所有法语版的书籍
books = Book.objects.language('fr').all()

# 过滤法语标题包含 "Petit Prince" 的书籍
books = Book.objects.language('fr').filter(title__contains='Petit Prince')

# 按法语版的出版日期排序
books = Book.objects.language('fr').order_by('release')

4. 典型生态项目

Django-hvad 可与多个 Django 生态项目配合使用，例如 Django REST framework。下面是一个简单的例子，演示如何在 Django REST framework 中使用 django-hvad：

from rest_framework import serializers
from myapp.models import Book

class BookSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Book
        fields = ('url', 'author', 'release', 'title')

# 使用时，确保设置了正确的语言
 serializer = BookSerializer(Book.objects.language('en').all(), many=True)

以上就是 Django-hvad 的基本使用教程，希望对您有所帮助。