REST API
React + i18next
Полный API reference автоматически сгенерируется из нашей OpenAPI 3.1 spec, как только поверхность стабилизируется. Лучше зашипить плейсхолдер, чем фейк-документировать эндпоинты, которые ещё могут двигаться. А пока — вот форма, что она покроет, и что делать сегодня.
Установка
Требуется <strong>Node 20 LTS</strong> или новее. Ставится два бинарника: <code>verbumia</code> и короткий алиас <code>vrb</code> — взаимозаменяемы.
terminal 1npm i @verbumia/react-i18next2. Оберни приложение
VerbumiaProvider принимает projectId и apiKey. Всё остальное по умолчанию: автоопределение локали из браузера, 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); Все props VerbumiaProvider
| 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. Используй хук
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с) и отправляется POST'ом в очередь missing на дашборде. Безопасно для продакшена — фолбэк продолжает рендериться.
- Namespace'ы с CDN. Бандлы переводов тянутся с
cdn.verbumia.caс HTTP-кэшированием и stale-while-revalidate. Сборка на этапе build не требуется. - Автоопределение локали. Если не передаёшь
defaultLocale, SDK читаетnavigator.languageи откатывается на дефолт проекта. - Открытые экспорты. Всё, что ты пушишь в Verbumia, можно выгрузить обратно в JSON i18next, XLIFF или PO. Смени инструмент завтра — код переписывать не придётся.
Кастомный транспорт (advanced)
Нужно логировать пропущенные ключи в свой стек наблюдаемости, прятать их за своей авторизацией или мокать в тестах? Передай функцию 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/>