@verbadev/js

Official JavaScript SDK for Verba - Translation Management System.

Installation

npm install @verbadev/js

Quick Start

import { Verba } from '@verbadev/js'

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

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

Configuration

const verba = new Verba({
  projectId: string,   // Required - Your project ID from the dashboard
  publicKey: string,   // Required - Your public key (safe for client-side)
  locale?: string,     // Optional - defaults to auto-detection from browser
  baseUrl?: string,    // Optional - API base URL (default: 'https://verba.dev')
})

Locale Auto-Detection

By default, the SDK automatically detects the user's locale from the browser (navigator.language) and matches it against your project's available locales.

// Auto-detect (default behavior)
const verba = new Verba({ projectId, publicKey })

// Explicit auto-detect
const verba = new Verba({ projectId, publicKey, locale: 'auto' })

// Override with specific locale
const verba = new Verba({ projectId, publicKey, locale: 'es' })

Matching logic:

1. Exact match (e.g., en-US → en-US)
2. Base language match (e.g., en-US → en)
3. Falls back to project's default locale if no match

API Reference

verba.t(key, defaultValue?, params?)

Get a translation for the current locale with optional interpolation.

// Basic usage
verba.t('welcome.message')

// With default value (auto-creates missing keys)
verba.t('greeting', 'Hello!')

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

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

Flexible signature:

• t(key) - just the key
• t(key, defaultValue) - with fallback string
• t(key, params) - with interpolation params (object)
• t(key, defaultValue, params) - with both

Parameters:

• key (string) - The translation key
• defaultValue (string, optional) - Fallback value if key doesn't exist
• params (object, optional) - Values to interpolate into {placeholder} tokens

Returns: The translated string with interpolation applied.

Auto-creation: When you call t() with a defaultValue and the key doesn't exist, the SDK automatically:

1. Returns the defaultValue immediately
2. Creates the key in Verba in the background
3. Triggers AI translation to all your project's locales

This enables a powerful workflow where you can write code first and translations are created on-the-fly.

verba.setLocale(locale)

Change the active locale.

verba.setLocale('es')
const text = verba.t('welcome.message') // Returns Spanish translation

verba.getLocale()

Get the current locale.

const locale = verba.getLocale() // 'en'

verba.getLocales()

Get all available locales for the project.

const locales = verba.getLocales() // ['en', 'es', 'fr']

verba.getDefaultLocale()

Get the project's default locale.

const defaultLocale = verba.getDefaultLocale() // 'en'

verba.ready()

Wait for translations to be loaded. Useful if you need to ensure translations are available before rendering.

await verba.ready()
// Translations are now loaded

How It Works

1. Initialization: When you create a Verba instance, it immediately fetches all translations from the API.

2. Caching: Translations are cached in memory. The SDK uses ETags for efficient cache validation.

3. Synchronous Access: After initialization, t() calls are synchronous and instant.

4. Auto-creation: Missing keys with default values are created in the background without blocking your app.

Framework Examples

React

import { Verba } from '@verbadev/js'
import { createContext, useContext, useState, useEffect } from 'react'

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

const VerbaContext = createContext(verba)

export function VerbaProvider({ children }: { children: React.ReactNode }) {
  const [, forceUpdate] = useState(0)

  useEffect(() => {
    verba.ready().then(() => forceUpdate(1))
  }, [])

  return (
    <VerbaContext.Provider value={verba}>
      {children}
    </VerbaContext.Provider>
  )
}

export function useTranslation() {
  const verba = useContext(VerbaContext)
  return {
    t: verba.t.bind(verba),
    setLocale: (locale: string) => verba.setLocale(locale),
    locale: verba.getLocale(),
  }
}

// Usage:
// const { t } = useTranslation()
// t('greeting', 'Hello, {name}!', { name: 'World' })

Next.js (App Router)

// lib/verba.ts
import { Verba } from '@verbadev/js'

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

// components/LocaleSwitcher.tsx
'use client'
import { verba } from '@/lib/verba'

export function LocaleSwitcher() {
  return (
    <select onChange={(e) => verba.setLocale(e.target.value)}>
      {verba.getLocales().map((locale) => (
        <option key={locale} value={locale}>{locale}</option>
      ))}
    </select>
  )
}

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>
  <div v-if="ready">
    <h1>{{ t('welcome.title', 'Welcome!') }}</h1>
  </div>
</template>

TypeScript

The SDK is written in TypeScript and includes full type definitions.

import { Verba, VerbaConfig } from '@verbadev/js'

const config: VerbaConfig = {
  projectId: 'your-project-id',
  publicKey: 'pk_your-public-key',
  locale: 'en',
}

const verba = new Verba(config)

License

MIT