# SDK: i18n

> @pithyx/sdk/i18n: createI18n for texts as ICU MessageFormat JSON in the user language.

Source: https://pithyx.org/docs/reference/sdk/i18n/
Markdown: https://pithyx.org/docs/reference/sdk/i18n.md

`@pithyx/sdk/i18n` is an optional helper for apps that keep their texts as ICU MessageFormat JSON, the format the desktop uses. Apps may use any other i18n library; the SDK only hands them the locale.

Generated from the TSDoc comments of @pithyx/sdk 1.0.0-rc.9 at build time; the text below the headings is the comment in the source.

## Interfaces

### Messages

Texts of one language: nested objects of ICU messages.

#### Indexable

```ts
[key: string]: string | Messages
```

---

### I18n

Texts in the app's current language, from [createI18n](#createi18n).

#### Properties

##### language

```ts
readonly language: string;
```

The language whose texts are in use: the user's, or its base language, or `en`.

#### Methods

##### t()

```ts
t(key, params?): string;
```

The text for a dotted key with its parameters; the key itself when no language has it.

###### Parameters

| Parameter | Type                            | Description                                                        |
| --------- | ------------------------------- | ------------------------------------------------------------------ |
| `key`     | `string`                        | A dotted key such as `files.count`.                                |
| `params?` | `Record`\<`string`, `unknown`\> | Values for the message's placeholders, for example `{ count: 3 }`. |

###### Returns

`string`

The formatted text in the current language, or in English when the language lacks the key.

## Functions

### pickLanguage()

```ts
function pickLanguage(locale, available): string;
```

Picks the user's language, then its base language (`de` for `de-AT`), then `en`.

#### Parameters

| Parameter   | Type                | Description                          |
| ----------- | ------------------- | ------------------------------------ |
| `locale`    | `string`            | A BCP 47 tag such as `de-AT`.        |
| `available` | readonly `string`[] | The languages the app has texts for. |

#### Returns

`string`

One of `available`, or `en`.

---

### createI18n()

```ts
function createI18n(app, messages): I18n;
```

Texts for the app's current locale, following `localeChange`. `en` is the fallback for keys a language lacks.
Messages are compiled once per language and key.

#### Parameters

| Parameter  | Type                                                                     | Description                                    |
| ---------- | ------------------------------------------------------------------------ | ---------------------------------------------- |
| `app`      | `Pick`\<[`PithyxApp`](https://pithyx.org/docs/reference/sdk/app/#pithyxapp), `"context"`\> | The connected app; only its `context` is read. |
| `messages` | `object` & `Partial`\<`Record`\<`string`, [`Messages`](#messages)\>\>    | Texts per language; `en` is required.          |

#### Returns

[`I18n`](#i18n)

Texts that follow the user's locale.

#### Throws

A syntax error of `intl-messageformat` from `t` when a message is not valid ICU MessageFormat.