Argilla 前端国际化指南：从零为 Argilla 添加一门新语言（i18n 配置、翻译文件与本地验证全流程）

Argilla 前端国际化指南：从零为 Argilla 添加一门新语言（i18n 配置、翻译文件与本地验证全流程）

【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla

本篇技术指南以 Argilla 官方社区文档为基础，系统讲解如何为 Argilla 前端（argilla-frontend）新增一门界面语言：包括翻译文件的创建与规范、nuxt.config.ts中 i18n 语言注册、浏览器语言检测与回退机制，以及借助 Docker 部署的 Argilla Server 与 Python SDK 完成端到端本地验证。读完本文，你将能够独立为 Argilla 的标注界面添加如韩语（ko）、法语（fr）等任意语言，并确认翻译在数据集列表、标注页面与数据集设置界面中正确生效。

一、Argilla 前端国际化（i18n）架构概览

Argilla 是一个面向 AI 工程师与领域专家的高质量数据集协作标注平台，其前端基于 Nuxt.js（Vue 2）构建。界面多语言能力由@nuxtjs/i18n模块承载，整体由以下三个核心部分协作完成：

• 翻译文件目录：translation/ —— 每种语言一个*.js文件，导出以键值对形式组织的翻译文本，其中en.js是官方维护的英文基准（模板）。
• i18n 配置：nuxt.config.ts —— 注册可用语言列表，声明语言目录、默认语言与回退策略。
• 语言检测与切换服务：useLanguageDetector.ts —— 应用启动时读取浏览器语言或用户历史选择，并持久化用户偏好。

从仓库现状看，Argilla 目前已内置四种语言，见 nuxt.config.ts：

官方建议的新增语言流程分为两步：先在argilla-frontend/translation目录创建翻译文件，再在nuxt.config.ts的i18n.locales中注册该语言。下面依次展开。

二、第一步：创建翻译文件

新增语言的第一步，是进入前端翻译目录argilla-frontend/translation，复制英文基准文件en.js并以目标语言的 ISO 639-1 语言代码命名。

例如要为韩语（代码ko）添加翻译，就创建ko.js，其内容结构如下：

