REST API & SDK: Programmatic Translation Management

The better-i18n platform gives developers full programmatic access to translation management — through a TypeScript SDK, a REST API, CLI tools, and an MCP server for AI assistants. Manage keys, translations, languages, and content from your own code and CI pipelines.

Two APIs, Different Purposes

better-i18n exposes two distinct APIs depending on what you're building:

API	Base URL	Auth	Use Case
Translation API	`dash.better-i18n.com/api`	Bearer token	Key management, translations, languages, syncs
Content API	`content.better-i18n.com`	`x-api-key` header	Headless CMS — blog posts, marketing pages, structured content

Both APIs use JSON request/response bodies and follow REST conventions.

Authentication

Generate API keys in Settings → API Keys on your dashboard.

# Translation API (key management, translations)
curl -H "Authorization: Bearer bi18_live_abc123..." \
  https://dash.better-i18n.com/api/...

# Content API (headless CMS)
curl -H "x-api-key: bi-your-api-key" \
  https://content.better-i18n.com/v1/content/acme/web-app/models

Never expose API keys in client-side code. Use environment variables and server-side proxies.

Translation API

The Translation API manages the core i18n workflow: projects, keys, translations, and languages.

Projects

listProjects()          → List all projects you have access to
getProject(project)     → Get project details, languages, and namespaces

Every project is identified by org/project format (e.g., acme/web-app). You'll find this in your i18n.config.ts.

Translation Keys

listKeys(project, options)    → Search and browse translation keys
createKeys(project, keys)     → Create keys with source text and translations
updateKeys(project, updates)  → Update translations for existing keys
deleteKeys(project, keys)     → Soft-delete translation keys

Create keys with translations in one call:

{
  "project": "acme/web-app",
  "keys": [
    {
      "name": "auth.login.title",
      "namespace": "auth",
      "sourceText": "Sign in to your account",
      "translations": {
        "tr": "Hesabınıza giriş yapın",
        "de": "Melden Sie sich bei Ihrem Konto an"
      }
    },
    {
      "name": "auth.login.button",
      "namespace": "auth",
      "sourceText": "Sign in"
    }
  ]
}

Search and filter keys:

{
  "project": "acme/web-app",
  "search": "login",
  "namespaces": ["auth"],
  "missingLanguage": "tr"
}

Update translations with status:

{
  "project": "acme/web-app",
  "translations": [
    {
      "key": "auth.login.title",
      "language": "tr",
      "text": "Hesabınıza giriş yapın",
      "status": "approved"
    }
  ]
}

Languages

addLanguage(project, language)   → Add a new target language
getProject(project)              → See all active languages and progress

Sync Operations

getSyncs(project)    → List recent sync operations (GitHub, CDN, etc.)
getSync(project, id) → Get details of a specific sync job

Content SDK

The @better-i18n/sdk is a TypeScript client for the Content API — our headless CMS for structured content like blog posts, changelog entries, and marketing pages.

Install

npm install @better-i18n/sdk

Initialize

import { createClient } from "@better-i18n/sdk";

const client = createClient({
  project: "acme/web-app",
  apiKey: process.env.BETTER_I18N_API_KEY!,
});

Query Builder (Supabase-style)

The SDK provides a chainable, immutable query builder:

// List published blog posts
const { data: posts, total, hasMore } = await client
  .from("blog-posts")
  .eq("status", "published")
  .order("publishedAt", { ascending: false })
  .expand("author", "category")
  .limit(10);

// Get a single entry in French
const { data: post } = await client
  .from("blog-posts")
  .language("fr")
  .single("getting-started");

console.log(post.title, post.body);

Available Methods

Method	Description
`.eq(field, value)`	Filter by exact value
`.search(term)`	Full-text search on titles
`.language(code)`	Set language for localized content
`.order(field, opts)`	Sort by `publishedAt`, `createdAt`, `updatedAt`, or `title`
`.limit(n)`	Entries per page (1–100)
`.page(n)`	Page number
`.expand(...fields)`	Expand relation fields inline
`.select(...fields)`	Choose which fields to return
`.single(slug)`	Fetch a single entry by slug

REST Endpoints (Under the Hood)

The SDK calls these endpoints:

Method	Endpoint
`GET`	`/v1/content/{org}/{project}/models`
`GET`	`/v1/content/{org}/{project}/models/{model}/entries`
`GET`	`/v1/content/{org}/{project}/models/{model}/entries/{slug}`

CLI Tools

The @better-i18n/cli integrates into your development workflow:

# Detect hardcoded strings in your codebase
better-i18n scan

# Compare local keys vs. cloud project
better-i18n sync

# CI/CD integration with JSON output
better-i18n scan --ci --format json
better-i18n sync --format json

The CLI auto-detects useTranslations() and getTranslations() hooks, extracts namespaces, and reports missing translations — all in under 100ms for typical codebases.

Pre-commit & CI Integration

# Pre-commit hook
npx @better-i18n/cli scan --staged --ci

# GitHub Actions
- run: npx @better-i18n/cli scan --ci --format json

MCP Server for AI Assistants

The better-i18n MCP (Model Context Protocol) server lets AI assistants like Claude, Cursor, and Windsurf manage translations directly from your IDE:

# Install MCP server
npm install @better-i18n/mcp

AI assistants can:

List and search translation keys
Create new keys with translations
Update existing translations
Check sync status
Add new languages

This means you can say "Add German translations for the auth namespace" and your AI assistant handles it through the API.

CDN Delivery

Translations are served globally via our CDN with a predictable URL pattern:

https://cdn.better-i18n.com/{org}/{project}/{locale}/{namespace}.json

For example:

https://cdn.better-i18n.com/acme/web-app/de/common.json

No deployment needed — translations update on the CDN automatically when published.

Platform SDKs

Package	Purpose
`@better-i18n/sdk`	Content API client (TypeScript)
`@better-i18n/cli`	Code scanning & sync (CLI)
`@better-i18n/next`	Next.js runtime integration
`@better-i18n/use-intl`	React translation hooks
`@better-i18n/mcp`	MCP server for AI assistants

All packages are available on npm and work in any JavaScript runtime with native fetch().

Git Integration — Sync translations with your repository via pull requests
Webhooks & Events — Real-time notifications for translation events
Full API Documentation — Complete endpoint reference

REST API & SDK: Programmatic Translation Management