Skip to content
LionRapid Docs

Quickstart

The LionRapid SDK is a TypeScript-first localization library with a server-first design: your translations live on the LionRapid platform, your app reads them at runtime through a cache-first client, and a CLI generates TypeScript types from the server so translation keys and their parameters are checked at compile time. This page takes you from an empty project to a translated, type-checked string.

What you need

Section titled “What you need”
  • A continuous localization project on the platform and an integration key for it — see Continuous localization for the project side and Authentication for the key.
  • Node.js 18 or later for the tooling. The client itself runs in browsers and in Node.
  • Nothing else: the SDK packages are published publicly to the npm registry under the @lionrapid scope, so there is no registry setup and no token.

Install the packages

Section titled “Install the packages”

Install the core client and the ICU formatters plugin, plus the type-generation CLI as a dev dependency:

Terminal window
npm install @lionrapid/core @lionrapid/formatters
npm install --save-dev @lionrapid/cli

React apps also install the React bindings, covered in SDK: React:

Terminal window
npm install @lionrapid/react

Create a client

Section titled “Create a client”

The client is assembled with LionRapidBuilder: pass the base configuration to init(), register the pieces you want with use(), and call build(). A typical setup uses an in-memory cache, a network repository pointed at your LionRapid server, and the ICU formatters plugin:

import {
  LionRapidBuilder,
  MemoryRepository,
  NetworkRepository,
} from '@lionrapid/core';
import { coreFormattersPlugin } from '@lionrapid/formatters';


const lionRapid = await LionRapidBuilder.init({
  defaultLocale: 'en',
  fallbackLocale: 'en',
  namespace: 'app',
})
  .use(new MemoryRepository({ enabled: true, options: { maxSize: 1000 } }))
  .use(
    new NetworkRepository({
      enabled: true,
      options: {
        baseUrl: 'https://your-lionrapid-host',
        apiKey: process.env.LIONRAPID_INTEGRATION_KEY,
        preloadNamespaces: [{ locale: 'en', namespace: 'app', eager: true }],
        syncMissing: { enabled: true, debounceMs: 500, batchSize: 50 },
      },
    })
  )
  .use(coreFormattersPlugin)
  .build();

What each piece does:

  • init() config — the default locale, the locale to fall back to, and the default namespace used when a key has no explicit namespace: prefix.
  • MemoryRepository — a synchronous in-memory cache. Translations found here are returned instantly.
  • NetworkRepository — reads translations from the platform’s integration endpoints and syncs missing keys back. The apiKey is your integration key, sent as a bearer token. preloadNamespaces fetches the app namespace during build(), so the first render already has data.
  • coreFormattersPlugin — ICU MessageFormat support: interpolation, plurals, select, number/date/currency formatting.

build() is asynchronous because it wires the handler chain and performs the eager preloads. Create the instance once, at app startup, and share it.

Translate your first string

Section titled “Translate your first string”
// Key only — returns the translation, or the key itself while loading.
lionRapid.t('welcome');


// With ICU parameters.
lionRapid.t('greeting', { name: 'Ada' });


// With parameters and a default value used until the server answers
// (and synced to the platform as source text if the key is new).
lionRapid.t('greeting', { name: 'Ada' }, 'Hello {name}!');

t() is synchronous and never blocks: if the key is already cached it returns the translation immediately; otherwise it returns the default value (or the key) and loads the real translation in the background. Subsequent calls return the cached translation. The React bindings re-render automatically when that happens; in vanilla JS you can subscribe to events — see SDK: core.

Switching languages loads and caches the new locale:

await lionRapid.changeLanguage('fi', { preloadNamespaces: ['app'] });

Let the app report missing keys

Section titled “Let the app report missing keys”

Because syncMissing is enabled in the setup above, any key the server does not know yet is queued, debounced for 500 ms, batched up to 50 items, and sent to the platform in a single batch sync call. The key and its default value appear in your continuous project as new source strings, ready for translation. Details and tuning are in SDK: core.

Generate types

Section titled “Generate types”

This is the part that makes translations compile-time safe. The CLI reads a lionrapid.yml describing where your translation files live, then writes one TypeScript declaration file from them. Scaffold the config once:

Terminal window
npx lionrapid init

Then generate:

Terminal window
npx lionrapid types generate

The declaration lands at types/translations.d.ts unless you set typesOutput. Make sure that path is covered by your tsconfig.json include. To type against the live server schema instead of your local files, add --server — see SDK: types CLI. From then on:

lionRapid.t('greeting', { name: 'Ada' }); // compiles
lionRapid.t('greeting'); // error: 'name' is missing
lionRapid.t('greetnig', { name: 'Ada' }); // error: unknown key

Keys without parameters, ICU plural counts (typed number), and select options (typed as literal unions) are all inferred from the server schema. Watch mode, strict ICU mode, and CI usage are covered in SDK: types CLI.

Where to go next

Section titled “Where to go next”