Documentation

Everything you need to integrate Verba into your application.

Installation

Install the SDK with your favorite package manager.

Terminal

npm install @verbadev/js

Quick Start

Initialize Verba and start translating in three lines of code.

app.ts

import { Verba } from '@verbadev/js'

const verba = new Verba({
  projectId: 'your-project-id',
  publicKey: 'pk_your-public-key',
  // locale auto-detected from browser
})

// Get a translation
const text = verba.t('welcome.message')

Auto-Create Missing Keys

Pass a default value to automatically create missing keys with AI translations.

app.ts

// If 'greeting' doesn't exist, it returns 'Hello!' immediately
// and creates the key with AI translations in the background
const text = verba.t('greeting', 'Hello!')

This enables a code-first workflow: write your translations inline, and Verba creates them automatically with AI-powered translations to all your configured locales.

Interpolation

Use { placeholders } in your translations and pass values to replace them.

app.ts

// With params only
verba.t('greeting', { name: 'Łukasz' })
// 'Hello, {name}!' → 'Hello, Łukasz!'

// With default value and params
verba.t('welcome', 'Welcome, {name}!', { name: 'Łukasz' })

API Reference

Complete API documentation for the Verba SDK.

new Verba({ projectId, publicKey, locale? })

Create a new Verba instance. Translations are fetched automatically on initialization.

projectId Your project ID from the dashboard

publicKey Your public key (safe for client-side)

locale Initial locale (optional, auto-detects from browser by default)

t(key, defaultValue?, params?)

Get a translation with optional interpolation. Supports flexible arguments:

t('key') - just the key

t('key', 'Hello!') - with fallback (auto-creates missing keys)

t('key', { name: 'World' }) - with interpolation params

t('key', 'Hi {name}!', { name: 'World' }) - both

verba.setLocale(locale)

Change the active locale. All subsequent t() calls will return translations for the new locale.

verba.getLocale()

Returns the current active locale.

verba.getLocales()

Returns an array of all available locales for the project.

verba.getDefaultLocale()

Returns the project's default locale.

await verba.ready()

Returns a promise that resolves when translations are loaded. Useful if you need to ensure translations are available before rendering.

Framework Guides

Integration examples for popular frameworks.

Next.js

lib/verba.ts

import { Verba } from '@verbadev/js'

export const verba = new Verba({
  projectId: 'your-project-id',
  publicKey: 'pk_your-public-key',
})

// In your component:
// import { verba } from '@/lib/verba'
// const text = verba.t('welcome.message', 'Welcome!')

Vue

App.vue

<script setup>
import { Verba } from '@verbadev/js'
import { ref, onMounted } from 'vue'

const verba = new Verba({
  projectId: 'your-project-id',
  publicKey: 'pk_your-public-key',
})

const ready = ref(false)

onMounted(async () => {
  await verba.ready()
  ready.value = true
})

const t = (key, defaultValue) => verba.t(key, defaultValue)
</script>

<template>
  <h1 v-if="ready">{{ t('welcome.title', 'Welcome!') }}</h1>
</template>

Svelte

App.svelte

<script>
  import { Verba } from '@verbadev/js'
  import { onMount } from 'svelte'

  const verba = new Verba({
    projectId: 'your-project-id',
    publicKey: 'pk_your-public-key',
  })

  let ready = false

  onMount(async () => {
    await verba.ready()
    ready = true
  })

  const t = (key, defaultValue) => verba.t(key, defaultValue)
</script>

{#if ready}
  <h1>{t('welcome.title', 'Welcome!')}</h1>
{/if}