企业官网建设流程全解析

CVAT 多语言配置教程：3 步支持中文界面

【免费下载链接】cvatComputer Vision Annotation Tool (CVAT) is a leading platform for building high-quality visual datasets for vision AI. It offers open-source, cloud, and enterprise products, as well as labeling services, for image, video, and 3D annotation with AI-assisted labeling, quality assurance, team collaboration, analytics, and developer APIs.项目地址: https://gitcode.com/GitHub_Trending/cvat/cvat

海外同事打开 CVAT 抱怨界面全是英文？这篇指南带你走通 CVAT 国际化（i18n）配置：后端怎么开、语言包怎么加、不生效怎么排查，按顺序做完，标注平台就能说你们团队的语言。

场景：海外用户打开界面全是英文

打开标注页，工具栏、菜单、报错提示清一色英文，国内团队却想先看中文标签。先说清楚现状：CVAT 的多语言能力分布在三层——Django 后端（报错与 API 文案）、Hugo 文档站（site/i18n/下的词条）、React 前端（当前为英文硬编码，无内置语言包）。三层里只有前两层开箱即用，前端要加语言属于"补装"动作。后面按任务顺序做，不用一次啃完三层。

字符串怎么到屏幕上：一条单向链路

链路是单向的：语言包 → 翻译标记 → 运行时渲染。界面上每个可翻译的字符串，先由开发者用标记函数圈出来，再被提取进语言包，最后渲染时按请求语言取对应词条。你配置多语言，本质就是维护这条链路上"语言包"这一环。


最快启用方式：按部署线改 3 处

第 1 步：确认后端 i18n 开关。打开 cvat/settings/base.py，国际化段落长这样：

# cvat/settings/base.py LANGUAGE_CODE = "en-us" # 回退语言：用户语言缺翻译时显示什么 USE_I18N = True # 总开关，仓库默认已开启

USE_I18N不用动。LANGUAGE_CODE默认选en-us并保持不变——它只是兜底语言，让用户的Accept-Language驱动界面语言，这样多地区团队互不影响。

第 2 步：核对环境变量与配置项。

第 3 步：重启服务让配置生效。

docker compose restart cvat

到这里，API 报错、邮件通知类文案已按请求语言输出；界面按钮菜单还是英文，继续下一节。

新增一门语言的完整闭环：以中文为例

以"给后端加简体中文"为主线，四步闭环：提取 → 翻译 → 编译 → 验证。

语言包最终落在这样的目录里（以zh_Hans为例）：

cvat/locale/ └── zh_Hans/LC_MESSAGES/ ├── django.po # 翻译源文件，人工编辑的就是它 └── django.mo # 编译后的二进制，运行时真正读的是它

第 1 步，提取所有可翻译字符串：

python manage.py makemessages -l zh_Hans python manage.py compilemessages

第 2 步，打开生成的cvat/locale/zh_Hans/LC_MESSAGES/django.po，把msgid（英文原文）对应的msgstr填成中文。没把握的词条留空即可，Django 会自动回退英文，不会报错。

第 3 步，compilemessages生成.mo。第 4 步，重启后用请求头验证：

docker compose restart cvat curl -s -H "Accept-Language: zh-Hans" http://127.0.0.1/api/about/version

再发一条会触发报错文案的请求（比如用错误 token 调 API），响应里出现中文即闭环完成。

排错 ⚠️：语言不生效、翻译缺失、切换延迟

Q1：明明填了翻译，为什么还是英文？按顺序定位三处：一是ls cvat/locale/zh_Hans/LC_MESSAGES/，没有.mo或它比.po旧，就是漏了编译，重跑compilemessages；二是抓请求头，浏览器或代理可能没带上Accept-Language: zh-Hans，用上面的curl单独验证可排除前端因素；三是改完 settings 没重启服务，Django 配置在启动时加载。

Q2：个别词条没翻译，界面显示什么？默认回退到LANGUAGE_CODE对应的英文原文，不会显示键名或空白——这是预期行为，直接保持默认即可。如果你希望"宁缺毋滥"地强制中文，把LANGUAGE_CODE改成zh-hans让未翻译部分也尽量走中文，代价是所有用户缺词时都看到中文，不建议多团队环境这么做。

Q3：切换语言要刷新很久？先分清两层：后端无状态，换Accept-Language立即生效，不存在延迟；如果前端做了客户端语言包懒加载，首次切语言要等包下载。默认建议：首屏只预载当前语言 + 英文兜底两包，其余语言按需加载并缓存在内存，切换体感即可做到即时。

进阶：浏览器语言自动检测与语言包懒加载

后端这块什么都不用做：Django 读请求的Accept-Language自动匹配，浏览器默认就会带上。前端则要先补基建——cvat-ui/src/ 目前没有语言包，想拿到中文界面，引入 i18next 这类库，把词条按命名空间拆分放在cvat-ui/src/locales/，例如新建cvat-ui/src/locales/zh.json：

{ "workspace": { "objects": "对象", "labels": "标签" }, "common": { "save": "保存", "cancel": "取消" } }

语言检测逻辑默认选"localStorage 用户选择 > 浏览器语言 > en"，首次访问用navigator.language命中支持列表就静默应用，不再弹选择框。懒加载按语言维度动态import对应 JSON，配合Map缓存，加载失败回退英文包，避免首屏被语言包拖慢。

部署前检查清单

到这里，CVAT 国际化的三块拼图就齐了：后端按Accept-Language输出翻译文案，语言包走"提取—翻译—编译"闭环，前端按需补包。上线前跑一遍这三项，基本不会翻车：

• ✅ 每种语言的django.mo都存在，且时间戳不早于对应.po
• ✅ 用curl -H "Accept-Language: …"分别命中中英文，确认报错文案随语言切换
• ✅ 前端语言包目录里的语言代码与后端 locale 目录一一对应，避免"后端中文、前端仍英文"的割裂感

【免费下载链接】cvatComputer Vision Annotation Tool (CVAT) is a leading platform for building high-quality visual datasets for vision AI. It offers open-source, cloud, and enterprise products, as well as labeling services, for image, video, and 3D annotation with AI-assisted labeling, quality assurance, team collaboration, analytics, and developer APIs.项目地址: https://gitcode.com/GitHub_Trending/cvat/cvat