API REST
React + i18next
La referencia API completa se auto-generará desde nuestra spec OpenAPI 3.1 en cuanto la superficie sea estable. Preferimos shipear un placeholder a fake-doc endpoints que aún pueden moverse. Mientras tanto, aquí va la forma, qué cubrirá y qué hacer hoy.
Instalar
Requiere <strong>Node 20 LTS</strong> o más reciente. Se instalan dos binarios: <code>verbumia</code> y el alias más corto <code>vrb</code> — intercambiables.
terminal 1npm i @verbumia/react-i18next2. Envuelve tu app
VerbumiaProvider recibe un projectId y un apiKey. El resto tiene defaults sensatos: auto-detección de locale desde el navegador, namespaces cargados bajo demanda desde tu CDN, handler de claves faltantes con debounce y POST automático.
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); Todas las props de VerbumiaProvider
| Prop | Type | Default |
|---|---|---|
| projectId | string | — obligatoria |
| apiKey | string | — obligatoria |
| 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. Usa el hook
useTranslation() devuelve { t, i18n }. Forma familiar si has usado react-i18next. i18n.ready te indica cuándo los namespaces iniciales se han hidratado; i18n.changeLanguage() cambia el locale en runtime.
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}Lo que obtienes gratis
- Captura de claves faltantes. Cualquier clave que llames y que no esté en el diccionario se encola, se debouncea (5s por defecto) y se envía por POST a la cola de faltantes de tu dashboard. Seguro en producción — tu fallback sigue renderizando.
- Namespaces servidos desde CDN. Los bundles de traducción se extraen de
cdn.verbumia.cacon caché HTTP y stale-while-revalidate. No hace falta bundling en build-time. - Auto-detección de locale. Si no pasas
defaultLocale, el SDK leenavigator.languagey recae en el default de tu proyecto. - Exports abiertos. Todo lo que envíes a Verbumia, lo puedes exportar de vuelta a JSON i18next, XLIFF o PO. Cambia de herramienta mañana sin reescribir tu código.
Transport personalizado (avanzado)
¿Necesitas loguear claves faltantes en tu propio stack de observabilidad, protegerlas detrás de tu auth o stubearlas en tests? Pasa una función transport. El SDK sigue haciendo debounce y batching; tú decides qué pasa con el batch.
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/>