Integraciones
HTML plano
¿Sin framework? El HTML plano funciona igual de bien, algo que ninguna otra herramienta i18n con compilador ofrece. Marca elementos, llama a bindDom, listo.
Instalación
El runtime es todo lo que necesita esta página: sin plugin y sin compilador.
pnpm add verbalyAgrega @verbaly/compiler como dependencia de desarrollo cuando quieras el comando verbaly, para comprobar tus catálogos o escribir cada página ya traducida.
Uso
<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-rendersAtributos
| Atributo | Propósito |
|---|---|
| data-verbaly | Clave cuya traducción se vuelve el texto del elemento |
| data-verbaly-args | Params JSON compartidos por las traducciones de texto y atributos |
| data-verbaly-attr | Mapa JSON de atributo → clave, p. ej. placeholder, title, aria-label. Los atributos URL (href, src…) se comprueban contra esquemas inseguros como lee una URL el navegador, así que un tabulador o un salto de línea dentro del esquema no esconde ninguno. on*, style y srcdoc se bloquean, así que un catálogo no puede inyectar scripts |
| data-verbaly-rich | Opt-in: renderiza los tags del mensaje como elementos reales (ver Rich text) |
| data-verbaly-links | Mapa JSON de nombre de link → href para links nombrados (ver Links nombrados) |
Rich text
Por defecto las traducciones renderizan vía textContent, así que los tags quedan literales. Marca el elemento con data-verbaly-rich y los mensajes con tags se vuelven elementos reales:
{ "gate.title": "The build <em>gate</em>" }<h3 data-verbaly="gate.title" data-verbaly-rich></h3>
<!-- renders: The build <em>gate</em> -->Una clave por frase, así que el traductor ve el mensaje completo y cada idioma mantiene su propio orden de palabras. El modelo de seguridad:
- Solo renderiza una lista corta de tags en línea:
em,strong,code,b,i,u,s,small,mark,sub,sup,span,kbd,abbr,br,wbr. Los dos últimos no llevan contenido, así que<br>,<br/>y<br />son todos un salto de línea. - Los elementos se construyen programáticamente, nunca
innerHTML, y los atributos jamás vienen del mensaje. - Cualquier otro tag se desenvuelve a texto inerte: un
<script>en un catálogo renderiza como texto plano, sin elemento. - Sobrescribe esa lista con
bindDom(v, { richTags: ['q'] }). - Las entidades HTML se decodifican como texto plano: tanto las nombradas
</>/&como las numéricas. Escribe{para mostrar una{literal sin tocar la sintaxis de placeholders.
Links nombrados
Los links quedan fuera de esa lista a propósito: un <a> sin atributos no sirve, y los atributos nunca salen de los mensajes. En su lugar nombras el link en el mensaje y provees el href desde el código:
{ "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>- Un link es un href
stringo{ href, target, rel }; el mapa por elementodata-verbaly-linksse mergea sobre elrichLinksglobal. - Los hrefs vienen de tu código, nunca del catálogo, y los esquemas inseguros (
javascript:,data:) los bloqueasafeHref: el<a>se renderiza sinhref. - En una página que escribió
verbaly render, el mapa viaja con la página. Ya lleva cada href con el prefijo de ese idioma, así que esos enlaces no necesitanrichLinksaquí, y un clic mantiene al lector en su idioma. - Los nombres que no están en el mapa se desenvuelven a texto inerte, como cualquier tag desconocido, así que las traducciones nunca rompen la página.
Elegir el idioma al arrancar
Dos helpers cubren lo que toda app repite, elegir el idioma inicial y recordar la elección del usuario:
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: la dirección → elección guardada →navigator.languages→fallback(por defecto, el primer idioma soportado). Pasapath: falsesi tus direcciones no llevan idioma. Seguro en el servidor. Cada preferencia encuentra el idioma soportado más cercano:es-PE→es,zh-HK→zh-Hant(su escritura probable),pt→pt-BR(su región probable) ypt-PT→pt-BR(mismo idioma y escritura).- Ambos aceptan un
storageKeycustom (defaultverbaly-locale);falsedesactiva el storage. - Catálogos lazy: solo la fuente va en el bundle, y los
loaderstraen el resto bajo demanda, una sola vez cada uno.es-MXencuentraespor sí solo.
Comportamiento
- Re-renderiza cada elemento bindeado en
setLocale/addMessages. - Un
MutationObserverdetecta nodos agregados después y ediciones de atributos, así que el contenido dinámico simplemente funciona. bindDomdevuelve ununbind()que desconecta todo.- Opciones:
bindDom(v, { root, attribute, richTags, richLinks })para acotar el escaneo, renombrar el atributo, sobrescribir los tags permitidos o proveer links nombrados.