Django-Vinaigrette 使用与技术文档

1. 安装指南

在开始使用django-vinaigrette之前，需要按照以下步骤进行安装：

• 将vinaigrette添加到您的Django项目的INSTALLED_APPS配置中。
• 在适当的apps.py文件中的AppConfig的ready方法里注册需要翻译的模型字段。

import vinaigrette

class SaladAppConfig(AppConfig):
    def ready(self):
        # 导入需要翻译的模型
        from .models import Ingredient  # 或其他模型...
        Ingredient = self.get_model("Ingredient")

        # 注册需要翻译的字段
        vinaigrette.register(Ingredient, ['name', 'description'])

这会告诉vinaigrette翻译Ingredient对象上的name和description字段。

2. 项目使用说明

安装vinaigrette之后，使用manage.py makemessages命令生成的PO文件将包含已注册字段的字符串。如果某个特定的字符串已经被翻译，那么模型的值将是翻译成相应语言的字符串。

from django.utils.translation import activate

i = Ingredient(name=u'莴苣')
print(i.name)  # 输出原始值
activate('fr')  # 激活法语
print(i.name)  # 输出翻译后的值

vinaigrette还提供了一些选项来限制从哪些对象收集翻译字符串。详情请参考vinaigrette.register的文档字符串。

vinaigrette为manage.py makemessages命令增加了一个--keep-obsolete选项，这可以防止gettext停用代码或已注册数据库字段中不再存在的翻译消息。

vinaigrette适用于以下类型的数据库内容：

• 总是使用默认语言编辑
• 由网站管理员编辑，而非用户

只有模型实例会被翻译。通过Django QuerySet的values方法访问的数据不会被翻译。

一般情况下，当访问字段时，如果存在翻译版本，它将始终返回翻译版本。但是，如果设置值，则应该将输入的确切值（而非翻译版本）保存到数据库。

3. 项目API使用文档

目前项目中的API主要是通过注册模型和字段来进行翻译操作，以下是主要API的使用方法：

• vinaigrette.register(model, fields): 注册需要翻译的模型及其字段。

• vinaigrette.middleware.VinaigretteAdminLanguageMiddleware: 中间件，用于强制后台管理界面始终使用主语言，避免vinaigrette干扰更改视图。

4. 项目安装方式

项目的安装方式已在“安装指南”一节中说明。这里补充一下，如果遇到后台管理界面问题，请确保在settings.MIDDLEWARE中添加了VinaigretteAdminLanguageMiddleware中间件。

MIDDLEWARE = [
    # 其他中间件...
    'vinaigrette.middleware.VinaigretteAdminLanguageMiddleware',
    # 其他中间件...
]

以上就是django-vinaigrette的安装使用和技术文档，如果需要更多帮助，请参考项目在GitHub上的wiki页面。