export default { multi_label_selection: "다중 라벨", ranking: "순위", label_selection: "라벨", span: "범위", text: "텍스트", // ... 其余所有键的韩语翻译 }

需要特别注意的是，必须保留en.js中定义的全部键（key），并逐一将值翻译为对应语言。en.js是翻译的权威基准，它包含 400 余行、覆盖数十个功能模块的字符串，例如：

• 全局界面词汇：search、title、description、labels、required、optional、expand、minimize等；
• 标注组件相关：multi_label_selection（多标签）、label_selection（单选标签）、span（跨度标注）、ranking（排序）、rating（评分）、text、image；
• 嵌套对象：如noRecordsMessages、breadcrumbs、userSettings、settings、button、bulkAnnotation、login、home、datasetCreation、exportToHub、config、validations等，它们以对象层级组织，翻译时需保持同样的嵌套结构；
• 带占位符的字符串：如login.signin_with_provider: "Sign in with {provider}"、noRecordsMessages.noRecords: "You have no {status} records"、bulkAnnotation.recordsSelected: "1 record selected | {count} records selected"等，占位符（{provider}、{status}、{count}）必须原样保留，不可改动或翻译，否则运行时将无法正确插值；
• 部分字符串包含 HTML 片段：如noRecordsMessages.datasetEmptyForAdmin中的<a href='...'>documentation</a>、login.hf.subtitle中的<strong>{user}</strong>，翻译时应保留这些标签结构，仅翻译标签之间的文本内容。

以现有的日语翻译 ja.js 为参照，可以看到其键顺序与en.js完全一致，例如：

export default { multi_label_selection: "マルチラベル", ranking: "ランキング", label_selection: "ラベル", span: "範囲選択", text: "テキスト", chat: "チャット", image: "画像", rating: "レーティング", // ... }

建议以en.js为底稿，自上而下逐行替换值，避免遗漏键。遗漏的键在运行时将自动回退到英文（回退策略详见第四节）。

三、第二步：在 nuxt.config.ts 中注册语言

创建好翻译文件后，需要编辑 argilla-frontend/nuxt.config.ts，在i18n.locales数组中追加该语言条目。以韩语为例：

i18n: { locales: [ { code: "en", file: "en.js", }, // ... 其他已有语言 { code: "ko", file: "ko.js", }, ], // ... }

locales数组中的每个条目包含两个关键字段：

• code：语言代码（如en、ko），用于运行时切换与检测；
• file：对应langDir下的翻译文件名。

当前仓库中的完整 i18n 配置块见 nuxt.config.ts，除了locales，还有几项与本主题强相关的配置值得理解：

四、深入源码：语言检测、回退与用户切换机制

完成文件创建与注册后，新语言会立即进入 Argilla 的运行时语言管线。理解这条管线有助于验证翻译是否真正生效，以及排查"为什么界面还是英文"的问题。

4.1 启动时的语言检测与持久化

应用启动时，插件 language-detector.ts 会调用 useLanguageDetector.ts 中的initialize()，其判定逻辑如下：

1. 优先读取localStorage中用户上次保存的language值（useLocalStorage的get("language")）；
2. 若没有历史选择，则取浏览器语言navigator.language；
3. 先精确匹配（如es直接命中es），若浏览器语言带地区后缀（如es-AR），则截取-前的语言代码（es）再匹配；
4. 若上述均未命中任何已注册语言，回退到"en"。

切换语言时（useLanguageChanger.change）会同步执行三件事：调用i18n.setLocale(language)应用翻译、将document.documentElement.lang设为对应语言代码（利于屏幕阅读器与 SEO）、并把选择写入localStorage以便下次启动恢复。

上述逻辑在单元测试 useLanguageDetector.test.ts 中有完整覆盖：测试分别验证了"用户无历史选择且浏览器语言受支持""浏览器语言为es-AR这类带区域后缀""浏览器语言不受支持时回退英文"以及"优先使用用户历史保存的语言"四种场景。这从测试层面印证了：只要在locales中注册了ko，韩语浏览器的用户首次访问就会自动看到韩语界面，无需任何手动设置。

4.2 用户手动切换语言

在界面层面，用户可以通过用户设置页（My settings）中的语言选择器切换语言，其实现位于 UserSettingsLanguage.vue，配合 useUserSettingsLanguageViewModel.ts 中的useLanguageChanger使用。语言列表（i18n.locales）按语言代码排序后展示，用户选择后立即生效并持久化。

4.3 键缺失时的回退

由于vueI18n.fallbackLocale配置为"en"，即便某个键在ko.js中漏翻或键名拼错，界面也不会崩溃，而是显示对应的英文文本。这意味着翻译不完整时界面"看起来能用"但夹杂英文，因此完整性校验（与en.js的键逐一比对）是翻译质量的关键环节。另外，仓库使用@intlify/eslint-plugin-vue-i18n（见 package.json）对*.vue文件中的 i18n 用法做静态检查，可辅助发现未定义键等常见问题。

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

对于阿拉伯语、希伯来语等从右到左书写的语言，仓库还提供了文本方向检测服务 useLanguageDirection.ts：isRTL(text)通过统计字符串中 RTL 与 LTR 字符的 Unicode 区间数量来判断文本方向，并在 language-direction.ts 中注入为$language。如果你的新语言需要 RTL 排版，可以基于该能力扩展界面方向切换，并同步在themes.css等样式层做适配。

五、第三步：本地端到端验证

翻译文件与配置完成后，需要在真实环境中验证：翻译是否被正确加载、数据集列表/标注页面/数据集设置等界面是否完整显示新语言。官方推荐的验证路径分三步。

5.1 启动本地 Argilla 后端

最快捷的方式是使用 Docker 部署 Argilla Server，完整步骤见 Docker 部署指南。核心操作如下：

# 创建部署目录并下载 docker-compose 配置 mkdir argilla && cd argilla curl https://raw.githubusercontent.com/argilla-io/argilla/main/examples/deployments/docker/docker-compose.yaml -o docker-compose.yaml # 启动服务器（默认 http://localhost:6900） docker compose up -d # 查看日志排查问题 docker compose logs -f

启动后，浏览器访问http://localhost:6900应能看到 Argilla 登录页。本地实例会提供前端所需的后端 API；同时可从仓库内的 examples/deployments/docker/docker-compose.yaml 查看服务编排细节。仓库内还提供了 nginx、traefik 等反向代理示例（见 examples/deployments/docker/），以及 Kubernetes Helm 部署方案（见 examples/deployments/k8s/argilla-chart/），可按需选用。

说明：Docker 镜像随仓库版本演进，下载链接中的镜像/配置路径请以当前部署指南与 docker-compose.yaml 为准。

5.2 构建并启动带新翻译的前端

前端在仓库的argilla-frontend目录下，使用 npm 管理依赖与脚本（见 package.json）。验证流程为：

# 进入前端目录 cd argilla-frontend # 安装依赖 npm i # 构建包含新翻译的前端产物 npm run build # 启动前端服务（默认监听 localhost:3000） npm run start

构建与启动对应的脚本为nuxt build与nuxt start（见 package.json）。由于i18n.lazy开启且langDir指向translation/，新加入的ko.js会被自动打包，并在浏览器语言命中ko时按需加载。

启动后访问http://localhost:3000，进入用户设置切换语言，或在韩语浏览器环境中直接访问，逐一核对各页面的翻译效果。

5.3 使用 Python SDK 构造测试数据集验证标注界面翻译

为了让验证覆盖标注场景（而不只是外壳页面），官方建议用 Argilla Python SDK 在本地实例中创建一个包含多种字段与问题类型的测试数据集。首先需要安装并连接 SDK：

import argilla as rg # 连接本地 Docker 部署的 Argilla 实例 client_local = rg.Argilla(api_url="http://localhost:6900/", api_key="argilla.apikey")

提示：api_url对应 5.1 中 Docker 部署的后端地址；默认 API key 为argilla.apikey，如部署时修改过密码，请以实际值为准。前端通过代理将/api/请求转发到该后端（见 nuxt.config.ts）。

然后定义数据集设置。下面的完整示例覆盖了 Argilla 支持的主要字段类型（Chat、Text、Image）与问题类型（Span、Label、MultiLabel、Ranking、Rating、Text）：

sample_questions = [ rg.SpanQuestion( name="question1", field="text", labels={ "PERSON": "Person", "ORG": "Organization", "LOC": "Location", "MISC": "Miscellaneous" }, # or ["PERSON", "ORG", "LOC", "MISC"] title="Select the entities in the text", description="Select the entities in the text", required=True, allow_overlapping=False, ), rg.LabelQuestion( name="question2", labels={"YES": "Yes", "NO": "No"}, # or ["YES", "NO"] title="Is the answer relevant to the given prompt?", description="Choose the option that applies.", required=True, ), rg.MultiLabelQuestion( name="question3", labels={ "hate": "Hate speech", "sexual": "Sexual content", "violent": "Violent content", "pii": "Personal information", "untruthful": "False information", "not_english": "Not English", "inappropriate": "Inappropriate content" }, # or ["hate", "sexual", "violent", "pii", "untruthful", "not_english", "inappropriate"] title="Does the response contain any of the following?", description="Select all applicable options.", required=True, visible_labels=3, labels_order="natural" ), rg.RankingQuestion( name="question4", values={ "reply-1": "Answer 1", "reply-2": "Answer 2", "reply-3": "Answer 3" }, # or ["reply-1", "reply-2", "reply-3"] title="Rank the answers by your preference", description="1 = best, 3 = worst. Equal ratings are allowed.", required=True, ), rg.RatingQuestion( name="question5", values=[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10], title="How satisfied are you with the answer?", description="1 = very dissatisfied, 10 = very satisfied", required=True, ), rg.TextQuestion( name="question6", title="Please provide your feedback on the answer", description="Please provide your feedback on the answer", required=True, use_markdown=True ) ] sample_fields = [ rg.ChatField( name="chat", title="Previous conversation with the customer", use_markdown=True, required=True, description="Dialog between AI & customer up to the last question", ), rg.TextField( name="text", title="Customer's question", use_markdown=False, required=True, description="This is a question from the customer", ), rg.ImageField( name="image", title="Image related to the question", required=True, description="Image sent by the customer", ), ] # 创建数据集设置并新建数据集 settings = rg.Settings( fields=sample_fields, questions=sample_questions, ) new_dataset = rg.Dataset( name="demo_dataset", workspace="default", settings=settings, client=client_local, ) new_dataset.create()

数据集创建后，写入一批测试记录以便在标注界面查看：

def fix_record(): return rg.Record( fields={ "chat": [ {"role": "user", "content": "What is Argilla?"}, {"role": "assistant", "content": "Argilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets"}, ], "image": "https://images.unsplash.com/photo-1523567353-71ea31cb9f73?w=900&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8MTJ8fGNvcmdpfGVufDB8fDB8fHww", "text": "Which town has a greater population as of the 2010 census, Minden, Nevada or Gardnerville, Nevada?", }, ) new_records = [fix_record() for _ in range(10)] new_dataset.records.log(new_records)

数据就绪后，回到前端界面，将界面语言切换到新语言，依次检查：

1. 数据集列表页：首页标题、按钮、空状态提示等是否已翻译；
2. 标注页面：问题标题/描述、标签选项、状态（pending / draft / submitted 等）、快捷键提示、排序与过滤选项等；
3. 数据集设置页：字段、问题、元数据属性、向量、删除确认弹窗等；
4. 用户设置页：主题、语言、API key 等；
5. 不同浏览器语言下的首次访问：确认自动检测与英文回退行为符合预期。

其中标注页面的记录状态文案（pending、draft、discarded、submitted、validated）位于recordStatus对象，数据集设置相关文案位于settings对象，验证时尤其值得留意这些嵌套键是否被正确翻译。

六、新增语言的最佳实践清单

结合en.js的结构、nuxt.config.ts的配置以及源码实现，为 Argilla 贡献新语言时建议遵循以下规范：

1. 以en.js为唯一基准：复制后逐键翻译，保持键名、键顺序与嵌套结构完全一致，不要自行增删键；
2. 保留占位符与 HTML 标签：{provider}、{count}、{status}、{datasetName}等占位符以及<strong>、<a>等标签必须原样保留；
3. 注意复数与上下文：如bulkAnnotation.recordsSelected使用了 vue-i18n 的1 | {count}管道语法区分单复数，翻译时需按目标语言的复数规则调整；
4. 控制字符串长度：界面空间有限，翻译文本过长可能导致布局溢出，建议保持简洁并实测 UI 效果；
5. 利用回退机制定位漏译：fallbackLocale: "en"会让漏译键显示英文，可通过在切换语言后全局搜索残留英文来排查遗漏；
6. RTL 语言需额外处理：借助useLanguageDirection的isRTL能力与样式适配（themes.css）支持从右到左排版；
7. 注册后无需改动路由：由于strategy: "no_prefix"与detectBrowserLanguage: false，新语言不会改变 URL 结构，也不会与模块内置探测冲突，语言完全由运行时检测与用户偏好决定；
8. 完整走一遍端到端验证：至少覆盖登录页、数据集列表、标注页面、数据集设置与用户设置五个界面，并分别在"浏览器语言命中""浏览器语言带区域后缀""浏览器语言未注册"三种情况下确认行为。

按照上述两步配置加三步验证的流程，即可为 Argilla 贡献一门全新语言，让不同语言背景的标注团队都能在熟悉的界面中高效协作，共同构建高质量的数据集。

【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla