Docs 应用语言配置完全指南：DJANGO_LANGUAGES 覆盖机制、翻译管理与 Cookie 行为

Docs 应用语言配置完全指南DJANGO_LANGUAGES 覆盖机制、翻译管理与 Cookie 行为【免费下载链接】docsDocs is an open-source text editor: web-native, made for real-time collaboration, cleanly structured documents and sub-documents with full ownership of your data. Built to scale with Django and React.项目地址: https://gitcode.com/GitHub_Trending/docs150/docs导读本文基于 Docs 官方文档 languages-configuration.md系统讲解如何配置与覆盖 Docs基于 Django React 的开源协作文档应用所支持的语言列表。你将掌握默认语言清单及其优先级语义、通过DJANGO_LANGUAGES环境变量在开发/生产/Docker Compose 三种场景下覆盖语言的方式、语言代码与翻译文件的对应关系以及语言偏好如何在前后端之间通过docs_languageCookie 与用户 Profile 同步并附带源码级实现佐证与排障清单。默认语言与源码定义Docs 默认支持 5 种语言按优先级从高到低排列Englishen-usFrançaisfr-frDeutschde-deNederlandsnl-nlEspañoles-es该默认值定义在 src/backend/impress/settings.py# Careful! Languages should be ordered by priority, as this tuple is used to get # fallback/default languages throughout the app. LANGUAGES values.SingleNestedTupleValue( ( (en-us, English), (fr-fr, Français), (de-de, Deutsch), (nl-nl, Nederlands), (es-es, Español), ) )注意代码注释中强调的优先级语义这个元组的顺序就是语言优先级第一个语言会被整个应用用作回退fallback语言。也就是说当某个界面缺少某种语言的翻译时应用会回退到列表首位的en-us。围绕这个设置仓库中有多处消费点可以印证其作用范围用户模型的语言字段直接以settings.LANGUAGES作为可选值src/backend/core/models.pychoicessettings.LANGUAGES序列化器对language字段使用choiceslazy(lambda: settings.LANGUAGES, tuple)()做校验默认值取settings.LANGUAGE_CODEsrc/backend/core/api/serializers.py邮件、AI 服务等内部模块在需要“未指定语言”时回退到settings.LANGUAGE_CODEsrc/backend/core/tasks/mail.py、src/backend/core/services/ai_services/legacy.py工厂数据生成测试/演示环境会从settings.LANGUAGES中随机抽取语言src/backend/core/factories.pycreate_demo命令也读取settings.LANGUAGES来构建演示数据src/backend/demo/management/commands/create_demo.py。通过 DJANGO_LANGUAGES 覆盖语言列表官方推荐的方式是不改源码仅通过DJANGO_LANGUAGES环境变量覆盖语言配置。得益于 Django 的 django-environ 风格取值values.SingleNestedTupleValue环境变量优先级高于 settings.py 中的默认值且变量名自动映射为DJANGO_LANGUAGES。格式说明DJANGO_LANGUAGES使用分号分隔多组语言每组内部用逗号连接「语言代码,显示名称」DJANGO_LANGUAGEScode1,Name1;code2,Name2;code3,Name3语言代码遵循language-region格式全部小写如en-us、fr-fr、de-de显示名称建议使用该语言母语拼写如Français、Deutsch因为语言选择器会直接展示这些名称详见下文前端 LanguagePicker 分析。配置示例示例 1仅保留英文与法文DJANGO_LANGUAGESen-us,English;fr-fr,Français示例 2新增意大利语与简体中文DJANGO_LANGUAGESen-us,English;fr-fr,Français;de-de,Deutsch;it-it,Italiano;zh-cn,中文示例 3自定义子集法/德/西DJANGO_LANGUAGESfr-fr,Français;de-de,Deutsch;es-es,Español注意当fr-fr排在首位时它同时成为全局回退语言——这符合“第一个语言即回退语言”的优先级规则。各环境的配置落点开发环境开发配置目录为env.d/development/其中公共文件为 env.d/development/common。官方文档示例写入env.d/development/common.local该文件不会入库适合个人本地覆盖写法为DJANGO_LANGUAGESen-us,English;fr-fr,Français;de-de,Deutsch;it-it,Italiano;zh-cn,中文;开发环境通过 docker-composecompose.yml启动时环境变量会注入到后端容器中。生产环境生产配置模板位于env.d/production.dist/对应的公共文件为 env.d/production.dist/common。在部署时如 deployment/paas 或 Helm 部署把如下变量加入生产环境配置DJANGO_LANGUAGESen-us,English;fr-fr,FrançaisDocker Compose使用 Docker Compose 时可直接在compose.yml或compose.override.yml的app服务中注入环境变量services: app: environment: - DJANGO_LANGUAGESen-us,English;fr-fr,Français;de-de,Deutsch语言配置如何传导到前端Docs 采用前后端分离架构Django 后端 React/Next.js 前端语言配置会通过配置 API 传导到前端后端配置接口/api/v1.0/config/将LANGUAGES与LANGUAGE_CODE一并返回给前端src/backend/core/api/viewsets.pyarray_settings白名单中包含LANGUAGES与LANGUAGE_CODE前端通过useConfig拉取该配置类型定义确认LANGUAGES: [string, string][]src/frontend/apps/impress/src/core/config/api/useConfig.tsx语言选择器LanguagePicker直接渲染conf?.LANGUAGES作为下拉选项并展示每个语言的显示名称src/frontend/apps/impress/src/features/language/components/LanguagePicker.tsx区域设置locale解析逻辑按“已解析语言”从配置的 LANGUAGES 中匹配对应代码并规范化为xx-XX形式供 UI 组件库使用src/frontend/apps/impress/src/i18n/useLocale.ts。此外前端还维护一份独立于后端的可用语言清单i18n.options.resources即translations.json中包含的语言前后端语言会做“就近匹配”同步getMatchingLocales见 src/frontend/apps/impress/src/features/language/hooks/useSynchronizedLanguage.ts。这意味着后端DJANGO_LANGUAGES控制了“语言选择器里能选什么”而前端翻译资源决定了“选了之后界面是否真的有译文”——两者需要配合使用。语言代码规范与可用语言清单编码规范使用标准语言代码ISO 639-1 语言码 可选区域码格式language-region全部小写如en-us、fr-fr、de-de不要使用目录名那种下划线大写格式fr_FR。后端翻译资源现状后端翻译文件位于 src/backend/locale/每个语言一个目录LC_MESSAGES/django.po。以下是仓库中已确认存在的语言及对应的配置代码写法目录名语言DJANGO_LANGUAGES 代码br_FR布列塔尼语法国br-frde_DE德语德国de-deen_US英语美国en-useo_PL世界语eo-ples_ES西班牙语西班牙es-esfr_FR法语法国fr-frit_IT意大利语意大利it-itnl_NL荷兰语荷兰nl-nlpt_PT葡萄牙语葡萄牙pt-ptru_RU俄语俄罗斯ru-rusl_SI斯洛文尼亚语斯洛文尼亚sl-sisv_SE瑞典语瑞典sv-setr_TR土耳其语土耳其tr-truk_UA乌克兰语乌克兰uk-uazh_CN简体中文中国zh-cnzh_TW繁体中文台湾zh-tw重要提示配置DJANGO_LANGUAGES时务必使用小写加连字符格式如pt-pt、ru-ru而不是目录名格式pt_PT。在新增语言之前请确认三点后端存在对应语言的翻译文件src/backend/locale/language_code/LC_MESSAGES/前端存在对应语言的翻译资源src/frontend/apps/impress/src/i18n/translations.json所需消息均已翻译完整。值得注意的是settings.LANGUAGES与“全量语言清单”是两个概念后端还维护了一个不受LANGUAGES限制的全量语言映射ALL_LANGUAGES源自 Django 全局设置用于用户 Profile、AI 代理等场景中展示任意语言名称src/backend/core/enums.py。也就是说DJANGO_LANGUAGES收窄的是“应用内可切换的语言”而全量语言清单仍然可以用于识别和展示语言名。翻译管理CrowdinDocs 项目使用 Crowdin 以对接该平台。想新增语言或改进现有翻译请联系项目维护者将新语言加入 Crowdin 项目后由社区协作完成翻译翻译文件采用标准 gettext 格式django.po支持 Django 生态的makemessages/compilemessages工作流。Cookie 与会话中的语言偏好用户的语言偏好存储在一个名为docs_language的 Cookie 中后端默认配置src/backend/impress/settings.pyLANGUAGE_CODE en-us默认语言代码LANGUAGE_COOKIE_NAME docs_languageCookie 名称LANGUAGE_COOKIE_PATH /Cookie 路径默认覆盖全站。前端 i18next 的语言检测顺序为「Cookie → 浏览器 navigator 语言」同样读取名为docs_language的 Cookie并回写该 Cookie有效期为 525600 分钟即一年sameSite: lax、路径/src/frontend/apps/impress/src/i18n/initI18n.ts。前端回退语言为ensrc/frontend/apps/impress/src/i18n/config.ts。登录用户的语言偏好还会同步到用户 Profile切换语言时前端调用用户更新接口把language字段写入后端用户模型useSynchronizedLanguage.ts这样同一账号在多设备/浏览器上可以保持语言一致未登录时则依赖docs_languageCookie。后端在生成邮件等场景取语言时也遵循user.language or settings.LANGUAGE_CODE的优先级src/backend/core/tasks/mail.py。修改语言配置后的验证步骤重启应用相关服务环境变量在进程启动时读取需重启才能生效打开前端界面确认语言选择器中显示的语言列表与DJANGO_LANGUAGES一致前端会从后端/config/接口拉取该列表依次切换不同语言确认界面文案即时变化刷新页面 / 新开浏览器访问确认所选语言被持久化docs_languageCookie 生效若已登录可在另一台设备/浏览器登录同一账号确认语言偏好随账号同步。后端配置接口的期望返回可在测试中验证src/backend/core/tests/test_api_config.py 断言了默认LANGUAGES与LANGUAGE_CODE的返回结构可作为本地验证的参照。故障排查语言没有出现在选择器中检查环境变量格式分号分隔语言组、组内用逗号连接「代码,名称」检查语言代码与名称中不能有尾随空格如en-us,English末尾的空格会导致解析异常确认修改配置后应用已重启确认前端能正常拉到/config/接口的LANGUAGES字段可用浏览器 DevTools 查看网络请求。出现未翻译文本语言混杂如果你新增了语言但看到英文或其他语言混杂检查后端翻译文件是否存在src/backend/locale/language_code/LC_MESSAGES/运行 Django 命令生成/更新并编译翻译# 生成/更新 .po 文件 python manage.py makemessages -l language_code # 编译 .mo 文件 python manage.py compilemessages确认前端translations.json中包含对应语言的翻译资源前端语言资源由 src/frontend/packages/i18n 工具链生成/管理。语言回退不符合预期回退语言始终是DJANGO_LANGUAGES列表的第一项若你希望回退到英语请将en-us放在列表首位前端 i18next 的 fallback 是en若后端回退语言被改成非英语需注意前后端回退策略的差异后端以LANGUAGE_CODE/列表首项为准前端固定以en兜底。相关配置项速查配置项默认值说明LANGUAGE_CODEen-us应用默认语言代码未指定用户偏好时的兜底LANGUAGE_COOKIE_NAMEdocs_language存储语言偏好的 Cookie 名称LANGUAGE_COOKIE_PATH/Cookie 作用路径LANGUAGES/DJANGO_LANGUAGES(en-us, fr-fr, de-de, nl-nl, es-es)可用语言列表有序首项为回退语言小结Docs 的语言配置核心是一条链路DJANGO_LANGUAGES环境变量 → Djangosettings.LANGUAGES→/config/配置接口 → 前端语言选择器与 i18next同时通过docs_languageCookie 与用户 Profile 完成语言偏好的持久化与跨端同步。掌握这一机制后你可以在不改一行代码的情况下灵活地为 Docs 定制语言子集、新增语言或调整回退优先级并借助本文的验证与排障清单快速定位问题。【免费下载链接】docsDocs is an open-source text editor: web-native, made for real-time collaboration, cleanly structured documents and sub-documents with full ownership of your data. Built to scale with Django and React.项目地址: https://gitcode.com/GitHub_Trending/docs150/docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考