REST API
React + i18next
完整的 API 参考会在 surface 稳定的那一刻,从我们的 OpenAPI 3.1 spec 自动生成。我们宁可发布一个 placeholder,也不愿对仍可能改动的 endpoint 做假文档。在此之前,这里给出形态、它将覆盖什么、以及今天该怎么做。
安装
需要 <strong>Node 20 LTS</strong> 或更新版本。会装两个二进制:<code>verbumia</code> 和较短别名 <code>vrb</code> — 可互换。
terminal 1npm i @verbumia/react-i18next2. 包装你的应用
VerbumiaProvider 接收 projectId 和 apiKey。其他都有合理默认值:从浏览器自动检测 locale、namespace 从你的 CDN 懒加载、缺失键处理器自动 debounce 并 POST。
main.tsx 1// src/main.tsx2import { VerbumiaProvider } from "@verbumia/react-i18next";3import { createRoot } from "react-dom/client";4import { App } from "./App"; 6createRoot(document.getElementById("root")!).render(7 <VerbumiaProvider8 projectId="proj_xxx"9 apiKey={import.meta.env.VITE_VERBUMIA_KEY}10 defaultLocale="en"11 namespaces={["common"]}12 >13 <App />14 </VerbumiaProvider>15); VerbumiaProvider 全部 props
| Prop | 类型 | 默认值 |
|---|---|---|
| projectId | string | — 必填 |
| apiKey | string | — 必填 |
| defaultLocale | string | browser |
| defaultNS | string | "common" |
| namespaces | string[] | ["common"] |
| cdnUrl | string | cdn.verbumia.ca |
| baseUrl | string | api.verbumia.ca |
| missingHandlerEndpoint | string | /v1/missing |
| debounceMs | number | 5000 |
| transport | (batch) => void | Promise<void> | internal |
3. 使用 hook
useTranslation() 返回 { t, i18n }。如果你用过 react-i18next,这个形态会很熟悉。i18n.ready 告诉你初始 namespace 何时已完成 hydrate;i18n.changeLanguage() 在运行时切换 locale。
Checkout.tsx 1// src/Checkout.tsx2import { useTranslation } from "@verbumia/react-i18next"; 4export function Checkout() {5 const { t, i18n } = useTranslation("common"); 7 if (!i18n.ready) return null; // first paint after hydration 9 return (10 <button onClick={() => i18n.changeLanguage("fr")}>11 {t("checkout.review.confirm")}12 </button>13 );14}开箱即得
- 缺失键捕获。 你调用的任何不在字典里的键都会被入队,debounce(默认 5 秒)后 POST 到 dashboard 的 missing 队列。生产可用 — 你的 fallback 仍会渲染。
- CDN 提供 namespace。 翻译 bundle 从
cdn.verbumia.ca拉取,带 HTTP 缓存与 stale-while-revalidate。无需构建时打包。 - Locale 自动检测。 如果你不传
defaultLocale,SDK 会读取navigator.language,并在失败时回退到项目默认值。 - 开放导出。 你 push 到 Verbumia 的内容,都可以导出回 JSON i18next、XLIFF 或 PO。明天换工具,不用重写代码。
自定义 transport(进阶)
想把缺失键打到自己的可观测性栈、放在自有鉴权后,或在测试里打桩?传一个 transport 函数即可。SDK 仍会做 debounce 和批量;批次怎么处理由你决定。
main.tsx 1// custom transport — useful for tests, edge cases, or auditing2<VerbumiaProvider3 projectId="proj_xxx"4 apiKey={import.meta.env.VITE_VERBUMIA_KEY}5 debounceMs={2000}6 transport={(batch) => fetch("/internal/i18n-misses", {7 method: "POST",8 body: JSON.stringify(batch),9 })}10/>