3 个任务让 Django 站点支持 200+ 语言：Wagtail 多语言实战指南

3 个任务让 Django 站点支持 200 语言Wagtail 多语言实战指南【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtailWagtail 是基于 Django 的开源内容管理系统CMS内置了完整的国际化体系Locale 语言环境负责登记站点支持哪些语言TranslatableMixin 则让每个内容对象按语言保存独立副本。读完这篇实践指南你能把现有后台改造成支持多市场的 Wagtail 多语言站点并跑通从添加语言、模型翻译到自动语言识别的完整链路。痛点一个后台服务六个市场假设你的产品刚进入法国和日本市场法语编辑抱怨法语页根本找不到每次都要问开发要链接客服被不同语言的工单轰炸却只能靠标题猜用户是哪个市场的。更麻烦的是早期方案是给每个国家复制一套 Django 项目结果改一个字段要同步改六遍运营完全无法自助。Wagtail 的思路是反过来的一个后台、一套数据、按语言存副本。语言不再属于服务器或域名而是内容本身的一个属性。原理速览两条主线撑起 Wagtail 多语言Wagtail 的国际化拆成两条主线理解它们之后所有功能都能对上号语言环境Locale一条language_code唯一记录回答这个站点允许哪些语言。列表由 settings 里的WAGTAIL_CONTENT_LANGUAGES决定增删改查都在 wagtail/locales/ 模块的后台视图里完成。内容翻译TranslatableMixin抽象基类给模型加上translation_key跨语言相同的 UUID和locale两个字段。同一篇文章的法语版和中文版是两条独立记录靠translation_key认出我们是一家人。说白了前者管字典后者管词条两者都就位后翻译界面才能正常工作。搭建路径三个任务跑通翻译链路任务一最快配置语言环境的方法语言清单写在settings.py里这是整个 wagtail locale 配置的唯一入口# settings.py声明站点内容语言第一项通常作为默认语言 WAGTAIL_CONTENT_LANGUAGES LANGUAGES [ (en, English), (fr, Français), (ja, 日本語), (zh-hans, 简体中文), ]然后在后台设置 → 语言里逐个添加或者在脚本里直接建# 代码方式批量创建语言环境language_code 必须与 settings 里一致 from wagtail.models import Locale Locale.objects.get_or_create(language_codefr)注意一个细节语言记录的创建和 settings 是解耦的改了WAGTAIL_CONTENT_LANGUAGES不等于后台立即多出语言按钮这是后面避坑第一条的主角。任务二让模型支持翻译Page子类天生带翻译能力真正需要动手的是 snippet 模型。继承TranslatableMixin后Django 会自动加上translation_key和locale字段# 模型类定义混入 TranslatableMixin 即获得 Django 内容翻译能力 from wagtail.models import TranslatableMixin class NewsBrief(TranslatableMixin, models.Model): body models.TextField(verbose_name正文) class Meta: constraints [ # 官方 check 要求保留该唯一约束删除会报错 wagtailcore.E003 models.UniqueConstraint( fields[translation_key, locale], nameunique_brief_locale ) ]别忘了makemigrationsmigrate新字段才会落库。字段定义在 wagtail/models/i18n.py 的TranslatableMixin中值得读一遍源码。任务三跑通创建翻译动作翻译不是改字段而是复制出一个新对象。标准入口是copy_for_translation# 把法语副本创建出来复制内容 换 locale后台同步留一条审计日志 page.fr_copy page.copy_for_translation( Locale.get_for_language(fr), exclude_fields[seo_title], # 不想照抄的字段列在这里 )之后每个语言版本就是一个普通对象独立编辑、独立发布、独立修订历史。列表页还能直接看到各语言的使用量统计实现在 wagtail/locales/utils.py 的get_locale_usage里——它会遍历所有可翻译模型数一数每种语言名下有多少页面和内容。进阶让站点更聪明自动识别访客语言不用让访客手动切语言wagtail.coreutils里现成的函数可以把浏览器设置映射成站点支持的变体# 把 Accept-Language 归一化为站点已启用的语言代码如 ja-jp - ja from wagtail.coreutils import get_supported_content_language_variant preferred request.META.get(HTTP_ACCEPT_LANGUAGE, en).split(,)[0] language get_supported_content_language_variant(preferred)匹配不上时它会按规则降级比如zh-hant落回zh不会抛异常可以放心放进中间件。给译文加一层缓存# 缓存键必须带语言维度否则 A 语言会读到 B 语言的译文 key fbody_{page.pk}_{locale.language_code} body cache.get_or_set(key, lambda: page.get_translation(locale).body, 3600)记得在内容保存信号里按语言键主动失效否则编辑改完半天不生效。照顾 RTL 排版阿拉伯语、希伯来语是右起书写。locale.language_info里自带rtl标记wagtail/models/i18n.py 中的属性渲染html时输出dir属性即可# 模板据此输出 html dirrtl再配一段 [dirrtl] 的全局 CSS 翻转方向 dir_attr rtl if locale.language_info[rtl] else ltr避坑三个高频翻车现场现象改了WAGTAIL_CONTENT_LANGUAGES后台却找不到新语言原因settings 只是白名单语言记录要单独存在Locale表里后台的添加按钮也会在所有配置语言都建齐后自动隐藏见 wagtail/locales/ 视图的_can_add_locale逻辑。解法改完 settings 后去后台设置 → 语言补建记录或在数据迁移里get_or_create批量补齐。现象翻译副本里混进了不该复制的字段原因copy_for_translation默认复制全部字段发布时间、SEO 元数据这类不该照抄的内容也一起搬了过去。解法始终显式传exclude_fields把站点级、非内容字段排除在外。现象删除语言环境被后台拒绝原因DeleteView有两道保护——最后一个语言不能删还有页面或内容挂在上面的语言不能删。解法先把这些内容迁移到其他语言或未发布统计数归零后再删别硬绕过。继续深入wagtail/locales/语言环境的视图、表单与使用统计源码wagtail/models/i18n.pyLocale与TranslatableMixin的完整定义wagtail/actions/copy_for_translation.py翻译副本动作的信号与递归复制实现docs/advanced_topics/i18n.md官方国际化文档含WAGTAIL_CONTENT_LANGUAGES全量说明【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考