# `LocalisedText`

The same text in several languages: `{"en-GB": "Rye loaf", "fr-FR": "Pain de seigle"}`.

Use it for content people translate, such as product names. `text.pick` gets the entry for a locale. For your app's own wording, use its translations instead.

## Shape

A map from [`Locale`](/docs/types/type-locale.md) to `Text`.

## Example

```jadpo
type NotATranslation = Failure {
    kind: FailureKind.invalid_value
    message: "That isn't a translated name."
}

var example: LocalisedText = attempt json.read(
    "{\"en-GB\":\"Rye loaf\",\"fr-FR\":\"Pain de seigle\"}",
    as: LocalisedText
) {
    invalid: NotATranslation
}
assert example == example
```

## Good to know

- It arrives as JSON, from a request or from `json.read`, since code can't write out a map with entries.
- `==` tells you whether two are the same. `<` and `list.sort_by` don't take it.

## In JSON

An object of its entries, each key written as its text, in a request, a response or `json.write`:

```json
{"en-GB":"Leek soup","fr-FR":"Soupe aux poireaux"}
{"en-US":"Leek potage"}
{"de-DE":"Lauchsuppe"}
```

## Details

<details>
<summary>Text form, storage, how it is shown, and operations</summary>

`LocalisedText` is in the group Text formats, and has been in Jadpo since 0.1.0.

### Text form

It has no single text form, so `text.from` and `text.parse` don't take it.

### How it is stored

It is stored in one column named for the field, of type `jsonb`. `{"de-DE":"Lauchsuppe"}` is stored as `'{"de-DE":"Lauchsuppe"}'::jsonb`.

### How it is shown to people

`text.format(value, locale:)` shows it to people in their locale.

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `{"en-GB":"Leek soup","fr-FR":"Soupe aux poireaux"}` | `Leek soup` |
| `{"en-US":"Leek potage"}` | `Leek potage` |
| `{"de-DE":"Lauchsuppe"}` | `Lauchsuppe` |
| `{}` | `""` |

### Operations

- `text.pick(value: LocalisedText, locale: Locale) -> Text`: The text in `value` for `locale`: its entry, else the entry of its language (the locale CLDR's likely subtags give for the language first), else the application's default locale's, else the first.

It also takes `text.format`, `json.read`, `json.write` and `==`. [How every standard type behaves](/docs/every-standard-type-meets-one-contract.md) says how they work.

</details>