Chuyển đến nội dung chính

Đặc tả Plugin Phương thức

Phiên bản: 1.1
Đối tượng: Các nhà phát triển plugin
Lược đồ chuẩn: schemas/rosetta-plugin.schema.json

Tổng quan​

i18n-rosetta sử dụng một hệ thống phương thức có thể cắm (pluggable). Mỗi cặp ngôn ngữ có thể sử dụng một phương thức dịch thuật khác nhau (LLM, coached, script-converter, v.v.). Các phương thức được đăng ký trong lib/translate.js và được phân giải cho từng cặp thông qua lib/pairs.js.

Nhiệm vụ của eval harness là phát triển, kiểm thử và xuất các phương thức dịch thuật. Nhiệm vụ của i18n-rosetta là tiêu thụ và thực thi chúng. Harness không bao giờ chạy bên trong rosetta.

Luồng dữ liệu​


Định dạng Method Plugin​

Một method plugin là một tệp JSON duy nhất (method.json) kèm theo các tệp dữ liệu coaching tùy chọn.

method.json — Bắt buộc​

{
"name": "french-formal-v1",
"type": "llm-coached",
"version": "1.0.0",
"description": "Formally-tuned French with terminology enforcement and grammar coaching",
"author": "Plugin Author",

"config": {
"model": "google/gemini-3.5-flash",
"register": "formal",
"batchSize": 80,
"temperature": 0.2
},

"locales": ["fr"],

"benchmarks": {
"fr": {
"date": "2026-05-11T00:00:00Z",
"corpus_size": 500,
"exact_match_rate": 0.42,
"corpus_chrf": 72.3,
"corpus_bleu": 45.1,
"model": "google/gemini-3.5-flash",
"harness_version": "1.0.0"
}
},

"provenance": {
"resources": [],
"commercialReady": false,
"flags": ["license-unclear"]
},

"coaching": {
"dir": "coaching"
}
}

Tham chiếu trường​

TrườngKiểu dữ liệuBắt buộcMô tả
namestring✅Định danh phương thức duy nhất (kebab-case)
typestring✅Loại phương thức Rosetta: llm, llm-coached, api, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini
versionstring✅Phiên bản Semver (ví dụ: 1.0.0)
localesstring[]✅Các mã ngôn ngữ (locale code) mà phương thức này nhắm tới (tối thiểu 1)
descriptionstring—Mô tả chi tiết cho người đọc
authorstring—Người đã phát triển/kiểm thử phương thức này
config.modelstring—Định danh mô hình OpenRouter
config.registerstring—Văn phong/giọng điệu của ngôn ngữ đích
config.batchSizenumber—Số lượng key trên mỗi batch API (1–200, mặc định: 80)
config.temperaturenumber—Temperature của LLM (0.0–2.0, mặc định: 0.3)
benchmarksobject—Kết quả benchmark theo từng locale
provenanceobject—Cấp phép và các phụ thuộc tài nguyên
coaching.dirstring—Đường dẫn tương đối đến thư mục dữ liệu coaching

Đối tượng Benchmark (theo từng locale)​

TrườngKiểu dữ liệuBắt buộcMô tả
datestring✅Dấu thời gian ISO 8601 của lần chạy benchmark
corpus_sizenumber✅Số lượng mục nhập được đánh giá
exact_match_ratenumber✅0.0–1.0, tỷ lệ khớp chính xác (exact match)
corpus_chrfnumber—Điểm chrF++ (0–100)
corpus_bleunumber—Điểm BLEU (0–100)
modelstring✅Mô hình được sử dụng trong quá trình đánh giá (eval)
harness_versionstring✅Phiên bản của evaluation harness được sử dụng

:::info Các số liệu nào được hiển thị? Lệnh rosetta status hiển thị chrF++ và tỷ lệ khớp chính xác (exact match rate) từ khối benchmark. corpus_bleu được chấp nhận trong manifest nhưng hiện không được hiển thị hoặc sử dụng bởi bất kỳ lệnh rosetta nào. Bảng xếp hạng Method Leaderboard theo dõi chrF++, exact match và tỷ lệ chấp nhận FST. :::


Đối tượng Provenance​

Khối provenance truyền đạt trạng thái cấp phép của các tài nguyên đi kèm trong plugin.

