企业官网建设流程全解析

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 种语言，按优先级从高到低排列：

1. English（en-us）
2. Français（fr-fr）
3. Deutsch（de-de）
4. Nederlands（nl-nl）
5. Español（es-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.py（choices=settings.LANGUAGES）；
• 序列化器对language字段使用choices=lazy(lambda: settings.LANGUAGES, tuple)()做校验，默认值取settings.LANGUAGE_CODE：src/backend/core/api/serializers.py；
• 邮件、AI 服务等内部模块在需要“未指定语言”时回退到settings.LANGUAGE_CODE：src/backend/core/tasks/mail.py、src/backend/core/services/ai_services/legacy.py；
• 工厂数据生成（测试/演示环境）会从settings.LANGUAGES中随机抽取语言：src/backend/core/factories.py；
• create_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_LANGUAGES=code1,Name1;code2,Name2;code3,Name3

• 语言代码遵循language-region格式，全部小写（如en-us、fr-fr、de-de）；
• 显示名称建议使用该语言母语拼写（如Français、Deutsch），因为语言选择器会直接展示这些名称（详见下文前端 LanguagePicker 分析）。

配置示例

示例 1：仅保留英文与法文

DJANGO_LANGUAGES=en-us,English;fr-fr,Français

示例 2：新增意大利语与简体中文

DJANGO_LANGUAGES=en-us,English;fr-fr,Français;de-de,Deutsch;it-it,Italiano;zh-cn,中文

示例 3：自定义子集（法/德/西）

DJANGO_LANGUAGES=fr-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_LANGUAGES=en-us,English;fr-fr,Français;de-de,Deutsch;it-it,Italiano;zh-cn,中文;

开发环境通过 docker-compose（compose.yml）启动时，环境变量会注入到后端容器中。

生产环境

生产配置模板位于env.d/production.dist/，对应的公共文件为 env.d/production.dist/common。在部署时（如 deployment/paas 或 Helm 部署）把如下变量加入生产环境配置：

DJANGO_LANGUAGES=en-us,English;fr-fr,Français

Docker Compose

使用 Docker Compose 时，可直接在compose.yml或compose.override.yml的app服务中注入环境变量：

services: app: environment: - DJANGO_LANGUAGES=en-us,English;fr-fr,Français;de-de,Deutsch

语言配置如何传导到前端

Docs 采用前后端分离架构（Django 后端 + React/Next.js 前端），语言配置会通过配置 API 传导到前端：

1. 后端配置接口/api/v1.0/config/将LANGUAGES与LANGUAGE_CODE一并返回给前端：src/backend/core/api/viewsets.py（array_settings白名单中包含LANGUAGES与LANGUAGE_CODE）；
2. 前端通过useConfig拉取该配置，类型定义确认LANGUAGES: [string, string][]：src/frontend/apps/impress/src/core/config/api/useConfig.tsx；
3. 语言选择器（LanguagePicker）直接渲染conf?.LANGUAGES作为下拉选项，并展示每个语言的显示名称：src/frontend/apps/impress/src/features/language/components/LanguagePicker.tsx；
4. 区域设置（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时务必使用小写加连字符格式（如pt-pt、ru-ru），而不是目录名格式（pt_PT）。

在新增语言之前请确认三点：

1. 后端存在对应语言的翻译文件：src/backend/locale/<language_code>/LC_MESSAGES/；
2. 前端存在对应语言的翻译资源（src/frontend/apps/impress/src/i18n/translations.json）；
3. 所需消息均已翻译完整。

值得注意的是，settings.LANGUAGES与“全量语言清单”是两个概念：后端还维护了一个不受LANGUAGES限制的全量语言映射ALL_LANGUAGES（源自 Django 全局设置），用于用户 Profile、AI 代理等场景中展示任意语言名称：src/backend/core/enums.py。也就是说，DJANGO_LANGUAGES收窄的是“应用内可切换的语言”，而全量语言清单仍然可以用于识别和展示语言名。

翻译管理（Crowdin）

Docs 项目使用 Crowdin 以对接该平台。

• 想新增语言或改进现有翻译：请联系项目维护者，将新语言加入 Crowdin 项目后，由社区协作完成翻译；
• 翻译文件采用标准 gettext 格式（django.po），支持 Django 生态的makemessages/compilemessages工作流。

Cookie 与会话中的语言偏好

用户的语言偏好存储在一个名为docs_language的 Cookie 中：

• 后端默认配置（src/backend/impress/settings.py）：

  • LANGUAGE_CODE = "en-us"：默认语言代码；
  • LANGUAGE_COOKIE_NAME = "docs_language"：Cookie 名称；
  • LANGUAGE_COOKIE_PATH = "/"：Cookie 路径，默认覆盖全站。

• 前端 i18next 的语言检测顺序为「Cookie → 浏览器 navigator 语言」，同样读取名为docs_language的 Cookie，并回写该 Cookie（有效期为 525600 分钟，即一年，sameSite: lax、路径/）：src/frontend/apps/impress/src/i18n/initI18n.ts。

• 前端回退语言为en：src/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。

修改语言配置后的验证步骤

1. 重启应用相关服务（环境变量在进程启动时读取，需重启才能生效）；
2. 打开前端界面，确认语言选择器中显示的语言列表与DJANGO_LANGUAGES一致（前端会从后端/config/接口拉取该列表）；
3. 依次切换不同语言，确认界面文案即时变化；
4. 刷新页面 / 新开浏览器访问，确认所选语言被持久化（docs_languageCookie 生效）；
5. 若已登录，可在另一台设备/浏览器登录同一账号，确认语言偏好随账号同步。

后端配置接口的期望返回可在测试中验证：src/backend/core/tests/test_api_config.py 断言了默认LANGUAGES与LANGUAGE_CODE的返回结构，可作为本地验证的参照。

故障排查

语言没有出现在选择器中

• 检查环境变量格式：分号分隔语言组、组内用逗号连接「代码,名称」；
• 检查语言代码与名称中不能有尾随空格（如en-us,English末尾的空格会导致解析异常）；
• 确认修改配置后应用已重启；
• 确认前端能正常拉到/config/接口的LANGUAGES字段（可用浏览器 DevTools 查看网络请求）。

出现未翻译文本（语言混杂）

如果你新增了语言但看到英文或其他语言混杂：

1. 检查后端翻译文件是否存在：src/backend/locale/<language_code>/LC_MESSAGES/；
2. 运行 Django 命令生成/更新并编译翻译：

# 生成/更新 .po 文件 python manage.py makemessages -l <language_code> # 编译 .mo 文件 python manage.py compilemessages

3. 确认前端translations.json中包含对应语言的翻译资源（前端语言资源由 src/frontend/packages/i18n 工具链生成/管理）。

语言回退不符合预期

• 回退语言始终是DJANGO_LANGUAGES列表的第一项，若你希望回退到英语，请将en-us放在列表首位；
• 前端 i18next 的 fallback 是en，若后端回退语言被改成非英语，需注意前后端回退策略的差异（后端以LANGUAGE_CODE/列表首项为准，前端固定以en兜底）。

相关配置项速查

小结

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