# t()

Lit directive that renders a translated label by key. Keys are batched into one GET to the endpoint set by the nearest `wordingProvider` ancestor attribute, and results are cached in `localStorage`.

## Import

<sonic-code language="typescript">
  <template>
import { t } from "@supersoniks/concorde/directives/Wording";
  </template>
</sonic-code>

`wording` and `w` are aliases of `t`. In plain HTML, use the [`sonic-t`](/core/components/functional/translation) element.

## Usage

Set `serviceURL` and `wordingProvider` on the host component or one of its ancestors, then call `t(key)` in a template. Attributes on elements **inside** the component's own template are not read. Click the button to bump the version and reload the labels.

<docs-lit-demo for="docs-api-config-wording-demo"></docs-lit-demo>

## Endpoint contract

All keys requested in the same tick are sent in one request, appended to `wordingProvider` as `labels[]`:

<sonic-code language="shell">
  <template>
GET {serviceURL}/wording/labels?lang=fr&labels[]=greeting&labels[]=farewell
  </template>
</sonic-code>

The response is a flat map of key to label:

<sonic-code language="json">
  <template>
{ "greeting": "Bonjour", "farewell": "Au revoir" }
  </template>
</sonic-code>

Until the label arrives, `t()` renders an empty string.

## HTML labels

`t()` escapes the label. Use `unsafeWording(key)` for labels that contain trusted HTML.

<sonic-code language="typescript">
  <template>
import { unsafeWording } from "@supersoniks/concorde/directives/Wording";

html`&lt;p&gt;${unsafeWording("terms.notice")}&lt;/p&gt;`;
  </template>
</sonic-code>

## Reloading labels

Labels are fetched again when:

- the `lang` attribute of `<html>` changes
- the number stored at `wordingVersionProvider` changes — bump it after publishing new labels to invalidate the `localStorage` cache

## API reference

| Function | Description |
|----------|-------------|
| `t(key)` · `wording(key)` · `w(key)` | Renders the escaped label for `key` |
| `unsafeWording(key)` | Renders the label as HTML |
| `isWordingReady(key)` | `true` once the label for `key` is loaded |

| Ancestor attribute | Description |
|--------------------|-------------|
| `wordingProvider` | Endpoint path and query, relative to `serviceURL` |
| `wordingVersionProvider` | DataProvider path holding a version number |

Other ancestor attributes (`serviceURL`, `token`, …) apply as for any request: see [API configuration](/docs/misc/api-configuration).