# Stift by Secundus

> Typed, build-time-compiled internationalization for TypeScript apps, vanilla or React. Docs 0.4.0 · unreleased — pin this exact version, it is pre-release.
> Packages: @secundus-studio/stift-cli@0.4.0, @secundus-studio/stift-core@0.4.0, @secundus-studio/stift-format@0.4.0, @secundus-studio/stift-generator@0.4.0, @secundus-studio/stift-persisters@0.4.0, @secundus-studio/stift-react@0.4.0, @secundus-studio/stift-tanstack-devtool-plugin@0.4.0, @secundus-studio/stift-tanstack-router-plugin@0.4.0, @secundus-studio/stift-vite-plugin@0.4.0.
> Frameworks: React, Vanilla TypeScript.
>
> Use this index as the routing layer for the docs. Fetch one linked Markdown page at a time, and prefer the track-specific page when the developer names a framework.
> Every link below is raw markdown (page URL plus `.md`), ready to read with no rendering step.

## Getting Started (React)
- [Overview](https://stift.secundus.studio/docs/latest/react/getting-started/overview.md)
- [Installation](https://stift.secundus.studio/docs/latest/react/getting-started/installation.md)
- [AI Setup Prompt](https://stift.secundus.studio/docs/latest/react/getting-started/ai-setup.md)

## Authoring Translations (React)
- [Messages & Keys](https://stift.secundus.studio/docs/latest/react/authoring/messages.md)
- [ICU Select & Plural](https://stift.secundus.studio/docs/latest/react/authoring/icu-select-plural.md)
- [Dialects](https://stift.secundus.studio/docs/latest/react/authoring/dialects.md)

## Configuration (React)
- [stift.config.ts](https://stift.secundus.studio/docs/latest/react/configuration/config-file.md)
- [Loading Strategies](https://stift.secundus.studio/docs/latest/react/configuration/loading-strategies.md)

## Runtime (React)
- [Offline & Persistence](https://stift.secundus.studio/docs/latest/react/runtime/offline-persistence.md)
- [Updates & Invalidation](https://stift.secundus.studio/docs/latest/react/runtime/updates-invalidation.md)

## React (React)
- [Quickstart](https://stift.secundus.studio/docs/latest/react/quickstart.md)
- [Setup & Boot Modes](https://stift.secundus.studio/docs/latest/react/setup.md)
- [Translating & Values](https://stift.secundus.studio/docs/latest/react/translating.md)
- [Units](https://stift.secundus.studio/docs/latest/react/units.md)

## Tooling (React)
- [Build: Vite Plugin & CLI](https://stift.secundus.studio/docs/latest/react/tooling/build.md)
- [Devtools](https://stift.secundus.studio/docs/latest/react/tooling/devtools.md)

## API (React)
- [useTranslation](https://stift.secundus.studio/docs/latest/react/api/use-translation.md)
- [useLocale](https://stift.secundus.studio/docs/latest/react/api/use-locale.md)
- [useFormatter](https://stift.secundus.studio/docs/latest/react/api/use-formatter.md)
- [useUnits](https://stift.secundus.studio/docs/latest/react/api/use-units.md)
- [useConfig](https://stift.secundus.studio/docs/latest/react/api/use-config.md)
- [usePackStatus](https://stift.secundus.studio/docs/latest/react/api/use-pack-status.md)
- [Provider & Scopes](https://stift.secundus.studio/docs/latest/react/api/components.md)

## Getting Started (Vanilla TypeScript)
- [Overview](https://stift.secundus.studio/docs/latest/vanilla/getting-started/overview.md)
- [Installation](https://stift.secundus.studio/docs/latest/vanilla/getting-started/installation.md)
- [AI Setup Prompt](https://stift.secundus.studio/docs/latest/vanilla/getting-started/ai-setup.md)

## Authoring Translations (Vanilla TypeScript)
- [Messages & Keys](https://stift.secundus.studio/docs/latest/vanilla/authoring/messages.md)
- [ICU Select & Plural](https://stift.secundus.studio/docs/latest/vanilla/authoring/icu-select-plural.md)
- [Dialects](https://stift.secundus.studio/docs/latest/vanilla/authoring/dialects.md)

## Configuration (Vanilla TypeScript)
- [stift.config.ts](https://stift.secundus.studio/docs/latest/vanilla/configuration/config-file.md)
- [Loading Strategies](https://stift.secundus.studio/docs/latest/vanilla/configuration/loading-strategies.md)

## Runtime (Vanilla TypeScript)
- [Offline & Persistence](https://stift.secundus.studio/docs/latest/vanilla/runtime/offline-persistence.md)
- [Updates & Invalidation](https://stift.secundus.studio/docs/latest/vanilla/runtime/updates-invalidation.md)

## Core (Vanilla TypeScript)
- [Quickstart](https://stift.secundus.studio/docs/latest/vanilla/quickstart.md)
- [Setup & Boot](https://stift.secundus.studio/docs/latest/vanilla/setup.md)
- [Translating & Formatting](https://stift.secundus.studio/docs/latest/vanilla/translating.md)
- [Units](https://stift.secundus.studio/docs/latest/vanilla/units.md)

## Tooling (Vanilla TypeScript)
- [Build: Vite Plugin & CLI](https://stift.secundus.studio/docs/latest/vanilla/tooling/build.md)

## API (Vanilla TypeScript)
- [Translating](https://stift.secundus.studio/docs/latest/vanilla/api/translate.md)
- [createStift](https://stift.secundus.studio/docs/latest/vanilla/api/create-stift.md)
- [Stift instance](https://stift.secundus.studio/docs/latest/vanilla/api/stift.md)
- [Formatting](https://stift.secundus.studio/docs/latest/vanilla/api/format.md)

## Agent skills
>
> Each skill states when to load it. Load with `pnpm exec intent load <package>#<skill>`.
- @secundus-studio/stift-generator#authoring-translations: Author translations in Stift — the default locale is the schema (new keys propagate to every locale automatically), non-default locales are values-only, message shapes (string / { value, description?, maxLength? }), ICU select/plural driven by context params, rich/markdown messages, and how to write dialect-specific translations (ar-SY-x-lattakia) with correct inheritance. Use when adding, editing, or translating message keys, writing locale files, or deciding where a translation belongs. (load: `pnpm exec intent load @secundus-studio/stift-generator#authoring-translations`)
- @secundus-studio/stift-vite-plugin#build: Wire the @secundus-studio/stift-vite-plugin into a Vite app — stiftPlugin options, generated files (stift.gen.d.ts type augmentation and the virtual:stift/runtime module), and the devtools write bridge. Use when adding Stift to a Vite build, regenerating the typegen, or enabling devtools file writes. (load: `pnpm exec intent load @secundus-studio/stift-vite-plugin#build`)
- @secundus-studio/stift-generator#config: Write and validate stift.config.ts with @secundus-studio/stift-generator — locales (incl. registered dialects), namespaces, messageFormat, params/grammatical agreement, units, memory, loadingStrategy, detection, and security tiers. Use when creating or editing the Stift config file, adding locales or namespaces, configuring detection order, or choosing a security/obfuscation tier. (load: `pnpm exec intent load @secundus-studio/stift-generator#config`)
- @secundus-studio/stift-core#core: Configure Stift's headless core — install, wire detectors and the persisted-state backend into createStift, and run the offline-first boot loop (detectLocale → setLocale → initialize). Use when creating the Stift instance, booting an app, adding locale detection or a persisted preference, or debugging the boot sequence. (load: `pnpm exec intent load @secundus-studio/stift-core#core`)
- @secundus-studio/stift-tanstack-devtool-plugin#devtools: Mount the Stift devtools panel inside the TanStack Devtools shell — createStiftDevtoolsPlugin, the [Plugin, NoOpPlugin] pair, import.meta.env.DEV gating, allowFileWrites, and the Vite dev-server bridge (/__stift_devtools/*). Use when debugging locale switching, namespace packs, missing-key/param logs, or enabling live translation editing in dev. (load: `pnpm exec intent load @secundus-studio/stift-tanstack-devtool-plugin#devtools`)
- @secundus-studio/stift-vite-plugin#getting-started: Initialize Stift in a fresh repo end-to-end — install @secundus-studio/stift-react + @secundus-studio/stift-vite-plugin, write stift.config.ts, wire the Vite plugin, create the Stift instance and boot it, add the first namespace/key, and verify with devtools live editing. Use when onboarding a repo to Stift, scaffolding a new app, or wiring Stift from scratch. The canonical reference is examples/tanstack-spa. (load: `pnpm exec intent load @secundus-studio/stift-vite-plugin#getting-started`)
- @secundus-studio/stift-core#locales: The Stift locale & dialect model — BCP 47 tags, what a dialect is (base locale + variant/private-use subtags, e.g. ar-SY-x-lattakia = the Lattakia dialect of Syrian Arabic), fallback chains (most-specific → least → default), RFC 4647 resolution, per-locale numbering systems, and dialect-safe persistence. Use when reading or writing locale tags, deciding which locale files to add or edit, or debugging why a dialect inherits or overrides translations. (load: `pnpm exec intent load @secundus-studio/stift-core#locales`)
- @secundus-studio/stift-core#offline: Configure Stift offline/PWA use — persisters (OPFS, IndexedDB), pack install/activate, loading and boot strategies, pack size, and cache invalidation (Stift.pack.checkForUpdates / refreshStale). Use when making an Stift app work offline, caching locale packs, managing install/activate lifecycle, or refreshing stale translations. (load: `pnpm exec intent load @secundus-studio/stift-core#offline`)
- @secundus-studio/stift-generator#params-units: Declare and use Stift context params (grammatical agreement) and units correctly — the units-vs-params distinction (params change which translation is selected, units only change how a number renders — never mix the two), defaults.all requirement, per-locale defaults, canonical values/supportedValues, and common config mistakes. Use when writing the params/units blocks of stift.config.ts, adding a context param, configuring unit categories, or deciding whether a value belongs in params or units. (load: `pnpm exec intent load @secundus-studio/stift-generator#params-units`)
- @secundus-studio/stift-react#react: Use the @secundus-studio/stift-react adapter — StiftProvider, the hooks (useStift, useTranslation, useLocale, useFormatter, useConfig, usePackStatus, useUnits), the g11n/stift/stift taxonomy, t.rich/t.markdown, LocaleScope params and grammatical agreement. Use when building React UI with Stift, translating messages, switching locales, reading runtime config, or formatting numbers/dates/currencies/units. (load: `pnpm exec intent load @secundus-studio/stift-react#react`)
- @secundus-studio/stift-tanstack-router-plugin#router: Integrate @secundus-studio/stift-tanstack-router-plugin with TanStack Router — URL rewriting (localize/deLocalize/shouldRedirect), persist-vs-infer locale adapters (cookie, localStorage, Accept-Language), and createLocaleRuntime for offline-safe locale resolution. Use when adding locale-aware URLs to a TanStack app, rewriting /en/... paths, redirecting to the preferred locale, or persisting the user's locale choice. (load: `pnpm exec intent load @secundus-studio/stift-tanstack-router-plugin#router`)
- @secundus-studio/stift-react#units: Use Stift's runtime units API in React — useUnits (units, setUnit, resetUnit, resetAllUnits, getUnit, getUnitValues), the unit-category formatters on useFormatter (formatLength/formatMass/formatArea/formatTemperature/formatDigital), the base-unit value contract, per-locale defaults vs global setUnit overrides, persisted state, and unit pickers. Use when rendering or choosing measurement units, converting stored base-unit values into the active unit, or building a unit preference UI. (load: `pnpm exec intent load @secundus-studio/stift-react#units`)
- @secundus-studio/stift-react#values: Pass values to Stift messages at runtime and supply context params — t() interpolation, ICU select/plural params, t.rich and t.markdown values, supplying grammatical-agreement context via LocaleScope and useLocale().context, setParam overrides, and locale-aware formatting with useFormatter (number/date/time/relativeTime/list). Use when rendering a message with values, formatting numbers/dates/lists, or supplying gender/politeness context in a React component. (load: `pnpm exec intent load @secundus-studio/stift-react#values`)