TrườngKiểu dữ liệuMặc địnhMô tả
resourcesobject[][]Danh sách các tài nguyên đi kèm với name, license và type
commercialReadybooleanfalseCho biết plugin đã được cấp phép để phân phối thương mại hay chưa
flagsstring[]["license-unclear"]Các cờ trạng thái (status flags) mà máy có thể đọc được

Trạng thái mặc định — các plugin được xuất ra sẽ đi kèm với commercialReady: false và flags: ["license-unclear"].

Trạng thái đã cấp phép (Cleared state) — khi việc cấp phép đã được xác minh: thiết lập commercialReady: true và xóa các cờ.


Định dạng Dữ liệu Coaching​

Nếu type là llm-coached, plugin nên bao gồm các tệp dữ liệu coaching trong thư mục con coaching/.

coaching/<locale>.json​

{
"grammar_rules": [
"French adjectives agree in gender and number with the noun they modify",
"Use 'vous' for formal contexts, 'tu' for informal"
],
"dictionary": {
"dashboard": "tableau de bord",
"deployment": "déploiement",
"settings": "paramètres"
},
"style_notes": "Prefer active voice. Avoid anglicisms where a native French term exists."
}
TrườngKiểu dữ liệuBắt buộcMô tả
grammar_rulesstring[]—Các quy tắc được chèn vào mọi prompt LLM cho locale này
dictionaryobject—Bản đồ thuật ngữ → bản dịch. Các thuật ngữ khớp sẽ được chèn vào dưới dạng thuật ngữ bắt buộc.
style_notesstring—Các hướng dẫn văn phong tự do được nối thêm vào prompt

Cấu trúc Thư mục​

french-formal-v1/
method.json # Method manifest with benchmarks
coaching/
fr.json # Coaching data for French

Đối với các phương thức đa ngôn ngữ (multi-locale):

european-formal-v2/
method.json # locales: ["fr", "de", "es", "it"]
coaching/
fr.json
de.json
es.json
it.json

Cách Rosetta Tiêu thụ Plugin​

Cài đặt​

i18n-rosetta plugin install ./french-formal-v1/

Lưu vào .rosetta/methods/french-formal-v1/.

Cấu hình​

i18n-rosetta.config.json
{
"pairs": {
"en:fr": {
"methodPlugin": "french-formal-v1"
}
}
}

:::info Ngữ nghĩa gộp (Merge semantics) Plugin định nghĩa phương thức nào sẽ được sử dụng (type). Cấu hình cặp (pair config) tinh chỉnh cách chạy phương thức đó (model, register, batchSize). Nếu cặp thiết lập model, nó sẽ ghi đè giá trị mặc định của plugin. :::

Thời gian chạy (Runtime)​

  1. Rosetta đọc method.json từ .rosetta/methods/french-formal-v1/
  2. Trường type của plugin thiết lập phương thức dịch thuật (ví dụ: llm-coached)
  3. Tải dữ liệu coaching từ thư mục coaching/ của plugin
  4. Sử dụng khối config để điền các khoảng trống trong model/register/temperature
  5. Khối benchmarks được hiển thị trong đầu ra của rosetta status
  6. Khối provenance được kiểm tra bởi rosetta provenance để tìm các cờ cấp phép

Xác thực Lược đồ (Schema Validation)​

Các manifest của plugin được xác thực tại thời điểm cài đặt dựa trên schemas/rosetta-plugin.schema.json.

Tham chiếu lược đồ trong method.json của bạn để IDE tự động hoàn thành:

{
"$schema": "./node_modules/i18n-rosetta/schemas/rosetta-plugin.schema.json",
"name": "my-method-v1"
}

Những gì KHÔNG nên bao gồm​

  • ❌ Không có mã Python hoặc các phụ thuộc của harness
  • ❌ Không có dữ liệu ngữ liệu thô (raw corpus data) hoặc nhật ký chạy (run logs)
  • ❌ Không có API key hoặc thông tin xác thực
  • ❌ Không có cấu hình harness
  • ❌ Không có các mẫu prompt nội bộ (chúng nằm trong các triển khai phương thức của rosetta)

Plugin chỉ chứa dữ liệu: cấu hình, nội dung coaching và kết quả benchmark.


Xem thêm​