Inicio
Primeros pasos
Verbaly invierte el flujo i18n habitual: escribes texto natural en tu código y el compilador extrae los mensajes, genera claves estables, tipos y bundles por idioma. Requisitos: Node 22.12+ y Vite 7 u 8.
Estos pasos son para un proyecto de Vite en TypeScript plano, la forma más corta de verlo funcionar. En otro montaje la idea es la misma, y su página tiene las líneas exactas: React y Next.js, Vue y Nuxt, Svelte y SvelteKit, Astro o HTML plano.
Instalación
Agrega el runtime y el plugin de Vite, y después el compilador, que es donde vive el comando
verbaly. Elige tu gestor de paquetes.pnpm add verbaly @verbaly/vitepnpm add -D @verbaly/compilerEl runtime es siempre el mismo; el plugin depende de tu setup. En webpack, Rollup, esbuild o Rspack instalas
@verbaly/unpluginen su lugar, y Next.js, Nuxt y Astro tienen el suyo. Ver Paquetes.Genera todo con un comando
npx verbaly initescribe la config y un catálogo por idioma, y te dice qué paquetes necesita tu proyecto: el plugin y, con Vite u otro bundler, el de React, Vue o Svelte si tu app usa uno. Indícale el idioma en el que escribes con--sourcey aquellos a los que traduces con--locales. Nunca sobrescribe nada. Cablear el plugin te toca a ti, y es el paso siguiente.Agrega el plugin
vite.config.tsimport verbaly from '@verbaly/vite'; export default { plugins: [verbaly()], };Tus opciones viven en el
verbaly.configque escribióinit, donde las leen el build yverbaly check:verbaly.config.tsimport type { VerbalyConfig } from '@verbaly/compiler'; export default { sourceLocale: 'es', locales: ['pt'], } satisfies VerbalyConfig;sourceLocalees el idioma en el que escribes ylocales, aquellos a los que traduces. Esa lista es la lista entera, así que un archivo que te dejaste olvidado se ignora. Para sumar un idioma después, agrégalo ahí y correnpx verbaly extract. Si dejas fueralocales, cada catálogo JSON delocales/cuenta como idioma, incluso un archivo vacío que acabas de crear.Escribe texto, no claves
src/main.tsimport { t, setLocale } from 'verbaly/app'; const name = 'Ana'; const count = 3; const app = document.querySelector('#app')!; const paint = () => { app.textContent = t`Hola ${name}, tienes ${count} mensajes`; }; paint(); setLocale('pt').then(paint); // loads its catalog, then paints againEn dev, el plugin extrae los mensajes en vivo: tu catálogo fuente se llena solo, los demás idiomas reciben placeholders
"", y los tipos generados mantienen claves y params tipados.Traduce y verifica
extractllena tus catálogos: tu idioma fuente queda listo y cada uno de los demás espera con un texto vacío. Por esocheckfalla aquí, y te dice qué falta.Escribe la traducción en
locales/pt.json. La clave es la que escribióextract, y los huecos como{name}se quedan tal cual:locales/pt.json{ "oHfbnDd4": "Olá {name}, você tem {count} mensagens" }Ahora
npx verbaly checkpasa. Correnpx vitey la página dice Olá Ana, você tem 3 mensagens.npx verbaly translatepuede llenar un catálogo por ti, como borradores que revisa una persona.
Qué exporta el módulo del proyecto
| Export | Descripción |
|---|---|
| t | Traduce: t('key', params) o el tagged t`...` |
| setLocale(locale) | Carga ese idioma y luego cambia. Devuelve una promesa, así que puedes esperarla |
| getLocale() | Idioma actual |
| subscribe(fn) | Re-ejecuta la UI en cambios de idioma/mensajes; devuelve unsubscribe |
| verbaly | La instancia subyacente (uso avanzado) |