为何Django自定义唯一约束错误消息未生效？如何本地化？

你遇到的情况是因为Django字段定义里的error_messages只会在模型校验阶段生效，而直接调用save()方法时，Django不会自动执行唯一性校验，而是直接将SQL语句发送给数据库。当数据库检测到重复键时，会抛出底层的UniqueViolation异常，此时不会触发字段定义中配置的自定义错误消息。

以下几种方式可以实现你想要的本地化错误提示效果：

1. 使用ModelForm处理数据提交 #

如果是通过表单接收用户输入，直接使用ModelForm即可自动触发模型的完整校验逻辑，包括唯一性检查，此时会返回你配置的自定义本地化错误消息：

from django import forms
from .models import Foo

class FooForm(forms.ModelForm):
    class Meta:
        model = Foo
        fields = ['email']

在视图中使用这个表单时，表单会自动处理校验，当邮箱重复时，form.errors中会包含你定义的错误消息，且gettext_lazy会根据当前语言环境自动转换。

2. 手动调用模型的full_clean()方法 #

如果直接操作模型实例而不使用表单，需要在调用save()之前手动执行full_clean()，触发模型的校验逻辑：

foo_instance = Foo(email="existing@example.com")
try:
    foo_instance.full_clean()  # 执行完整校验，包括唯一性检查
    foo_instance.save()
except ValidationError as e:
    # 这里可以获取到自定义的错误消息
    print(e.message_dict['email'])

这种方式会在应用层面先做唯一性检查，避免直接触发数据库异常，同时返回配置的本地化错误消息。

3. 捕获数据库异常并转换为自定义错误 #

考虑到并发场景（比如两个请求同时提交相同邮箱，full_clean()都通过，但第一个请求先完成保存，第二个请求save()时触发数据库异常），可以捕获数据库的唯一性异常，转换为Django的ValidationError并返回自定义消息：

from django.db import IntegrityError, models
from django.core.exceptions import ValidationError
import psycopg2

class Foo(models.Model):
    email = models.EmailField(
        max_length=255, 
        unique=True, 
        default=None, 
        blank=True,
        null=True, 
        verbose_name=gettext_lazy('email address'), 
        error_messages={'unique': gettext_lazy("Email address is already registered to another user.")}
    )

    def save(self, *args, **kwargs):
        try:
            super().save(*args, **kwargs)
        except IntegrityError as e:
            # 判断是否是邮箱字段的唯一性约束异常
            if isinstance(e.__cause__, psycopg2.errors.UniqueViolation) and 'foo_email_key' in str(e):
                raise ValidationError(
                    {'email': [self._meta.get_field('email').error_messages['unique']]}
                ) from e
            # 其他类型的IntegrityError原样抛出
            raise

确保你的Django项目已经正确配置本地化支持：

• 在settings.py中设置LANGUAGES、LOCALE_PATHS
• 启用LocaleMiddleware中间件
• 已编译对应语言的po/mo文件

只要满足以上配置，gettext_lazy包裹的错误消息会自动根据当前请求的语言环境切换显示内容。

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