Migrar a partir de i18next

Antes de começar

Três coisas e está pronto para importar:

• Um projeto. Crie um no dashboard e copie o respetivo project_uuid.
• Uma chave de API com o scope mcp:*. A CLI passa pela superfície MCP — uma chave limitada ao projeto devolve 403. A referência da CLI explica como gerar uma.
• Node 18+ e os seus ficheiros i18next existentes, dispostos como <lang>/<namespace>.json (disposições atípicas também são tratadas).

1. Instalar e inicializar

Instale a CLI globalmente, gere uma config que aponte para o seu projeto e exporte a sua chave.

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 escreve um sonenta.config.json que pode commitar. Na CI, salte o init e passe --project mais a variável de ambiente SONENTA_TOKEN. sonenta e SONENTA_* são canónicos; o antigo comando sonenta e as variáveis SONENTA_* continuam a funcionar durante a transição.

2. Pré-visualizar, depois importar

O importador lê o caminho de cada ficheiro para inferir o idioma e o namespace, pelo que uma árvore locales/ convencional não precisa de opções. Faça um dry-run primeiro para ver o plano, depois remova --dry-run para o aplicar.

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

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

As árvores podem ser aninhadas ou planas — ambas se importam de forma idêntica. --status define o estado de entrada (draft ou translated, por omissão translated); --version visa uma versão não predefinida. Os plurais expressos como dicionário CLDR ({ one, other }) são armazenados automaticamente como formas plurais.

3. Publicar no CDN

O import preenche o projeto; a publicação torna-o servível. Corte uma release e os bundles propagam-se pelo CDN mundial a partir do qual o SDK lê.

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

As releases são snapshots imutáveis de uma versão. Republique sempre que importar novo conteúdo — tanto o SDK como o seu build estático obtêm a última release.

4. Verificar o bundle

Confirme que o conteúdo está em direto. Um bundle publicado é um simples ficheiro JSON público por idioma e namespace — obtenha um diretamente, ou abra o projeto no dashboard.

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

Um 404 num idioma? Ainda não faz parte dos idiomas do projeto, ou a release não se propagou — aguarde alguns segundos e tente novamente.

5. Apontar o seu SDK para a Sonenta

Troque o seu backend i18next pelo provider Sonenta. As suas chamadas t(), as suas chaves e os seus namespaces permanecem iguais — as traduções vêm agora do bundle CDN que acabou de publicar.

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>

Chaves que contêm pontos (uma versão, um preço, uma referência bíblica)? Defina keySeparator={false} e passe o projeto para plano — veja o guia Chaves planas ou aninhadas. Caso contrário, o padrão aninhado funciona tal como está.

O que o importador trata

• Aninhado ou plano. Ambas as formas JSON se importam para as mesmas chaves — sem pré-processamento.
• Plurais. Os dicionários de plurais CLDR ({ one, other, … }, com other obrigatório) tornam-se chaves plurais automaticamente.
• Resiliência por ficheiro. Um idioma ou namespace desconhecido é reportado como erro por unidade — o resto do import conclui-se à mesma.
• Verificações de glossário. As traduções importadas passam pelo seu glossário; as violações são listadas e ignoradas em aplicação estrita.
• Limpeza de chaves em falta. Os eventos de chave em falta abertos para as chaves importadas resolvem-se assim que os valores chegam.