Quickstart

This guide will walk you through setting up Saykit and creating your first translated message.

Prerequisites

Before you begin, make sure you have:

Installed Saykit and the necessary packages for your framework (see Installation)
Configured your build tool (Babel plugin or unplugin)

Step-by-Step Tutorial

Create a configuration file

Create a saykit.config.ts file in your project root:

saykit.config.ts

import { defineConfig } from '@saykit/config';

export default defineConfig({
  sourceLocale: 'en',
  locales: ['en', 'fr', 'es'],
  buckets: [
    {
      include: ['src/**/*.{ts,tsx,js,jsx}'],
      output: 'src/locales/{locale}/messages.{extension}',
    },
  ],
});

This configuration:

Sets English as the source locale
Defines three supported locales (English, French, Spanish)
Scans all TypeScript and JavaScript files in src/
Outputs extracted messages to src/locales/{locale}/messages.json

You can also use JSON format by creating saykit.config.json and omitting the defineConfig wrapper.

Initialize the Say instance

Create a Say instance that will handle your translations:

Vanilla JavaScript
React (Next.js)

src/i18n.ts

import { Say } from 'saykit';

const say = new Say({
  locales: ['en', 'fr', 'es'],
  messages: {
    en: await import('./locales/en/messages.json').then((m) => m.default),
    fr: await import('./locales/fr/messages.json').then((m) => m.default),
    es: await import('./locales/es/messages.json').then((m) => m.default),
  },
});

// Activate the default locale
say.activate('en');

export default say;

src/i18n.ts

import 'server-only';
import { unstable_createWithSay } from '@saykit/react/server';
import { Say } from 'saykit';

const say = new Say({
  locales: ['en', 'fr', 'es'],
  messages: {
    en: await import('./locales/en/messages.json').then((m) => m.default),
    fr: await import('./locales/fr/messages.json').then((m) => m.default),
    es: await import('./locales/es/messages.json').then((m) => m.default),
  },
});

export const withSay = unstable_createWithSay(say);

export default say;

Add translatable messages

Use Saykit’s template literal syntax to mark strings for translation:

Vanilla JavaScript
React

src/index.ts

import say from './i18n';

// Simple message
const greeting = say`Hello, World!`;
console.log(greeting); // "Hello, World!"

// Message with interpolation
const name = 'Alice';
const welcome = say`Welcome, ${name}!`;
console.log(welcome); // "Welcome, Alice!"

// Plural message
const count = 5;
const items = say.plural(count, {
  one: 'You have 1 item',
  other: 'You have # items',
});
console.log(items); // "You have 5 items"

src/app/page.tsx

'use client';
import { Say } from '@saykit/react';

export default function HomePage() {
  const name = 'Alice';

  return (
    <main>
      <h1>
        <Say>Hello, World!</Say>
      </h1>
      <p>
        <Say>Welcome, {name}!</Say>
      </p>
    </main>
  );
}

For server components, wrap your component with withSay:

src/app/[locale]/page.tsx

import { withSay } from '../../i18n';
import { Say } from '@saykit/react';

function HomePage({ params }: { params: Promise<{ locale: string }> }) {
  return (
    <main>
      <Say>Hello from the server!</Say>
    </main>
  );
}

export default withSay(HomePage, (p) => p.params.then((p) => p.locale));

Extract messages

Run the extract command to scan your source files and generate message catalogs:

npx saykit extract

This creates .po files for each locale in your output directory (e.g., src/locales/en/messages.po).

The .po (Portable Object) format is an industry-standard format used by professional translation tools.

Translate your messages

Open the generated .po files and add translations:

msgid "Hello, World!"
msgstr "Bonjour le monde!"

msgid "Welcome, {name}!"
msgstr "Bienvenue, {name}!"

Compile translations

Convert .po files to runtime-ready JSON:

npx saykit compile

This generates messages.json files that your application will load at runtime.

Switch locales

Change the active locale to see your translations:

import say from './i18n';

// Switch to French
say.activate('fr');
console.log(say`Hello, World!`); // "Bonjour le monde!"

// Switch to Spanish
say.activate('es');
console.log(say`Hello, World!`); // "¡Hola, Mundo!"

CLI Commands Reference

Saykit provides three main CLI commands:

`saykit extract`

Scans your source files and extracts translatable messages into .po files.

npx saykit extract

Options:

-v, --verbose - Enable verbose logging
-q, --quiet - Suppress all logging

`saykit compile`

Compiles .po translation files into runtime-ready JSON files.

npx saykit compile

Options:

-v, --verbose - Enable verbose logging
-q, --quiet - Suppress all logging

`saykit build`

Combines extract and compile into a single step.

npx saykit build

Options:

-v, --verbose - Enable verbose logging
-q, --quiet - Suppress all logging

Add these commands to your package.json scripts for easy access:

package.json

{
  "scripts": {
    "i18n:extract": "saykit extract",
    "i18n:compile": "saykit compile",
    "i18n:build": "saykit build"
  }
}

Next Steps

Now that you have Saykit set up, explore more features:

Configuration - Learn about all configuration options
Core Concepts - Understand how Saykit works under the hood
React Integration - Deep dive into React-specific features
Message Formatting - Advanced pluralization, selection, and formatting

Get Started

Core Concepts

Integrations

CLI Reference

Guides

Prerequisites

Step-by-Step Tutorial

CLI Commands Reference

`saykit extract`

`saykit compile`

`saykit build`

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

Integrations

CLI Reference

Guides

​Prerequisites

​Step-by-Step Tutorial

​CLI Commands Reference

​saykit extract

​saykit compile

​saykit build

​Next Steps

Build docs developers (and LLMs) love

Prerequisites

Step-by-Step Tutorial

CLI Commands Reference

`saykit extract`

`saykit compile`

`saykit build`

Next Steps