Saltar al contenido

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.

  • Node 22.12+ · Vite 7/8
  • TypeScript-first
  • ~3 KB0 dependencias

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.

  1. 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/vite
     pnpm add -D @verbaly/compiler

    El runtime es siempre el mismo; el plugin depende de tu setup. En webpack, Rollup, esbuild o Rspack instalas @verbaly/unplugin en su lugar, y Next.js, Nuxt y Astro tienen el suyo. Ver Paquetes.

  2. Genera todo con un comando

    npx verbaly init escribe 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 --source y aquellos a los que traduces con --locales. Nunca sobrescribe nada. Cablear el plugin te toca a ti, y es el paso siguiente.

    npx verbaly init --source es --locales pt   # config + locales/es.json + locales/pt.json
  3. Agrega el plugin

    vite.config.ts
    import verbaly from '@verbaly/vite';
    
    export default {
      plugins: [verbaly()],
    };

    Tus opciones viven en el verbaly.config que escribió init, donde las leen el build y verbaly check:

    verbaly.config.ts
    import type { VerbalyConfig } from '@verbaly/compiler';
    
    export default {
      sourceLocale: 'es',
      locales: ['pt'],
    } satisfies VerbalyConfig;

    sourceLocale es el idioma en el que escribes y locales, 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 corre npx verbaly extract. Si dejas fuera locales, cada catálogo JSON de locales/ cuenta como idioma, incluso un archivo vacío que acabas de crear.

  4. Escribe texto, no claves

    src/main.ts
    import { 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 again

    En 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.

  5. Traduce y verifica

    extract llena tus catálogos: tu idioma fuente queda listo y cada uno de los demás espera con un texto vacío. Por eso check falla aquí, y te dice qué falta.

    npx verbaly extract   # sync catalogs + types
    npx verbaly check     # exit 1 if anything is missing

    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 check pasa. Corre npx vite y la página dice Olá Ana, você tem 3 mensagens. npx verbaly translate puede llenar un catálogo por ti, como borradores que revisa una persona.

Qué exporta el módulo del proyecto

ExportDescripción
tTraduce: 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
verbalyLa instancia subyacente (uso avanzado)
↑↓para moverteEnterpara abrir
Copiado en el portapapeles