---
id: getting-started/overview
title: Overview
---

Secundus Stift is typed, build-time-compiled internationalization for TypeScript apps — vanilla or React. You author plain JSON, get compile-time-checked keys, and ship binary packs that load lazily, work offline, and invalidate precisely.

**The pitch in one line:** compile-time typed translations, build-time binary packs (small, optionally obfuscated/encrypted), runtime lazy loading with bounded memory, offline-first locale storage, dev/prod byte-identical.

## How it works

1. **Author** `locales/<locale>/<namespace>.json` + `stift.config.ts` (locales, detection order, loading strategy, security tier). See [Messages & Keys](../authoring/messages.md) and [stift.config.ts](../configuration/config-file.md).
2. **Build** validates, type-gens `src/stift.gen.d.ts` (keys, param shapes, locales become literal types — typos are compile errors), and compiles each locale×namespace into a binary `.dat` pack (msgpack/cbor + compression) plus a `catalog.json`. See [Build: Vite Plugin & CLI](../tooling/build.md).
3. **Run**: the app detects a locale, loads only the namespaces it renders, persists packs for offline use, and revalidates against the catalog on a single ping. No service worker required. See [Offline & Persistence](../runtime/offline-persistence.md) and [Updates & Invalidation](../runtime/updates-invalidation.md).

## Packages

| Package | Role | Docs |
|---|---|---|
| `@secundus-studio/stift-core` | Headless runtime: store, detection, ICU formatter, pack manager | [React setup](../react/setup.md) (core concepts), [Offline](../runtime/offline-persistence.md) |
| `@secundus-studio/stift-react` | React adapter: provider + hooks (re-exports core) | [Setup & Boot Modes](../react/setup.md), [Translating](../react/translating.md) |
| `@secundus-studio/stift-generator` | Build core: config, discovery, typegen, pack compiler | [stift.config.ts](../configuration/config-file.md) |
| `@secundus-studio/stift-vite-plugin` | Vite integration: `virtual:stift/runtime`, dev/prod packs | [Build](../tooling/build.md) |
| `@secundus-studio/stift-cli` | `stift` bin: `generate`, `watch`, `compile` | [Build](../tooling/build.md) |
| `@secundus-studio/stift-tanstack-router-plugin` | TanStack Router: URL rewriting + locale runtime | [Setup](../react/setup.md) |
| `@secundus-studio/stift-tanstack-devtool-plugin` | TanStack Devtools panel: live editing, pack state | [Devtools](../tooling/devtools.md) |
| `@secundus-studio/stift-format` | Optional tree-shakable formatters (units, ordinals…) | [Units](../react/units.md) |
| `@secundus-studio/stift-persisters` | Offline pack storage: OPFS / IndexedDB / Cache API chain | [Offline & Persistence](../runtime/offline-persistence.md) |

## Enough talk, show me some code

**Vanilla TypeScript** (Node, browser, anywhere):

```ts
import { createStift } from '@secundus-studio/stift-core'
import { createStiftRuntime } from 'virtual:stift/runtime' // emitted by the vite-plugin

const Stift = createStift({ ...createStiftRuntime(), persister })
await Stift.initialize({ locale: await Stift.detectLocale() })
Stift.scope('common')('greeting', { name: 'Ada' }) // typed keys + params
```

**React**:

```tsx
<StiftProvider Stift={Stift} boot={() => Stift.initialize({ locale })}>
  <BootFallback fallback={<Spinner />}>
    <App />
  </BootFallback>
</StiftProvider>

const { t } = useTranslation('common')
t('greeting', { name: 'Ada' })
```

[//]: # 'Example'

## What now?

- New here? Follow the [Quickstart](../react/quickstart.md) — install to first translated string in eight steps.
- Installing into an existing app? See [Installation](./installation.md).
- Wondering how keys stay in sync across locales? Read [Messages & Keys](../authoring/messages.md) — the default locale is the schema.

[//]: # 'Materials'