企业官网建设流程全解析

CVAT 多语言支持完整指南：三步给标注平台加上中文界面

【免费下载链接】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 多语言支持配置指南以加一门中文为例，带你从建语言包、改后端设置，讲到 Docker 部署与生效验证。读完后，你能给自己的实例加上任何一门新语言。

如何新增中文语言包：最快路径

结论先行：三步大约十分钟，一门新语言就能全链路跑通。所谓全链路，是指界面、API 消息、文档站三处都换成中文，而不只是按钮文案。

第一步：准备语言包。前端管界面文案，后端管 API 提示与报错，两边不共享文件，所以要各建一份。

# 前端语言包：放 UI 源码里，界面文案按这里的键取值 mkdir -p cvat-ui/src/locales touch cvat-ui/src/locales/zh.json # 后端翻译目录：Django 约定位置，存 .po 待翻文件和 .mo 编译结果 mkdir -p locale/zh_Hans/LC_MESSAGES

第二步：配置 Django 语言列表。打开 cvat/settings/base.py，改三处：

LANGUAGE_CODE = "zh-hans" # 默认语言：用户没选语言时回退到这里 LANGUAGES = [("en", "English"), ("zh-hans", "简体中文")] # 允许切换的语言白名单 # MIDDLEWARE 列表里补一行（CVAT 默认没启用它）： "django.middleware.locale.LocaleMiddleware" # 每个请求都识别当前语言

为什么是这三处：默认语言决定"没偏好"时的显示；白名单决定切换器里出现哪些选项；中间件负责把两者接到具体请求上。

第三步：重新编译并重启。

python manage.py makemessages -l zh_Hans # 把已标记的英文抽成中文待翻文件 # 人工填好 msgstr 列后： python manage.py compilemessages && docker compose restart

makemessages 会扫描代码里所有 gettext 标记，生成带格式提示的 .po 文件，你要做的只是把 msgstr 那一列填上中文。

CVAT 语言包长什么样：前端 JSON 结构

一句话结论：前端语言包就是两层 JSON——分组、键、译文，界面按"分组.键"取字。

{ "common": { "save": "保存", "cancel": "取消", "delete": "删除", "edit": "编辑" } }

分组名按模块划分（common、annotation、error 这类），键名用英文小写单词，别拿英文原文当键。不想逐条手写的话，可以先复制一份英文版语言包当骨架，再按分组补齐。切换机制的结论：用户在切换器里选一门语言，前端加载对应语言包，界面文案即时替换，无需刷新；某个键在这门语言里缺失时，该处自动回退英文，不报错，但回退比例高说明覆盖不够。

从全局看，CVAT 国际化由三套并行的体系组成：前端 JSON 语言包、后端 gettext 词条、文档站 TOML 文件，互不共享。官方文档站走的是 Hugo 体系，语言文件放在 site/i18n/en.toml 这个目录，新增语言时这里也要补一份，否则文档站永远只有英文。

CVAT i18n 配置在后端：消息如何被翻译

结论先行：后端翻译 = 配置决定"用哪门语言" + 标记决定"哪些字能翻"，两者缺一不可，且都落在 cvat/settings/base.py 和业务代码里。

三个配置项各管一段：

• LANGUAGE_CODE：默认语言基线，请求没带语言偏好时回退到它。
• LANGUAGES：可切换语言白名单，语言切换器通常就按它生成。
• LocaleMiddleware：每个请求从 Accept-Language 头里解析出当前语言的中间件。CVAT 默认的 MIDDLEWARE 列表里没有它，必须手动补上。

标记字符串用 gettext 系列函数，仓库里 engine 等模块已经在用gettext_lazy做标记，所以 makemessages 能直接抽到现成词条：

from django.utils.translation import gettext as _ def after_save(self): # %(name)s 是占位符：编译时保留原样，运行期再填参 return _("Task %(name)s saved") % {"name": self.name}

标记要打在用户看得见的字面上，日志文案不用标；带参数的句子用%(name)s占位符，别用 f-string 拼接，否则抽取不到完整句式。

CVAT 多语言部署：Docker 里该设哪些语言变量

结论先行：容器化部署只多传几个环境变量，后端管默认语言，前端管可选语言。

需要说明：仓库里 LANGUAGE_CODE 的默认值是写死的，上面两个自定义变量要靠你的 settings 扩展去读取，所以先建一个继承 production 的小扩展文件。compose 文件里只保留语言相关部分：

services: cvat: environment: - DJANGO_SETTINGS_MODULE=cvat.settings.production - CVAT_DEFAULT_LANGUAGE=zh-hans # 后端默认中文 cvat_ui: environment: - CVAT_SUPPORTED_LANGUAGES=en,zh-hans # 前端只展示两种语言

docker compose up -d之后，等两个服务都 healthy 再进浏览器验证。

怎么确认翻译真的生效了

结论先行：三个可操作的动作，五分钟验证全链路。

1. 打开前端把界面语言切到中文，看顶部菜单、按钮、对话框文案是否全部替换，有没有英文残留。
2. 做一件带参量的操作，比如保存一次标注，检查成功提示里的变量（任务名之类）是否正确填入，而不是显示%s或None。
3. 故意触发一条 API 报错，比如用无权限的账号请求，看响应里的 403 消息文案是不是中文，而不是通用的 Django 报错。

两个最常见的坑：漏翻的词条会自动回退英文，看到中英混排先查键缺失，别怀疑部署；.po 文件改完必须跑一次 compilemessages，否则容器里用的还是旧的 .mo，你会以为改动没生效。

上线之后的维护要点

结论先行：加语言是十分钟的事，让它别和代码脱节才是长期成本。

• 新增界面文案时同步提交语言包，别等发布后才发现漏翻。
• 每次发版前跑一遍 makemessages，对照新抽出来的英文串补翻译。
• 前端 JSON 语言包和后端 .po 是两套体系，切换验证时分开测，别只测一边。

开头那两位日本和俄罗斯同事，现在打开标注页看到的就是各自母语。下次想加韩语或西语，照这三步复制一遍即可。

【免费下载链接】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