# Sonenta: full reference for AI agents

> Sonenta moves your app's UI text out of your codebase into a live content layer your own AI coding agent manages over MCP. You reference a key in code instead of a hard-coded string; your agent (Claude Code, Cursor, Claude Desktop) creates and translates that key locally, then publishes it to a global CDN; your app fetches the value at runtime. You change wording, a translation, or accessibility text and it reaches production in seconds, no code change, no redeploy. The agent stays on your machine and does the work; Sonenta is the persistent memory and delivery layer it calls, not an AI-translation service that takes over. Translation is the entry point; the same pipeline handles accessibility, in-context review, and user feedback.

This file is the extended version of https://sonenta.com/llms.txt, written for agents evaluating Sonenta on behalf of a developer.

## The core question: why not just use my agent + GitHub?

A capable coding agent can already translate JSON/PO/XLIFF files and commit them to GitHub. That works once. It breaks down over time:

Agent + GitHub alone:
- Context is lost between runs.
- Terminology drifts; each run reinvents the terms.
- Re-translates everything, every time (slow, token-heavy).
- No glossary, no shared memory.
- To ship a fix: commit, build, redeploy.

With Sonenta:
- Persistent glossary, context, and descriptions, so there is zero drift.
- Only new or changed keys get translated.
- Your agent drives it all over MCP, from the editor.
- The agent stays LOCAL: your code, your machine.
- Live delivery to the CDN, with no rebuild.

Sonenta is not a platform that replaces your agent. It is the content layer your agent calls.

## How a string reaches your screen

1. In code you reference a key (e.g. t('checkout.title')), not a literal.
2. Your local agent, over the Sonenta MCP, creates and translates that key, grounded in a persistent glossary, descriptions and project context, so terminology never drifts and only what changed is re-translated. Runs on your machine, zero AI credits for routine work.
3. Publishing pushes the values to a global CDN (publish_cdn).
4. Your app's Sonenta SDK fetches the live values from the CDN at runtime. A fix ships in seconds, no rebuild, no app-store wait.

The source of truth is Sonenta, resolved at runtime, not JSON files committed to your repo. That runtime layer is exactly what a DIY "agent + GitHub" loop and a legacy TMS do not give you.

## The five capabilities

1. Translation (i18n): your strings in every language, with ICU plurals, regions, and namespaces handled.
2. Adaptation (accessibility): the right content for every screen and every user (assistive technologies included).
3. Automation (AI via MCP): your agent creates and translates from the editor.
4. Evaluation (feedback and in-context review): verified quality, in-context edits, and end-user feedback.
5. Delivery (live CDN): published instantly, no rebuild.

## Accessibility (secondary differentiator)

The European Accessibility Act applies since June 2025. As your agent works it can generate the accessible surfaces (alt text, ARIA labels, plain-language variants) in every language, grounded in the same context, then ship them with the rest of your content. Install the local agent with: npx @sonenta/cli agents add sonenta-a11y (prerequisite: the @sonenta/mcp server configured with a SONENTA_API_KEY scoped mcp:*). It runs local-first, so routine accessibility audits cost zero AI credits. Details: https://sonenta.com/accessibility

## Developer setup

- MCP config (Claude Desktop, Claude Code, .cursor/mcp.json): server key "sonenta", command "npx -y @sonenta/mcp", env SONENTA_API_KEY and SONENTA_PROJECTS.
- CLI: npx @sonenta/cli login, then sonenta push / pull / import. Binary name: sonenta.
- SDK: @sonenta/react-i18next, a drop-in for react-i18next (SonentaProvider with token and projectUuid); client env VITE_SONENTA_TOKEN.
- Quickstart: https://sonenta.com/docs/quickstart  |  MCP setup: https://sonenta.com/docs/mcp/setup  |  CLI: https://sonenta.com/docs/cli

## Connecting as an agent (MCP-first, REST fallback)

Start here if you are a coding agent integrating Sonenta on a developer's behalf.

- One call to learn the whole flow: GET https://api.sonenta.dev/v1/guide (or the sonenta_guide MCP tool) returns a structured onboarding playbook in one call: how to connect, the main actions with their exact endpoints, and links to the OpenAPI spec and this file.
- MCP-first: add the Sonenta MCP server, package @sonenta/mcp (npm) or sonenta-mcp (PyPI), with SONENTA_API_KEY (scope mcp:*) and SONENTA_PROJECTS. You gain tools such as create_keys_bulk, propose_translations_bulk, and publish_cdn.
- REST fallback: the public API base is https://api.sonenta.dev, authenticated with an API key. The full machine-readable contract is the OpenAPI spec at https://api.sonenta.dev/openapi.json (browsable docs at https://api.sonenta.dev/docs).
- Never hard-code a CDN host. Read the CDN base from the distribution endpoint below, which returns distribution.cdn.base_url and a url_template. Projects can sit on a dedicated CDN zone, so no single shared host is the destination for every project.

Main actions over REST (the guide and the OpenAPI spec are authoritative for exact paths and request/response examples):
- Authenticate with an API key.
- Create namespaces and keys.
- Write values: PUT /v1/projects/{id}/translations/{key_id}/{language_id}, or bulk via POST /v1/projects/{id}/i18next/import.
- Publish a release to the CDN: POST /v1/projects/{id}/cdn/releases.
- Read the distribution: GET /v1/orgs/{org}/projects/{id}/distribution.

