Getting Started

Get the Content SDK running in under 5 minutes.

Installation

npm install @better-i18n/sdk

bun add @better-i18n/sdk

pnpm add @better-i18n/sdk

yarn add @better-i18n/sdk

Setup

Get your API Key

Go to dash.better-i18n.com
Navigate to Settings → API Keys
Select Content as the type
Create and copy your API key

Keep your API key secret. Never commit it to version control. Use environment variables instead.

Create a client

lib/content.ts

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

export const content = createClient({ 
  project: "your-org/your-project", 
  apiKey: process.env.BETTER_I18N_API_KEY!, 
});

Find your project identifier in the dashboard URL: dash.better-i18n.com/{org}/{project}

Fetch content

import { content } from "./lib/content";

// List all content models
const models = await content.getModels();
console.log(models);
// [{ slug: "blog-posts", displayName: "Blog Posts", kind: "collection", entryCount: 12 }]

// List published entries (chainable API)
const { data: posts, total } = await content 
  .from("blog-posts") 
  .eq("status", "published") 
  .limit(10); 

// Get a single entry
const { data: post } = await content 
  .from("blog-posts") 
  .language("en") 
  .single("hello-world"); 

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

Environment Variables

.env

BETTER_I18N_API_KEY=bi-your-api-key // [!code ++]
BETTER_I18N_PROJECT=acme/web-app // [!code ++]

Variable	Required	Description
`BETTER_I18N_API_KEY`	Yes	Your API key from the dashboard
`BETTER_I18N_PROJECT`	Yes	Project identifier in `org/project` format

Your project identifier matches the dashboard URL path: dash.better-i18n.com/acme/web-app → "acme/web-app"

Configuration Options

Option	Type	Required	Default	Description
`project`	`string`	Yes	—	Project identifier in `org/project` format
`apiKey`	`string`	Yes	—	API key for authentication
`apiBase`	`string`	No	`https://content.better-i18n.com`	Custom API base URL
`debug`	`boolean`	No	`false`	Log request URLs and responses to console

Debugging

Enable debug mode to see exactly what the SDK is doing:

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

This logs all requests and responses to the console:

[better-i18n] Client initialized { apiBase: "https://content.better-i18n.com", org: "acme", project: "web-app", base: "https://content.better-i18n.com/v1/content/acme/web-app" }
[better-i18n] → getEntries(blog-posts) https://content.better-i18n.com/v1/content/acme/web-app/models/blog-posts/entries?status=published
[better-i18n] ← 200 OK
[better-i18n]   Response: {"items":[...],"total":24,"hasMore":true}

Framework Integration

The SDK works with any JavaScript framework. For framework-specific wrappers:

Next.js — Use @better-i18n/next for server components with ISR caching
React / TanStack Start — Use @better-i18n/use-intl for React hooks
Any framework — Use @better-i18n/sdk directly with fetch()

On this page