Translate your app with Sonenta

1. 1. Install the CLI

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

2. 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 snt_live_<prefix>.<secret>
   # --host defaults to https://api.sonenta.dev

3. 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). In Claude Code, quit your session and start a fresh one afterward: Claude Code reads .mcp.json when the session starts, so a session that was already open keeps running without the Sonenta tools.

   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. 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. 5. Verify the setup

   sonenta doctor                       # checks MCP wired, reachable, scoped

6. 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="snt_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>;

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 every untranslated key into all my target languages, following my glossary and tone.

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.