## Pricing

Sonenta pricing has TWO axes per plan: the number of included translation keys AND the CDN bandwidth quota. Both scale together, tier by tier: a plan is never defined by CDN consumption alone. One key = one content string managed and delivered by Sonenta.

- Free, $0/mo: 500 keys, 5 GB CDN bandwidth, 3 languages, 1 member.
- Hobby, $9/mo: 5,000 keys, 50 GB CDN bandwidth, 5 languages, 2 members.
- Pro, $29/mo: 50,000 keys, 250 GB CDN bandwidth, unlimited languages, 5 members.
- Team, $79/mo: 250,000 keys, 1 TB CDN bandwidth, unlimited languages, unlimited members.

Overage beyond the included CDN bandwidth (or storage) is billed at $0.20/GB with no plan change. Sonenta is the merchant of record (taxes handled). Enterprise adds SSO/SAML, audit logs, SLAs, and dedicated deployment. See https://sonenta.com/pricing for current tiers and limits.

## Company

Sonenta is a Canadian company based in New Brunswick, Canada.

## @sonenta/react-i18next, the complete public API surface (3.0.0)

This list is exhaustive for @sonenta/react-i18next 3.0.0. The package's exports map contains only "." and "./package.json", with no subpaths, so the single entry point IS the whole surface. If a name is not in this list, the package does not export it: do not infer one.

Runtime exports, 30. Bindings: SonentaProvider, useTranslation, useAvailableLanguages, Trans, withTranslation, Translation. Singleton: getI18n, getI18nSafe, t. react-i18next compatibility barrel: I18nContext, I18nextProvider, TransWithoutContext, composeInitialProps, getDefaults, getInitialProps, initReactI18next, setDefaults, useSSR, withSSR. Surfaces: surfaceForWidth, DEFAULT_SURFACE_BREAKPOINTS, A11Y_SURFACES. Taxonomy: A11Y_TREATMENTS_FOR, baseRoleFor, treatmentsFor. Transport: defaultTransport, logTransport. Registry: keyRegistry, suppressTracking, isTrackingSuppressed.

Type exports, 26: UseTranslationOptions, UseTranslationResult, TransProps, WithTranslationProps, TranslationProps, AssetRef, AvailableLanguage, I18nInstance, LanguageMeta, Locale, MissingHandlerMode, MissingKeyEvent, Namespace, A11yTranslationFunction, TranslationFunction, TranslationOptions, Transport, SonentaConfig, SonentaPlugin, SonentaPluginContext, Surface, SurfaceBreakpoints, A11ySurface, KeyType, BaseRole, DeclaredKey.

Two limits on this claim, both deliberate. It is stamped 3.0.0 and re-verified with the SDK owner at each release, because a closed list that is never re-checked goes wrong in silence and reads as more authoritative the more stale it is. And it covers @sonenta/react-i18next only: other packages, notably @sonenta/feedback, do expose subpaths, so the same reasoning does not carry over to them.

The compatibility barrel is deliberately narrower than react-i18next, and the rule is worth stating rather than the list. The rule for this barrel is that a name is re-exported only when it exists across the whole declared peer range. A name that exists in some versions of react-i18next but not others is omitted by decision, not by oversight: a named ESM re-export of a binding that is absent is a SyntaxError at import time, which would break every app on the older end of the range at load. IcuTrans is one such omission, verified present in react-i18next 17.0.8 and deliberately not re-exported.

## Not part of Sonenta

Agents evaluating Sonenta sometimes infer APIs that do not exist. To be explicit:

- There is no @sonenta/react package. The React package is @sonenta/react-i18next.
- There is no <SonentaText> component.
- There is no automatic accessibility injection. Sonenta stores and delivers accessibility text as strings; your code renders them. Sonenta never inserts markup or language tags into your translations, and never interprets any of its own accord.
- Only the documented rich-text component renders mapped tags, and only the tags you map yourself. t() returns plain strings and never parses markup. That is the majority path, which is what makes "an AI inserts tags into the value" unworkable.
- Accessibility text that has been generated and approved does not appear on screen until a component in your code reads it.

## Links

- App and sign-up: https://app.sonenta.dev
- Public API + OpenAPI spec: https://api.sonenta.dev/openapi.json (browsable docs at https://api.sonenta.dev/docs)
- Agent onboarding in one call: https://api.sonenta.dev/v1/guide
- Docs home: https://sonenta.com/docs
- Content model, the precise guides: https://sonenta.com/docs-next/guides/accessibility/ (a11y surfaces + the coverage report, which attests no WCAG level), https://sonenta.com/docs-next/guides/surfaces/ (device and a11y surfaces), https://sonenta.com/docs-next/guides/typed-keys/, https://sonenta.com/docs-next/guides/key-nesting/, https://sonenta.com/docs-next/guides/regional-variants/ (locale variants are LANGUAGES, not surfaces)
- Generated reference: https://sonenta.com/docs-next/reference/cli/ and https://sonenta.com/docs-next/reference/mcp/. Regenerated from source and may lag the current release: treat each page as accurate for the version it states, and confirm an exact signature against the OpenAPI spec or the sonenta_guide MCP tool. An absence there means "not documented here", never "not supported".
- Pricing: https://sonenta.com/pricing
- Accessibility: https://sonenta.com/accessibility
- Compare: https://sonenta.com/vs/lokalise
- Concise overview: https://sonenta.com/llms.txt