Guía · Migración

Migrar desde i18next

¿Ya estás en producción con i18next? @sonenta/react-i18next es un reemplazo directo (drop-in) de react-i18next — la misma API useTranslation() y t(): solo cambias el provider y tus traducciones llegan en vivo desde el CDN. Lleva tus archivos locales/ existentes a Sonenta con un solo comando, y luego mantén tu código tal cual. El import crea las claves faltantes, actualiza cada traducción y es totalmente idempotente: puedes volver a ejecutarlo desde la CI sin miedo. Este es el recorrido completo: instalar, importar, publicar, verificar y conectar el SDK.

Antes de empezar

Tres cosas, y estás listo para importar:

Un proyecto. Crea uno en el dashboard y copia su project_uuid.
Una clave API con el scope mcp:*. La CLI pasa por la superficie MCP — una clave limitada al proyecto devuelve 403. La referencia de la CLI explica cómo generar una.
Node 18+ y tus archivos i18next existentes, dispuestos como <lang>/<namespace>.json (también se gestionan las disposiciones atípicas).

1. Instalar e inicializar

Instala la CLI globalmente, genera una config que apunte a tu proyecto y exporta tu clave.

terminal

1# one global install — gives you the `sonenta` command (Node >= 18)2npm i -g @sonenta/cli 4# scaffold sonenta.config.json and point it at your project5sonenta init --project <project_uuid> 7# the CLI talks to the MCP surface — use an mcp:* scoped key8export SONENTA_TOKEN=snt_live_<prefix>.<secret>

sonenta init escribe un sonenta.config.json que puedes commitear. En la CI, omite init y pasa --project más la variable de entorno SONENTA_TOKEN. sonenta y SONENTA_* son canónicos; el antiguo comando sonenta y las variables SONENTA_* aún funcionan durante la transición.

2. Previsualizar, luego importar

El import lee la ruta de cada archivo para deducir su idioma y namespace, así que un árbol locales/ convencional no necesita ninguna opción. Haz un dry-run primero para ver el plan, y luego quita --dry-run para aplicarlo.

your repo

1# the importer infers (language, namespace) from each path:2#   <lang>/<namespace>.json3locales/4├─ en/5│  ├─ common.json     → language en · namespace common6│  └─ checkout.json   → language en · namespace checkout7└─ fr/8   ├─ common.json     → language fr · namespace common9   └─ checkout.json   → language fr · namespace checkout

terminal

1# preview first — no writes, prints exactly what WOULD change2sonenta import "./locales/**/*.json" --dry-run 4# the real run — idempotent, safe to repeat5sonenta import "./locales/**/*.json" 7✓ common · checkout   (en, fr)8  keys           312 created · 0 reused9  translations   624 created · 0 updated · 0 unchanged10  errors 0 · glossary 0 violations 12# non-standard layout? override the inference per file:13sonenta import strings.fr.json --language fr --namespace common

Los árboles pueden ser anidados o planos — ambos se importan igual. --status fija el estado entrante (draft o translated, por defecto translated); --version apunta a una versión no predeterminada. Los plurales expresados como diccionario CLDR ({ one, other }) se almacenan como formas plurales automáticamente.

3. Publicar en el CDN

El import llena el proyecto; la publicación lo hace servible. Corta una release y los bundles se propagan al CDN global del que lee el SDK.

terminal

1# cut a CDN release so the SDK and your build can fetch it2sonenta releases publish 4→ released "main" · propagating to cdn.sonenta.com

Las releases son instantáneas inmutables de una versión. Vuelve a publicar en cuanto importes contenido nuevo — tanto el SDK como tu build estático recuperan la última release.

4. Verificar el bundle

Confirma que el contenido está en línea. Un bundle publicado es un simple archivo JSON público por idioma y namespace — recupera uno directamente, o abre el proyecto en el dashboard.

terminal

1# the published bundle is public — no auth needed2curl -s https://cdn.sonenta.com/p/<project_uuid>/main/latest/fr/common.json

¿Un 404 en un idioma? Todavía no forma parte de los idiomas del proyecto, o la release no se ha propagado — espera unos segundos y reintenta.

5. Apuntar tu SDK a Sonenta

Reemplaza tu backend i18next por el provider de Sonenta. Tus llamadas t(), tus claves y tus namespaces siguen siendo idénticos — las traducciones vienen ahora del bundle de CDN que acabas de publicar.

main.tsx

1// src/main.tsx — point @sonenta/react-i18next at the same project2import { SonentaProvider } from "@sonenta/react-i18next"; 4<SonentaProvider5  projectUuid="<project_uuid>"6  token={import.meta.env.VITE_SONENTA_TOKEN}7  defaultLocale="fr"8  namespaces={["common", "checkout"]}9>10  <App />11</SonentaProvider>

¿Claves que contienen puntos (una versión, un precio, una referencia bíblica)? Pon keySeparator={false} y pasa el proyecto a plano — ver la guía Claves planas o anidadas. Si no, el valor por defecto anidado funciona tal cual.

Reejecutable en cualquier momento

sonenta import es idempotente: reimportar un contenido idéntico no cambia nada (0 creadas, 0 actualizadas, N sin cambios). Intégralo en la CI para mantener Sonenta sincronizado con tu repositorio — solo crea lo que falta y solo actualiza lo que realmente cambió.

Lo que gestiona el import

Anidado o plano. Ambas formas JSON se importan a las mismas claves — sin preprocesamiento.
Plurales. Los diccionarios de plurales CLDR ({ one, other, … }, con other obligatorio) se convierten en claves plurales automáticamente.
Resiliencia por archivo. Un idioma o un namespace desconocido se señala como error por unidad — el resto del import se completa igualmente.
Controles de glosario. Las traducciones importadas pasan por tu glosario; las violaciones se listan, y se omiten en aplicación estricta.
Limpieza de claves faltantes. Los eventos de clave faltante abiertos para las claves importadas se resuelven en cuanto llegan los valores.