Integraciones
Svelte
El paquete oficial de Svelte 5 para Verbaly. Stores idiomáticos sobre el mismo core reactivo, factories de stores para uso a nivel app, y un componente <Trans> para rich text.
Qué puedes lograr:
- Traduce con stores:
$tre-renderiza en cada cambio de idioma, sin cableado - Enlaza un switcher de idioma en una línea:
bind:valuesobre el store del idioma simplemente funciona - Usa contexto o factories de stores, con o sin árbol de componentes
- Mapea un tag de un mensaje a tu propio componente con el prop components de <Trans>
Instalación
Agrega el runtime, este paquete y el plugin de Vite, y después el compilador, que es donde vive el comando verbaly. init escribe tu config y tu catálogo fuente.
pnpm add verbaly @verbaly/svelte @verbaly/vite pnpm add -D @verbaly/compilerDespués agrega verbaly() a los plugins de vite.config. Escribe verbaly/app, el módulo que leen tus componentes.
Setup y stores
<script>
// root component / layout:
import { provideVerbaly } from '@verbaly/svelte';
import { verbaly } from 'verbaly/app';
provideVerbaly(verbaly);
</script>
<script>
// any child component:
import { useT, useLocale } from '@verbaly/svelte';
const t = useT();
const locale = useLocale(); // writable store
const count = 3;
</script>
<p>{$t`You have ${count} messages`}</p>
<select bind:value={$locale}>…</select>- Stores idiomáticos:
$tre-renderiza en cada cambio de idioma;bind:value={$locale}en un select funciona directo. - ¿Sin árbol de componentes?
tStore(instance)/localeStore(instance)construyen los mismos stores sin context, compartidos por toda la app. - ¿Sin
provideVerbalyencima de un componente, en el navegador?useT()lee la instancia que creaverbaly/app, y el plugin del bundler carga ese módulo en cada componente que importa@verbaly/svelte, así que una app de una sola página o un test de componente no necesitan envoltorio. En el servidor un padre tiene que proveerla, porque cada petición tiene su propia instancia.
El idioma que elige un visitante
Asignar $locale cambia todos los componentes, y la página lo sigue: <html lang>, <html dir> y la elección, guardada en el navegador. Una app de una sola página arranca en su idioma fuente, así que recupera esa elección antes de montar:
// the saved choice, else the browser's, loaded before anything renders
import { mount } from 'svelte';
import { resolveLocale } from 'verbaly';
import { locales, setLocale } from 'verbaly/app';
import App from './App.svelte';
setLocale(resolveLocale({ supported: locales, path: false })).then(() =>
mount(App, { target: document.getElementById('app')! }),
);Donde un servidor renderiza la página, como en SvelteKit, cambia de idioma con switchLocale de verbaly/app: además escribe la cookie que lee el servidor.
Escribe el texto en su lugar
El compilador también lee tus archivos .svelte: escribe el texto fuente con el tag del store, en una expresión del markup o en el script, y se extrae, recibe su clave y sus tipos al guardar. El texto que solo se muestra nunca se extrae, así que una página puede enseñar t`…` como ejemplo sin riesgo. Sin inventar claves, sin tocar catálogos.
<h1>{$t`Hola ${name}, tienes ${count} mensajes`}</h1>
<!-- extracted on save; the build rewrites it to: -->
<h1>{$t('oHfbnDd4', { name, count })}</h1>¿Prefieres claves legibles? $t.id('inbox.title') antes del template extrae bajo tu id en vez de un hash del contenido.
¿Prefieres dejar el texto en tu catálogo? Escribe solo su clave: se comprueba y se tipa igual. Mira Claves y catálogos.
Rich text con <Trans>
Svelte tiene su propio componente: impórtalo del subpath Trans.svelte (componente crudo, lo compila tu bundler):
<script>
import Trans from '@verbaly/svelte/Trans.svelte';
import DocsLink from './DocsLink.svelte';
</script>
<Trans id='home.title' />
<Trans id='greet' values={{ name: 'Aron' }} />
<!-- message: 'Read the <docs>guide</docs>' → your component wraps the tag content -->
<Trans id='cta' components={{ docs: DocsLink }} />- Los tags del mensaje (
The <em>build</em> gate) se renderizan como elementos reales con la misma lista de tags permitidos dedata-verbaly-rich. Los tags desconocidos se desenvuelven a texto inerte,richTagsla sobreescribe. - Usa la instancia de
provideVerbaly; pasainstance={verbaly}explícito cuando no hay contexto. Se re-renderiza en cada cambio de idioma. - Links nombrados: el prop
linksrenderiza tags nombrados como elementos<a>reales, con hrefs desde tu código, nunca desde los mensajes;javascript:bloqueado. - Tus propios componentes: el prop
componentsmapea un tag a un componente Svelte que recibe el contenido del tag como children, y gana sobre links y tags permitidos.
SvelteKit
Las páginas renderizadas en el servidor llegan ya traducidas al idioma del visitante, y el navegador sigue con el mismo idioma y el mismo catálogo, sin flash de texto sin traducir ni diferencias entre servidor y navegador.
- Cada página se renderiza en el idioma del visitante, tomado de la dirección cuando la lleva, y si no de su elección guardada o del header
Accept-Language - Sin flash de texto sin traducir: el HTML que envía el servidor y la página ya hidratada son idénticos, catálogo incluido
- Cada petición tiene su propia instancia, así que dos visitantes simultáneos nunca ven el idioma del otro
- Un switcher de idioma en una llamada:
switchLocalecarga el catálogo y persiste la elección para el próximo render del servidor
SvelteKit necesita el paquete de servidor (@verbaly/sveltekit) junto al paquete de Svelte, el plugin de Vite y el compilador:
pnpm add verbaly @verbaly/sveltekit @verbaly/svelte @verbaly/vite pnpm add -D @verbaly/compilerinit escribe verbaly.config.ts y tu catálogo fuente. Lista ahí tus idiomas (locales: ['en', 'es']): el build, verbaly extract y verbaly check los leen.
Conéctalo
Tres cables en el servidor, uno en el cliente. Primero el plugin de Vite y el placeholder de lang:
// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import verbaly from '@verbaly/vite';
export default { plugins: [verbaly(), sveltekit()] };
<!-- src/app.html -->
<html lang="%verbaly.lang%" dir="%verbaly.dir%">El hook de servidor resuelve el idioma por petición y rellena el placeholder. Pasa routing y decide la dirección cuando lleva el idioma, cayendo a la elección guardada, luego a Accept-Language, luego a tu fallback:
// src/hooks.server.ts
import { verbalyHandle } from '@verbaly/sveltekit';
import { locales, routing } from 'verbaly/app';
export const handle = verbalyHandle({ locales, routing });
// src/app.d.ts
declare namespace App {
interface Locals { verbalyLocale: string }
}Pásale el idioma al cliente y construye una instancia por render con el catálogo esperado, la garantía sin flash:
// +layout.server.ts
export const load = ({ locals }) => ({ locale: locals.verbalyLocale });
// +layout.ts
import { createRequestInstance } from 'verbaly/app';
export const load = async ({ data }) => ({
...data,
verbaly: await createRequestInstance(data.locale), // catalog ready BEFORE render
});
<!-- +layout.svelte -->
<script>
import { provideVerbaly } from '@verbaly/svelte';
let { data, children } = $props();
provideVerbaly(data.verbaly);
</script>
{@render children()}De aquí en adelante es @verbaly/svelte normal: los stores useT() / useLocale() y Trans.svelte funcionan sin cambios en cada componente.
$t está tipado por tu catálogo: los tipos van a src/verbaly.d.ts, la carpeta que lee el tsconfig de SvelteKit, así que svelte-check los ve sin configurar nada y falla con una clave que ningún catálogo tiene.
Un solo árbol de rutas para todos los idiomas
Si tus páginas viven en /es/docs, no necesitas una carpeta de rutas por idioma. Un solo hook universal hace que /es/docs se renderice por tu ruta /docs, así que tus rutas se quedan tal cual estaban:
import { verbalyReroute } from '@verbaly/sveltekit';
import { locales } from 'verbaly/app';
export const reroute = verbalyReroute({ locales });Va en hooks.ts y no en hooks.server.ts, porque moverse entre páginas en el navegador tiene que resolverse igual que lo hizo el servidor.
Cambiar de idioma
switchLocale de verbaly/app ya conoce tus idiomas y tu modo de URL. Pásale la instancia con la que se pinta esta página: con el idioma en la URL va a la misma página en el otro idioma, y sin él carga el catálogo y cambia la página en su sitio. En los dos casos escribe la cookie que lee el hook del servidor, así que la siguiente petición ya coincide:
<script>
import { switchLocale } from 'verbaly/app';
import { useVerbaly } from '@verbaly/svelte';
// the instance this page renders with: one per request
const verbaly = useVerbaly();
</script>
<button onclick={() => switchLocale('es', { instance: verbaly })}>Español</button>- La cookie por defecto es
verbaly-locale(la misma identidad que la clave de storage del core);cookie: falseen cualquiera de los dos lados la desactiva, paraAccept-Languagepuro. fallbackpor defecto es tu primer idioma; la negociación sigue el orden de preferencia del navegador, yes-PEcoincide cones.- Sin dependencia de SvelteKit en sí: el hook está tipado estructuralmente y se mantiene compatible con SvelteKit 2 y 3.