Skip to main content

React SDK — Getting Started

The @multilocale/react package provides React hooks and components to load and display translations in your app.

Installation​

npm install @multilocale/react

Setup​

1. Initialize Multilocale​

Call init() at your app's entry point with your organizationId and project name. You can find these in the Multilocale dashboard.

import { init } from '@multilocale/react'

init({
  organizationId: 'your-organization-id',
  project: 'your-project-name',
  defaultLanguage: 'en', // optional, falls back to browser language
})

2. Add the MultilocaleProvider​

Wrap your app with MultilocaleProvider. This sets up TanStack React Query for data fetching and caching.

import MultilocaleProvider from '@multilocale/react/MultilocaleProvider'

function App() {
  return (
    <MultilocaleProvider>
      <YourApp />
    </MultilocaleProvider>
  )
}

3. Use Translations​

Use the useTranslation hook in your components to access translated strings.

import { useTranslation } from '@multilocale/react'

function WelcomeBanner() {
  const { t, language } = useTranslation()

  return (
    <div>
      <h1>{t('welcome_message')}</h1>
      <p>{t('current_language')}: {language}</p>
    </div>
  )
}

Server-Side Rendering​

For SSR, use the Cache component returned by useTranslation to hydrate translations on the client:

function Page() {
  const { t, Cache } = useTranslation()

  return (
    <html>
      <head>
        <Cache />
      </head>
      <body>
        <h1>{t('page_title')}</h1>
      </body>
    </html>
  )
}

The Cache component injects a <script> tag that sets window.__MULTILOCALE_CACHE__ with the current dictionaries, preventing a re-fetch on the client.

Pre-loading Dictionaries​

You can pass dictionaries directly to init() to skip the network request:

import { init } from '@multilocale/react'

init({
  organizationId: 'your-organization-id',
  project: 'your-project-name',
  dictionaries: {
    en: {
      welcome_message: 'Welcome!',
      goodbye: 'Goodbye!',
    },
    es: {
      welcome_message: 'Bienvenido!',
      goodbye: 'Adiós!',
    },
  },
})