Suitenumerique Docs项目中的前后端语言偏好统一方案

背景与问题分析

在Suitenumerique Docs项目中，开发团队发现了一个关于国际化(i18n)的有趣问题：前端界面和后端返回的错误信息经常出现语言不一致的情况。例如，当用户界面显示为法语时，某些文档标题却以英语呈现；或者当用户将界面语言设置为英语后，某些错误提示仍然固执地保持法语状态。

这种不一致性源于前后端系统采用了不同的语言检测机制。前端(Next.js)通过本地存储(localStorage)保存用户的语言偏好，而后端(Django)则依赖于HTTP头中的Accept-Language信息或默认语言设置。这种分离的机制导致了用户体验上的割裂。

技术解决方案

统一语言偏好的核心思路

为了解决这个问题，开发团队决定采用基于Cookie的统一语言偏好方案。这种方案的核心思想是：

1. 创建一个共享的Cookie(impress_language)来存储用户的语言偏好
2. 前端和后端都从这个Cookie中读取语言设置
3. 当用户切换语言时，同时更新这个Cookie

实现细节

在Django后端，配置了LANGUAGE_COOKIE_NAME设置为impress_language，这样Django就会优先从这个Cookie中获取语言设置，而不是依赖HTTP头。Django的语言检测顺序变为：

1. 首先检查impress_language Cookie
2. 如果没有找到，再检查Accept-Language HTTP头
3. 最后回退到全局的LANGUAGE_CODE设置

在前端Next.js应用中，移除了原有的localStorage实现，改为使用相同的impress_language Cookie来存储和读取语言偏好。这样确保了无论请求来自前端还是后端API，都能获得一致的语言体验。

技术优势

这种统一方案带来了几个显著优势：

1. 一致性：消除了前后端语言显示不一致的问题，提供统一的用户体验
2. 可维护性：简化了代码结构，前后端共享同一套语言检测逻辑
3. 灵活性：Cookie可以在不同页面间保持语言设置，而不会丢失
4. 兼容性：既支持Next.js的前端路由，也兼容Django的后端处理

实施考量

在实施过程中，开发团队最初考虑使用Next.js默认的NEXT_LOCALE Cookie，但发现它主要适用于URL路由场景，且当前项目并未使用URL模式的语言前缀。因此，最终选择了自定义的impress_language Cookie名称，这既保持了与框架的兼容性，又提供了足够的灵活性。

总结

通过引入共享Cookie机制，Suitenumerique Docs项目成功解决了前后端语言偏好不一致的问题。这种方案不仅适用于当前项目，也可以作为其他类似技术栈(Next.js + Django)项目的参考实现。它展示了在现代Web开发中，如何通过简单的技术调整来提升用户体验的一致性和完整性。