Integrations
Plain HTML
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.
pnpm add verbalyAdd @verbaly/compiler as a dev dependency when you want the verbaly command, to check your catalogs or to write each page already translated.
Usage
<h1 data-verbaly="home.title"></h1>
<p data-verbaly="inbox" data-verbaly-args='{"count":3}'></p>
<input data-verbaly-attr='{"placeholder":"search.hint"}' />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-rendersAttributes
| 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:
{ "gate.title": "The build <em>gate</em>" }<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
</>/&and numeric ones alike. Write{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:
{ "cta": "Read the <docs>guide</docs> now" }bindDom(v, {
richLinks: { docs: { href: '/docs', target: '_blank', rel: 'noopener' } },
});
// renders: Read the <a href="/docs" target="_blank" rel="noopener">guide</a> now<p data-verbaly="cta" data-verbaly-rich data-verbaly-links='{"docs":"/es/docs"}'></p>- A link is a
stringhref or{ href, target, rel }; the per-elementdata-verbaly-linksmap merges over the globalrichLinks. - Hrefs come from your code, never from the catalog, and unsafe schemes (
javascript:,data:) are blocked bysafeHref: the<a>renders withouthref. - On a page
verbaly renderwrote, the map travels with the page. It already carries each href with that language’s prefix, so those anchors need norichLinkshere, 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:
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). Passpath: falsewhen 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) andpt-PT→pt-BR(same language and script).- Both accept a custom
storageKey(defaultverbaly-locale);falsedisables storage. - Lazy catalogs: only the source ships in the bundle, and
loadersfetch the rest on demand, once each.es-MXfindseson its own.
Behavior
- Re-renders every bound element on
setLocale/addMessages. - A
MutationObserverpicks up nodes added later and attribute edits, so dynamic content just works. bindDomreturns anunbind()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.