# Translations API

Every export of kitr/i18n, with its signature.

Every export of `kitr/i18n`, `kitr/i18n/provider`, read from the published type definitions. The [guide](/packages/i18n) shows them in use.

## kitr/i18n

Re-exports `i18next`, `react-i18next` unchanged, plus the following.

### createI18n

```ts
function createI18n(config: I18nConfig, initialLocale?: string): i18n;
```

Creates an isolated i18next instance from your config, already initialised with react-i18next.
The locale is `initialLocale`, else the detected one when `detect` is on, else `defaultLocale`.

### detectLocale

```ts
function detectLocale(supported: string[], storageKey?: string): string | undefined;
```

In the browser, the saved choice under `storageKey` in localStorage, else the best match for
`navigator.languages`. Returns `undefined` on the server or when nothing matches.

### matchLocale

```ts
function matchLocale(candidates: string | readonly string[], supported: string[]): string | undefined;
```

Pick the best supported locale from an `Accept-Language` header (server) or a language list.

### defineConfig

```ts
const defineConfig: <const C extends I18nConfig>(config: C) => C;
```

Types `config/i18n.ts`. Returns the object you pass, unchanged.

### I18nConfig

```ts
interface I18nConfig extends Omit<InitOptions, 'resources' | 'lng'> {
  /** Every locale's strings, keyed by locale then namespace: `{ en: { common: { hello: 'Hello' } } }`. */
  resources: Record<string, Record<string, Record<string, unknown>>>;
  /** The locale used when nothing better matches, and the fallback for missing keys. */
  defaultLocale: string;
  /** The locales the app supports. Default: the keys of `resources`. */
  locales?: string[];
  /** Detect from `navigator.language` (client) or `Accept-Language` (server). Default true. */
  detect?: boolean;
  /** Query/cookie/storage key for an explicit choice. Default `locale`. */
  storageKey?: string;
}
```

The options in `config/i18n.ts`: your strings per locale, the fallback locale and detection.
Any other i18next init option passes straight through.

### TranslationKeys

```ts
type TranslationKeys<R, Prefix extends string = ''> = {
  [K in keyof R & string]: R[K] extends string ? `${Prefix}${K}` : TranslationKeys<R[K], `${Prefix}${K}.`>;
}[keyof R & string];
```

Keys of a resource bundle as `namespace:key.path` strings, for typed `t()`.

## kitr/i18n/provider

### i18nProvider

```ts
const i18nProvider: KitrProvider;
```

Binds `i18n` from `config/i18n.ts` and wraps the tree in I18nextProvider.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->