Wagtail StreamField区块名称翻译异常，寻求正确实现方案

你之前踩的坑在于混淆了StreamField中name的核心作用——这个参数是内部唯一标识符，用于模板调用、JSON存储等场景，必须严格遵循Python变量命名规范（小写、下划线分隔），绝对不能用翻译后的字符串（这也是用ugettext_lazy包裹name会触发KeyError的原因：翻译后的内容会变成非规范的键名，破坏了内部序列化逻辑）。

而管理界面中显示的区块名称，其实是由Block定义的label属性控制的，这才是需要做国际化翻译的部分！

具体实现步骤 #

1. 保持name为原始的、非翻译的标识符，确保符合命名规范；
2. 在定义每个Block时，通过label参数传入ugettext_lazy包裹的翻译文本；
3. 确保你的Django项目已经正确配置国际化（比如settings.py中开启USE_I18N = True，设置好LOCALE_PATHS路径等）。

代码示例 #

基础StreamField定义场景

from django.utils.translation import ugettext_lazy as _
from wagtail.fields import StreamField
from wagtail.blocks import CharBlock, RichTextBlock, ImageChooserBlock

class ArticlePage(Page):
    content = StreamField([
        # name保持原始标识符，label用翻译文本
        ('plain_text', CharBlock(label=_('Plain Text'))),
        ('formatted_text', RichTextBlock(label=_('Formatted Content'))),
        ('inline_image', ImageChooserBlock(label=_('Inline Image'))),
    ], use_json_field=True)

使用自定义StreamBlock的场景

from django.utils.translation import ugettext_lazy as _
from wagtail.fields import StreamField
from wagtail.blocks import StreamBlock, CharBlock, QuoteBlock

class ContentStreamBlock(StreamBlock):
    paragraph = CharBlock(label=_('Paragraph'))
    pull_quote = QuoteBlock(label=_('Pull Quote'))

class BlogPage(Page):
    body = StreamField(ContentStreamBlock(), use_json_field=True)

为什么之前的方法不生效？ #

• 用gettext包裹name：gettext会在代码加载时立即完成翻译，只能使用项目默认语言（settings.py中LANGUAGE_CODE指定的语言），无法跟随用户在管理界面切换的语言偏好；
• 用ugettext_lazy包裹name：name作为内部键，Wagtail会用它来序列化/反序列化StreamField的内容，翻译后的字符串可能包含特殊字符或空格，不符合键名规范，直接触发KeyError。

通过上述方法，管理界面的区块名称会根据用户的语言偏好动态切换，同时内部标识符保持稳定，不会破坏序列化逻辑。

内容的提问来源于stack exchange，提问作者user7346216