如何快速实现doccano国际化：完整i18n架构与翻译工作流指南

【免费下载链接】doccano Open source annotation tool for machine learning practitioners. 项目地址: https://gitcode.com/gh_mirrors/do/doccano

doccano是一款面向机器学习从业者的开源标注工具，提供了直观的界面和强大的标注功能。本文将深入解析doccano的国际化架构，帮助开发者快速掌握其i18n实现原理与翻译工作流管理方法，轻松构建多语言支持的标注平台。

一、doccano国际化架构概览

doccano采用前后端分离的国际化方案，前端基于Nuxt.js的i18n模块实现多语言切换，后端通过Django的国际化框架提供API支持。这种架构设计确保了用户界面和系统消息都能无缝支持多种语言。

1.1 核心技术栈

• 前端：Nuxt.js + vue-i18n
• 后端：Django Internationalization
• 翻译文件格式：JavaScript模块（前端）、PO文件（后端）

1.2 支持语言列表

doccano当前支持四种语言，可在frontend/i18n/index.js中查看完整配置：

• 英语（en）
• 中文（zh）
• 法语（fr）
• 德语（de）

二、前端国际化实现详解

2.1 语言配置系统

前端国际化的核心配置文件位于frontend/i18n/index.js，定义了支持的语言列表、默认语言、文件路径等关键信息：

export default {
  locales: [
    { name: 'English', code: 'en', iso: 'en-CA', file: 'en' },
    { name: '中文', code: 'zh', iso: 'zh-CN', file: 'zh' },
    { name: 'Français', code: 'fr', iso: 'fr-CA', file: 'fr' },
    { name: 'Deutsch', code: 'de', iso: 'de-DE', file: 'de' }
  ],
  lazy: true,
  langDir: 'i18n/',
  defaultLocale: 'en',
  vueI18n: { fallbackLocale: 'en' }
}

2.2 翻译文件组织结构

翻译文件采用模块化结构，按语言和功能模块分类存放于frontend/i18n/目录：

i18n/
├── en/
│   ├── generic.js
│   ├── header.js
│   ├── projects/
│   │   ├── annotation.js
│   │   ├── create.js
│   │   └── ...
│   └── ...
├── zh/
├── fr/
└── de/

每个语言目录下包含通用翻译（generic.js）和按功能模块划分的翻译文件，例如frontend/i18n/zh/generic.js定义了通用按钮和操作的中文翻译：

export default {
  continue: '继续',
  yes: '是',
  all: '全部',
  save: '保存',
  edit: '编辑',
  create: '创建',
  cancel: '取消',
  close: '关闭',
  upload: '上传',
  add: '增加',
  delete: '删除',
  deleteAll: '全部删除',
  search: '搜索',
  name: '名称',
  import: '导入',
  export: '导出',
  description: '描述',
  type: '类型',
  loading: '加载中... 请等待'
}

2.3 组件中的翻译使用

在Vue组件中使用$t方法访问翻译内容，例如项目创建页面的标题翻译：

<h1>{{ $t('projects.create.title') }}</h1>

三、翻译工作流管理

3.1 新增翻译项流程

1. 确定翻译键：遵循模块.页面.元素的命名规范
2. 更新翻译文件：在对应语言的JS文件中添加翻译键值对
3. 组件中应用：使用$t('键名')在模板中引用
4. 测试验证：切换语言查看翻译效果

3.2 翻译文件维护最佳实践

• 保持键名一致：所有语言文件使用相同的键名
• 模块化组织：按功能模块拆分翻译文件
• 定期同步：新增功能时同步更新所有语言文件
• 使用注释：为复杂翻译项添加注释说明上下文

四、界面语言切换功能

doccano提供了直观的语言切换界面，用户可以通过右上角的语言选择器随时切换界面语言。

图：doccano登录页面展示了语言切换下拉菜单

语言切换功能通过Nuxt-i18n的$i18n.setLocale方法实现，相关逻辑位于frontend/components/layout/LocaleMenu.vue组件中。

五、扩展支持新语言

要为doccano添加新的语言支持，只需完成以下步骤：

1. 在frontend/i18n/index.js的locales数组中添加新语言配置
2. 在frontend/i18n/目录下创建对应语言的目录（如ja/）
3. 复制现有语言的翻译文件到新目录并进行翻译
4. 在后端Django项目中添加对应语言的PO文件
5. 测试新语言的显示效果

六、国际化常见问题解决

6.1 翻译不生效

• 检查翻译键是否正确
• 确认语言文件路径和文件名是否正确
• 清除浏览器缓存或使用nuxt dev重新编译

6.2 格式问题

• 使用$t('key', { variable: value })处理带变量的翻译
• 注意保持HTML标签在翻译中的正确格式

6.3 RTL（从右到左）语言支持

对于阿拉伯语、希伯来语等RTL语言，需要额外添加CSS样式支持：

[dir="rtl"] {
  direction: rtl;
  text-align: right;
}

总结

doccano的国际化架构设计灵活且易于扩展，通过Nuxt-i18n和Django国际化框架的结合，实现了前端界面和后端API的全面多语言支持。遵循本文介绍的翻译工作流和最佳实践，开发者可以轻松维护现有语言翻译或扩展支持新的语言，为全球用户提供更加友好的标注体验。

要开始使用多语言版doccano，只需从官方仓库克隆项目：

git clone https://gitcode.com/gh_mirrors/do/doccano

然后按照docs/install_and_upgrade_doccano.md的指引进行安装配置即可。

【免费下载链接】doccano Open source annotation tool for machine learning practitioners. 项目地址: https://gitcode.com/gh_mirrors/do/doccano