一、translation.py 文件的核心目的

这个文件是 django-modeltranslation 库的多语言字段配置文件，核心作用是：
告诉 django-modeltranslation：哪些模型的哪些字段需要支持多语言，并自动为这些字段生成对应语言的数据库列（如 name_en、name_zh_hans、name_ru），同时让 Django Admin 自动显示多语言输入框。

简单来说：

  • 没有这个文件 → 模型字段只有单语言版本（如 name 仅存英文）；
  • 有这个文件 → 自动生成多语言字段（name_en/name_zh_hans/name_ru），无需手动修改模型。

二、这个文件「在哪里被调用」？

1. 调用时机：Django 启动时自动加载

django-modeltranslation 会在 Django 应用初始化（apps.populate()）阶段，自动扫描每个已注册应用下的 translation.py 文件，并执行其中的 @register 装饰器逻辑——无需你手动导入/调用这个文件，是框架自动触发的。

2. 具体执行流程（Django 启动时）：

Django 启动 → 加载 settings.py 中的 INSTALLED_APPS → 初始化每个应用 → 
modeltranslation 扫描应用下的 translation.py → 执行 @register 装饰器 → 
为指定模型字段生成多语言版本 → 注册到 Django 模型注册表

3. 关键触发条件：

  • modeltranslation 必须在 settings.py 的 INSTALLED_APPS 中（且在 django.contrib.admin 之前）；
  • 文件名必须是 translation.py（固定命名，框架只认这个名字）；
  • 文件必须放在应用目录下（如 products/translation.py）。

三、文件内容的逐行解释

# 1. 导入必要的工具：register（注册多语言模型）、TranslationOptions（配置多语言字段）
from modeltranslation.translator import register, TranslationOptions
# 2. 导入需要配置多语言的模型
from .models import Category, Product, ProductImage

# 3. 为 Category 模型配置多语言
@register(Category)  # 装饰器：告诉框架要处理 Category 模型
class CategoryTranslationOptions(TranslationOptions):
    fields = ('name',)  # 指定 Category 的 name 字段需要多语言
    # 效果：自动生成 name_en、name_zh_hans、name_ru 三个数据库字段

# 4. 为 Product 模型配置多语言
@register(Product)
class ProductTranslationOptions(TranslationOptions):
    fields = ('name', 'short_description', 'full_description')
    # 效果：为这3个字段各生成3个语言版本（共9个字段）

# 5. 为 ProductImage 的 alt_text 配置多语言（可选）
@register(ProductImage)
class ProductImageTranslationOptions(TranslationOptions):
    fields = ('alt_text',)
    # 效果：自动生成 alt_text_en、alt_text_zh_hans、alt_text_ru

四、这个文件的实际作用（落地效果）

1. 数据库层面：自动新增多语言字段

执行 makemigrations 后，数据库表会自动新增字段：

  • categories 表：新增 name_en、name_zh_hans、name_ru；
  • products 表：新增 name_en、name_zh_hans、name_ru，short_description_en/zh_hans/ru，full_description_en/zh_hans/ru；
  • productimage 表：新增 alt_text_en、alt_text_zh_hans、alt_text_ru。

2. Admin 后台层面：自动显示多语言输入框

在 Django Admin 中添加/编辑 Category/Product 时，原本的 name 字段会变成「多语言输入组」：

  • 英文输入框（Name (English)）；
  • 中文输入框（Name (Simplified Chinese)）；
  • 俄语输入框（Name (Russian)）。

无需你手动修改 Admin 代码，框架自动渲染。

3. 模板/视图层面：透明访问多语言字段

在模板中写 {{ category.name }} 时：

  • 框架会根据当前请求的语言（request.LANGUAGE_CODE），自动返回对应语言的字段值；
  • 例如当前语言是 zh-hans → 实际取 category.name_zh_hans；
  • 无需手动判断 if request.LANGUAGE_CODE == 'zh-hans': ...，框架自动处理。

五、常见问题：为什么修改了 translation.py 没生效？

  1. 未重启 Django 服务：translation.py 仅在 Django 启动时加载，修改后需重启 runserver；
  2. 未重新生成迁移：新增多语言字段后，需执行 makemigrations + migrate 才能同步到数据库；
  3. modeltranslation 位置错误：必须在 INSTALLED_APPS 中位于 django.contrib.admin 之前；
  4. 文件名错误：必须是 translation.py（不能写成 translations.py 或其他）。

六、总结

维度作用说明
核心目的配置模型字段的多语言版本，自动生成数据库字段和Admin输入框
调用方式Django 启动时由 modeltranslation 自动扫描加载，无需手动调用
落地效果数据库多语言字段 + Admin 多语言输入 + 模板透明访问
关键依赖INSTALLED_APPS 中注册 modeltranslation，且文件名必须为 translation.py

这个文件是 django-modeltranslation 实现「模型动态多语言」的核心配置文件，也是我们能在不修改模型代码的前提下，为字段添加多语言支持的关键。
(來自doubao)

标签: none