# SDK: i18n

> @pithyx/sdk/i18n: createI18n für Texte als ICU-MessageFormat-JSON in der Sprache des Benutzers.

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

`@pithyx/sdk/i18n` ist ein optionaler Helfer für Apps, die ihre Texte als ICU-MessageFormat-JSON halten, das Format des Desktops. Apps können jede andere i18n-Bibliothek nehmen; das SDK gibt ihnen nur die Locale.

Beim Build aus den TSDoc-Kommentaren von @pithyx/sdk 1.0.0-rc.9 erzeugt; der Text unter den Überschriften ist der Kommentar im Quelltext und bleibt Englisch.

## Schnittstellen

### Messages

Texts of one language: nested objects of ICU messages.

#### Indexierbar

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

---

### I18n

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

#### Eigenschaften

##### language

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

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

#### Methoden

##### t()

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

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

###### Parameter

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

###### Rückgabewert

`string`

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

## Funktionen

### pickLanguage()

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

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

#### Parameter

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

#### Rückgabewert

`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.

#### Parameter

| Parameter  | Typ                                                                         | Beschreibung                                   |
| ---------- | --------------------------------------------------------------------------- | ---------------------------------------------- |
| `app`      | `Pick`\<[`PithyxApp`](https://pithyx.org/de/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.          |

#### Rückgabewert

[`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.