@verbadev/react-native

Official React Native SDK for Verba - Translation Management System.

Installation

npm install @verbadev/react-native @verbadev/react @verbadev/js

For best locale detection, also install one of:

# Expo projects
npx expo install expo-localization

# Bare React Native projects
npm install react-native-localize

Quick Start

import { VerbaProvider, useVerba } from '@verbadev/react-native'
import { View, Text } from 'react-native'

export default function App() {
  return (
    <VerbaProvider
      projectId="your-project-id"
      publicKey="pk_your-public-key"
    >
      <MyScreen />
    </VerbaProvider>
  )
}

function MyScreen() {
  const { t, isReady } = useVerba()

  // Locale is auto-detected from device settings
  return (
    <View>
      <Text>{t('welcome.message', 'Welcome!')}</Text>
    </View>
  )
}

Configuration

<VerbaProvider>

Wrap your app with VerbaProvider to provide translation context to all child components.

<VerbaProvider
  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 device
  baseUrl={string}      // Optional - API base URL (default: 'https://verba.dev')
>
  {children}
</VerbaProvider>

Locale Auto-Detection

Unlike the browser-based JS SDK, this SDK automatically detects the user's locale from native device settings using the following detection chain:

1. expo-localization → getLocales()[0].languageTag (Expo projects)
2. react-native-localize → getLocales()[0].languageTag (bare RN projects)
3. React Native NativeModules → iOS AppleLanguages / Android I18nManager.localeIdentifier
4. Fallback → 'en'

The detected locale is matched against your project's available locales:

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

You can also override detection with an explicit locale:

<VerbaProvider projectId={projectId} publicKey={publicKey} locale="es">

API Reference

useVerba()

Access translations and locale management from any component inside VerbaProvider.

const { t, locale, setLocale, locales, defaultLocale, isReady } = useVerba()

Returns:

| Property | Type | Description | |---|---|---| | t | (key, defaultValue?, params?) => string | Get a translated string | | locale | string | Current active locale | | setLocale | (locale: string) => void | Change locale (triggers re-render) | | locales | string[] | All available locales | | defaultLocale | string \| null | Project's default locale | | isReady | boolean | Whether translations have loaded |

t(key, defaultValue?, params?)

Get a translation for the current locale with optional interpolation.

function MyScreen() {
  const { t } = useVerba()

  return (
    <View>
      {/* Basic usage */}
      <Text>{t('welcome.message')}</Text>

      {/* With default value (auto-creates missing keys) */}
      <Text>{t('greeting', 'Hello!')}</Text>

      {/* With interpolation params */}
      <Text>{t('greeting', { name: 'Łukasz' })}</Text>
      {/* 'Hello, {name}!' → 'Hello, Łukasz!' */}

      {/* With both default value and params */}
      <Text>{t('greeting', 'Hello, {name}!', { name: 'Łukasz' })}</Text>
    </View>
  )
}

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

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.

setLocale(locale)

Change the active locale. Triggers a re-render of all components using useVerba().

function LocaleSwitcher() {
  const { locale, setLocale, locales } = useVerba()

  return (
    <View>
      {locales.map((l) => (
        <TouchableOpacity key={l} onPress={() => setLocale(l)}>
          <Text style={{ fontWeight: l === locale ? 'bold' : 'normal' }}>{l}</Text>
        </TouchableOpacity>
      ))}
    </View>
  )
}

detectNativeLocale()

The native locale detection function is also exported if you need it directly.

import { detectNativeLocale } from '@verbadev/react-native'

const deviceLocale = detectNativeLocale() // e.g., 'en-US'

How It Works

1. Initialization: VerbaProvider creates a Verba instance with native locale detection and immediately fetches all translations from the API.

2. Native Detection: The device locale is detected using available native libraries (expo-localization, react-native-localize, or NativeModules), unlike the browser SDK which uses navigator.language.

3. Reactivity: When translations load (isReady flips to true) or the locale changes, all components using useVerba() automatically re-render.

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

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

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

Framework Examples

Expo

// App.tsx
import { VerbaProvider } from '@verbadev/react-native'
import { NavigationContainer } from '@react-navigation/native'
import { HomeScreen } from './screens/HomeScreen'

export default function App() {
  return (
    <VerbaProvider
      projectId="your-project-id"
      publicKey="pk_your-public-key"
    >
      <NavigationContainer>
        <HomeScreen />
      </NavigationContainer>
    </VerbaProvider>
  )
}

// screens/HomeScreen.tsx
import { useVerba } from '@verbadev/react-native'
import { View, Text } from 'react-native'

export function HomeScreen() {
  const { t, isReady } = useVerba()

  if (!isReady) return <Text>Loading...</Text>

  return (
    <View>
      <Text>{t('home.title', 'Welcome!')}</Text>
      <Text>{t('home.subtitle', 'Start exploring')}</Text>
    </View>
  )
}

Bare React Native

// index.js
import { AppRegistry } from 'react-native'
import { VerbaProvider } from '@verbadev/react-native'
import App from './App'

function Root() {
  return (
    <VerbaProvider
      projectId="your-project-id"
      publicKey="pk_your-public-key"
    >
      <App />
    </VerbaProvider>
  )
}

AppRegistry.registerComponent('MyApp', () => Root)

Locale Switcher Component

import { useVerba } from '@verbadev/react-native'
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native'

const LOCALE_NAMES: Record<string, string> = {
  en: 'English',
  es: 'Español',
  fr: 'Français',
  de: 'Deutsch',
}

export function LocaleSwitcher() {
  const { locale, setLocale, locales } = useVerba()

  return (
    <View style={styles.container}>
      {locales.map((l) => (
        <TouchableOpacity
          key={l}
          onPress={() => setLocale(l)}
          style={[styles.button, l === locale && styles.active]}
        >
          <Text style={l === locale ? styles.activeText : styles.text}>
            {LOCALE_NAMES[l] || l}
          </Text>
        </TouchableOpacity>
      ))}
    </View>
  )
}

const styles = StyleSheet.create({
  container: { flexDirection: 'row', gap: 8 },
  button: { paddingHorizontal: 12, paddingVertical: 6, borderRadius: 16, backgroundColor: '#f3f4f6' },
  active: { backgroundColor: '#111827' },
  text: { color: '#6b7280', fontSize: 14 },
  activeText: { color: '#ffffff', fontSize: 14 },
})

TypeScript

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

import { VerbaProvider, useVerba, VerbaContextValue, detectNativeLocale } from '@verbadev/react-native'

Exported types:

• VerbaProviderProps - Props for the VerbaProvider component
• VerbaContextValue - Return type of useVerba() hook

Peer Dependencies

• react >= 18
• react-native >= 0.70
• @verbadev/js >= 0.2.0
• @verbadev/react >= 0.1.0

Optional (for locale detection):

• expo-localization (Expo projects)
• react-native-localize (bare RN projects)

License

MIT