Translate your app with Sonenta

1. Install the CLI

   npm install -g @sonenta/cli      # provides the `sonenta` command

2. Authenticate

   Create an API key in the dashboard (Settings → API keys) with the mcp:* scope so the local-AI agents can act.

   sonenta login --token vrb_live_<prefix>.<secret>
   # --host defaults to https://api.sonenta.dev

3. Initialize the project

   Run in your repo root. This scaffolds sonenta.config.json, a managed block in CLAUDE.md / AGENTS.md so your local AI knows the project, and auto-wires the MCP server into .mcp.json (secret-free, the server reads credentials from your sonenta login).

   sonenta init --project <PROJECT_UUID>

   {
     "host": "https://api.sonenta.dev",
     "project_uuid": "<PROJECT_UUID>",
     "version_slug": "main"
   }

   {
     "mcpServers": {
       "sonenta": {
         "command": "npx",
         "args": ["-y", "@sonenta/mcp"],
         "env": {
           "SONENTA_BASE_URL": "https://api.sonenta.dev",
           "SONENTA_PROJECT": "<PROJECT_UUID>"
         }
       }
     }
   }

4. Install the local-AI agent

   Writes .claude/agents/sonenta-i18n.md and ensures .mcp.json is wired. sonenta agents list shows all bundled agents, e.g. sonenta-a11y.

   sonenta agents add sonenta-i18n      # the translation agent

5. Verify the setup

   sonenta doctor                       # checks MCP wired, reachable, scoped

6. Add the runtime SDK

   Wrap your app once with the provider, then render strings with the t() hook as usual. Published translations arrive over the CDN with no code change.

   npm install @sonenta/react-i18next

   import { SonentaProvider } from "@sonenta/react-i18next";
   
   <SonentaProvider
     apiBase="https://api.sonenta.dev"
     projectUuid="<PROJECT_UUID>"
     token="vrb_live_<prefix>.<secret>"   // a key with the missing:write scope
     defaultLocale="en"
     namespaces={["common"]}
   >
     <App />
   </SonentaProvider>

   const { t } = useTranslation();
   return <button>{t("checkout.pay")}</button>;

7. Or set it all up in one prompt

   Hand the whole setup to your local AI:

   Set up Sonenta in this repo: run sonenta login with my API key, then sonenta init --project <PROJECT_UUID> (wire the MCP server and write the CLAUDE.md block), install the sonenta-i18n agent, run sonenta doctor, and add the @sonenta/react-i18next SDK with a SonentaProvider around my app.

A simple three-step loop: generate drafts, review, publish.

1. 1. Generate translations (drafts)

   The agent runs locally (0 AI credits): coverage_report → list_untranslated_keys → propose_translations_bulk, honoring your glossary and project context. The result is draft translations in Sonenta, nothing is live yet.

   Using sonenta-i18n, translate my untranslated keys into French and Spanish, then submit them for my review.

2. 2. Review in Sonenta

   Open the Translations editor in the dashboard (/translations). Approve or edit each draft. Only what you approve becomes publishable.

3. 3. Publish to the CDN

   The agent calls publish_cdn. Published translations are served from the CDN and picked up automatically by your app through @sonenta/react-i18next, no code change, no redeploy.

   Publish the approved translations to the CDN.

Publishing happens through the agent’s publish_cdn tool (or the prompt above). There is no separate sonenta publish command, the CLI’s push / pull sync local locale files, not the AI-driven flow above.