REST API
React + i18next
完全な API リファレンスは、サーフェスが安定し次第、私たちの OpenAPI 3.1 spec から自動生成します。まだ動く可能性のあるエンドポイントを偽ドキュメントで出すより、プレースホルダーをシップする方がマシです。それまでは、形と、何をカバーするか、そして今日できることをまとめておきます。
インストール
<strong>Node 20 LTS</strong> 以上が必要です。インストールされるのは 2 つのバイナリ: <code>verbumia</code> と短いエイリアス <code>vrb</code> — どちらでも使えます。
terminal 1npm i @verbumia/react-i18next2. アプリをラップ
VerbumiaProvider は projectId と apiKey を受け取ります。それ以外はすべて妥当なデフォルト付き: ブラウザからのロケール自動検出、CDN からの namespace 遅延ロード、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 | Type | デフォルト |
|---|---|---|
| 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. フックを使う
useTranslation() は { t, i18n } を返します。react-i18next 経験者には馴染みの形です。i18n.ready で初期 namespace のハイドレート完了を判定でき、i18n.changeLanguage() でランタイムにロケールを切り替えられます。
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 秒)を経てダッシュボードの missing キューに POST されます。本番でも安全 — フォールバックは描画され続けます。
- CDN 配信の namespace。 翻訳バンドルは
cdn.verbumia.caから HTTP キャッシュおよび stale-while-revalidate 付きで取得されます。ビルド時バンドルは不要です。 - ロケール自動検出。
defaultLocaleを渡さない場合、SDK はnavigator.languageを読み、プロジェクトのデフォルトにフォールバックします。 - オープンなエクスポート。 Verbumia に push したものは、JSON i18next、XLIFF、PO に書き戻せます。明日ツールを乗り換えてもコードを書き直す必要はありません。
カスタムトランスポート(上級)
欠落キーを自前の可観測性スタックにログしたい、認証で守りたい、テストでスタブしたい? 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/>