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.jsVue 2构建。界面多语言能力由nuxtjs/i18n模块承载整体由以下三个核心部分协作完成翻译文件目录translation/ —— 每种语言一个*.js文件导出以键值对形式组织的翻译文本其中en.js是官方维护的英文基准模板。i18n 配置nuxt.config.ts —— 注册可用语言列表声明语言目录、默认语言与回退策略。语言检测与切换服务useLanguageDetector.ts —— 应用启动时读取浏览器语言或用户历史选择并持久化用户偏好。从仓库现状看Argilla 目前已内置四种语言见 nuxt.config.ts语言代码语言名称翻译文件enEnglishen.jsdeDeutschde.jsesEspañoles.jsja日本語ja.js官方建议的新增语言流程分为两步先在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还有几项与本主题强相关的配置值得理解配置项当前值作用langDirtranslation/翻译文件所在目录即argilla-frontend/translation/defaultLocaleen默认语言应用启动时的兜底语言vueI18n.fallbackLocaleen当某个键在目标语言中缺失时回退到英文lazytrue翻译文件懒加载仅在使用该语言时才请求对应*.jsstrategyno_prefixURL 中不携带语言前缀语言由客户端运行时决定detectBrowserLanguagefalse关闭模块自带的浏览器语言探测改由仓库自研检测逻辑接管四、深入源码语言检测、回退与用户切换机制完成文件创建与注册后新语言会立即进入 Argilla 的运行时语言管线。理解这条管线有助于验证翻译是否真正生效以及排查为什么界面还是英文的问题。4.1 启动时的语言检测与持久化应用启动时插件 language-detector.ts 会调用 useLanguageDetector.ts 中的initialize()其判定逻辑如下优先读取localStorage中用户上次保存的language值useLocalStorage的get(language)若没有历史选择则取浏览器语言navigator.language先精确匹配如es直接命中es若浏览器语言带地区后缀如es-AR则截取-前的语言代码es再匹配若上述均未命中任何已注册语言回退到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.tsisRTL(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 在本地实例中创建一个包含多种字段与问题类型的测试数据集。首先需要安装并连接 SDKimport argilla as rg # 连接本地 Docker 部署的 Argilla 实例 client_local rg.Argilla(api_urlhttp://localhost:6900/, api_keyargilla.apikey)提示api_url对应 5.1 中 Docker 部署的后端地址默认 API key 为argilla.apikey如部署时修改过密码请以实际值为准。前端通过代理将/api/请求转发到该后端见 nuxt.config.ts。然后定义数据集设置。下面的完整示例覆盖了 Argilla 支持的主要字段类型Chat、Text、Image与问题类型Span、Label、MultiLabel、Ranking、Rating、Textsample_questions [ rg.SpanQuestion( namequestion1, fieldtext, labels{ PERSON: Person, ORG: Organization, LOC: Location, MISC: Miscellaneous }, # or [PERSON, ORG, LOC, MISC] titleSelect the entities in the text, descriptionSelect the entities in the text, requiredTrue, allow_overlappingFalse, ), rg.LabelQuestion( namequestion2, labels{YES: Yes, NO: No}, # or [YES, NO] titleIs the answer relevant to the given prompt?, descriptionChoose the option that applies., requiredTrue, ), rg.MultiLabelQuestion( namequestion3, 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] titleDoes the response contain any of the following?, descriptionSelect all applicable options., requiredTrue, visible_labels3, labels_ordernatural ), rg.RankingQuestion( namequestion4, values{ reply-1: Answer 1, reply-2: Answer 2, reply-3: Answer 3 }, # or [reply-1, reply-2, reply-3] titleRank the answers by your preference, description1 best, 3 worst. Equal ratings are allowed., requiredTrue, ), rg.RatingQuestion( namequestion5, values[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10], titleHow satisfied are you with the answer?, description1 very dissatisfied, 10 very satisfied, requiredTrue, ), rg.TextQuestion( namequestion6, titlePlease provide your feedback on the answer, descriptionPlease provide your feedback on the answer, requiredTrue, use_markdownTrue ) ] sample_fields [ rg.ChatField( namechat, titlePrevious conversation with the customer, use_markdownTrue, requiredTrue, descriptionDialog between AI customer up to the last question, ), rg.TextField( nametext, titleCustomers question, use_markdownFalse, requiredTrue, descriptionThis is a question from the customer, ), rg.ImageField( nameimage, titleImage related to the question, requiredTrue, descriptionImage sent by the customer, ), ] # 创建数据集设置并新建数据集 settings rg.Settings( fieldssample_fields, questionssample_questions, ) new_dataset rg.Dataset( namedemo_dataset, workspacedefault, settingssettings, clientclient_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?w900autoformatfitcropq60ixlibrb-4.0.3ixidM3wxMjA3fDB8MHxzZWFyY2h8MTJ8fGNvcmdpfGVufDB8fDB8fHww, 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)数据就绪后回到前端界面将界面语言切换到新语言依次检查数据集列表页首页标题、按钮、空状态提示等是否已翻译标注页面问题标题/描述、标签选项、状态pending / draft / submitted 等、快捷键提示、排序与过滤选项等数据集设置页字段、问题、元数据属性、向量、删除确认弹窗等用户设置页主题、语言、API key 等不同浏览器语言下的首次访问确认自动检测与英文回退行为符合预期。其中标注页面的记录状态文案pending、draft、discarded、submitted、validated位于recordStatus对象数据集设置相关文案位于settings对象验证时尤其值得留意这些嵌套键是否被正确翻译。六、新增语言的最佳实践清单结合en.js的结构、nuxt.config.ts的配置以及源码实现为 Argilla 贡献新语言时建议遵循以下规范以en.js为唯一基准复制后逐键翻译保持键名、键顺序与嵌套结构完全一致不要自行增删键保留占位符与 HTML 标签{provider}、{count}、{status}、{datasetName}等占位符以及strong、a等标签必须原样保留注意复数与上下文如bulkAnnotation.recordsSelected使用了 vue-i18n 的1 | {count}管道语法区分单复数翻译时需按目标语言的复数规则调整控制字符串长度界面空间有限翻译文本过长可能导致布局溢出建议保持简洁并实测 UI 效果利用回退机制定位漏译fallbackLocale: en会让漏译键显示英文可通过在切换语言后全局搜索残留英文来排查遗漏RTL 语言需额外处理借助useLanguageDirection的isRTL能力与样式适配themes.css支持从右到左排版注册后无需改动路由由于strategy: no_prefix与detectBrowserLanguage: false新语言不会改变 URL 结构也不会与模块内置探测冲突语言完全由运行时检测与用户偏好决定完整走一遍端到端验证至少覆盖登录页、数据集列表、标注页面、数据集设置与用户设置五个界面并分别在浏览器语言命中浏览器语言带区域后缀浏览器语言未注册三种情况下确认行为。按照上述两步配置加三步验证的流程即可为 Argilla 贡献一门全新语言让不同语言背景的标注团队都能在熟悉的界面中高效协作共同构建高质量的数据集。【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考