# Plain HTML

Source: https://verbaly.dev/docs/frameworks/dom

No framework? Plain HTML works just as well, something no other compiler-based i18n tool offers. Mark elements, call `bindDom`, done.

## Installation

The runtime is all this page needs: no plugin and no compiler.

```sh
npm install verbaly
# or: pnpm add verbaly
# or: yarn add verbaly
# or: bun add verbaly
```

Add `@verbaly/compiler` as a dev dependency when you want the `verbaly` command, to check your catalogs or to write each page already translated.

## Usage

```html title="index.html"
<h1 data-verbaly="home.title"></h1>
<p  data-verbaly="inbox" data-verbaly-args='{"count":3}'></p>
<input data-verbaly-attr='{"placeholder":"search.hint"}' />
```

```ts title="main.ts"
import { bindDom, createVerbaly } from 'verbaly';

const messages = {
  es: {
    'home.title': 'Bienvenida',
    inbox: '{count | one: # mensaje | other: # mensajes}',
    'search.hint': 'Buscar',
  },
  en: {
    'home.title': 'Welcome',
    inbox: '{count | one: # message | other: # messages}',
    'search.hint': 'Search',
  },
};

const v = createVerbaly({ locale: 'es', messages });
bindDom(v);         // render + observe

v.setLocale('en');  // every bound node re-renders
```

## Attributes

| Attribute | Purpose |
| --- | --- |
| data-verbaly | Key whose translation becomes the element's text |
| data-verbaly-args | JSON params shared by text and attribute translations |
| data-verbaly-attr | JSON map of attribute → key, e.g. `placeholder`, `title`, `aria-label`. URL attributes (`href`, `src`…) are checked against unsafe schemes the way a browser reads a URL, so a tab or a line break inside the scheme cannot hide one. `on*`, `style` and `srcdoc` are blocked, so a catalog can't inject scripts |
| data-verbaly-rich | Opt-in: render tags in the message as real elements (see Rich text) |
| data-verbaly-links | JSON map of link name → href for named links (see Named links) |

## Rich text

By default translations render via `textContent`, so tags stay literal. Mark the element with `data-verbaly-rich` and tagged messages become real elements:

```json title="locales/en.json"
{ "gate.title": "The build <em>gate</em>" }
```

```html title="index.html"
<h3 data-verbaly="gate.title" data-verbaly-rich></h3>
<!-- renders: The build <em>gate</em> -->
```

One key per sentence, so translators see the whole message and each language keeps its own word order. The safety model:

- Only a **short list of inline tags** renders: `em`, `strong`, `code`, `b`, `i`, `u`, `s`, `small`, `mark`, `sub`, `sup`, `span`, `kbd`, `abbr`, `br`, `wbr`. The last two take no content, so `<br>`, `<br/>` and `<br />` are all a line break.
- Elements are built programmatically, never `innerHTML`, and **attributes never come from the message**.
- Any other tag is unwrapped to inert text: `<script>` in a catalog renders as plain text, no element.
- Override that list with `bindDom(v, { richTags: ['q'] })`.
- HTML entities decode as plain text: named `&lt;`/`&gt;`/`&amp;` and numeric ones alike. Write `&#123;` to show a literal `{` without touching the placeholder syntax.

## Named links

Links are left off that list on purpose: an `<a>` without attributes is useless, and attributes never come from messages. Instead you name the link in the message and provide the `href` from code:

```json title="locales/en.json"
{ "cta": "Read the <docs>guide</docs> now" }
```

```ts title="main.ts"
bindDom(v, {
  richLinks: { docs: { href: '/docs', target: '_blank', rel: 'noopener' } },
});
// renders: Read the <a href="/docs" target="_blank" rel="noopener">guide</a> now
```

```title="index.html: per-element override"
<p data-verbaly="cta" data-verbaly-rich data-verbaly-links='{"docs":"/es/docs"}'></p>
```

- A link is a `string` href or `{ href, target, rel }`; the per-element `data-verbaly-links` map merges over the global `richLinks`.
- Hrefs come from **your code, never from the catalog**, and unsafe schemes (`javascript:`, `data:`) are blocked by `safeHref`: the `<a>` renders without `href`.
- On a page `verbaly render` wrote, the map travels with the page. It already carries each href with that language’s prefix, so those anchors need no `richLinks` here, and a click keeps the reader in their language.
- Names missing from the map unwrap to inert text, like any unknown tag, so translations never break the page.

## Picking the language at startup

Two helpers cover what every app repeats, picking the initial language and remembering the user's choice:

```ts title="main.ts"
import { bindDom, createVerbaly, persistLocale, resolveLocale } from 'verbaly';

const v = createVerbaly({
  locale: resolveLocale({ supported: ['en', 'es', 'pt'] }),  // storage → navigator → fallback
  messages: { en },  // bundle only the source
  loaders: { es: () => import('./locales/es.json'), pt: () => import('./locales/pt.json') },
});  // the chosen locale's catalog is fetched for you
bindDom(v);

// on user switch:
await v.loadLocale('es');  // flash-free (setLocale alone also auto-loads)
v.setLocale('es');
persistLocale('es');  // localStorage + <html lang> + <html dir>
```

- `resolveLocale`: the address → stored choice → `navigator.languages` → `fallback` (defaults to the first supported language). Pass `path: false` when your addresses carry no language. Safe on a server. Each preference finds the closest language you support: `es-PE` → `es`, `zh-HK` → `zh-Hant` (its likely script), `pt` → `pt-BR` (its likely region) and `pt-PT` → `pt-BR` (same language and script).
- Both accept a custom `storageKey` (default `verbaly-locale`); `false` disables storage.
- Lazy catalogs: only the source ships in the bundle, and `loaders` fetch the rest on demand, once each. `es-MX` finds `es` on its own.

## Behavior

- Re-renders every bound element on `setLocale` / `addMessages`.
- A `MutationObserver` picks up nodes added later and attribute edits, so dynamic content just works.
- `bindDom` returns an `unbind()` that disconnects everything.
- Options: `bindDom(v, { root, attribute, richTags, richLinks })` to scope the scan, rename the attribute, override the allowed tags or provide named links.

> **Safe by design**
>
> Translations render via `textContent`, never `innerHTML`. Rich mode builds only the allowed elements, attributes never come from the catalog, and `on*` names are rejected, so catalog content can't inject markup or handlers.
