Internationalization

Configure multi-language support with built-in English, Russian and Chinese translations for all embarkAI UI components.

embarkAI ships with en, ru and zh translations out of the box. You can use the built-in translations as-is, extend them with custom keys or extra locales, or fully replace them.

Import


import {
  combineI18NResources,
  getAvailableLanguages,
  getLanguageIcon,
  PASSPORT_TRANSLATIONS,
  LOCAL_STORAGE_I18N_KEY,
  LangToggle,
} from '@embarkai/ui-kit'

Quick Setup

The simplest integration is to add the LangToggle component, which renders a language selector dropdown. It works out of the box with no additional configuration:


import { Provider, LangToggle } from '@embarkai/ui-kit'
 
function App() {
  return (
    <Provider projectId="your-project-id">
      <header>
        <LangToggle />
      </header>
    </Provider>
  )
}

The selected language is automatically persisted to localStorage under the LOCAL_STORAGE_I18N_KEY key.

combineI18NResources

Merges the built-in passport translations with your custom translation keys. Pass the result to the Provider’s translations config:


import { Provider, combineI18NResources } from '@embarkai/ui-kit'
 
const customTranslations = {
  en: {
    myApp: {
      welcome: 'Welcome to My App',
      dashboard: 'Dashboard',
    },
  },
  ru: {
    myApp: {
      welcome: 'Добро пожаловать',
      dashboard: 'Панель',
    },
  },
}
 
const resources = combineI18NResources(customTranslations)
 
function App() {
  return (
    <Provider
      projectId="your-project-id"
      initialConfig={{
        translations: resources,
      }}
    >
      <main>Your app</main>
    </Provider>
  )
}

When called without arguments, combineI18NResources() returns the default passport translations unchanged.

getAvailableLanguages

Returns the language codes present in a translation resources object. Pass the built-in PASSPORT_TRANSLATIONS or your combined resources:


import { getAvailableLanguages, PASSPORT_TRANSLATIONS } from '@embarkai/ui-kit'
 
const languages = getAvailableLanguages(PASSPORT_TRANSLATIONS)
// ['en', 'zh', 'ru']

getLanguageIcon

Returns an emoji flag for a given language code, or null for unknown codes:


import { getAvailableLanguages, getLanguageIcon, PASSPORT_TRANSLATIONS } from '@embarkai/ui-kit'
 
function LanguageList() {
  const languages = getAvailableLanguages(PASSPORT_TRANSLATIONS)
 
  return (
    <ul>
      {languages.map((code) => (
        <li key={code}>
          {getLanguageIcon(code) ?? ''} {code}
        </li>
      ))}
    </ul>
  )
}

PASSPORT_TRANSLATIONS

The raw translation object used internally. Useful if you need to inspect available keys or build a fully custom language selector:


import { PASSPORT_TRANSLATIONS } from '@embarkai/ui-kit'
 
// Access English translations
const en = PASSPORT_TRANSLATIONS.en

LOCAL_STORAGE_I18N_KEY

The localStorage key where the user’s language preference is stored. Use this to read or pre-set the language before the Provider mounts:


import { LOCAL_STORAGE_I18N_KEY } from '@embarkai/ui-kit'
 
// Read the stored language preference
const savedLang = localStorage.getItem(LOCAL_STORAGE_I18N_KEY)
 
// Pre-set a language
localStorage.setItem(LOCAL_STORAGE_I18N_KEY, 'fr')

Custom Language Selector

Build a custom language picker using the utility functions:


import {
  getAvailableLanguages,
  getLanguageIcon,
  LOCAL_STORAGE_I18N_KEY,
  PASSPORT_TRANSLATIONS,
} from '@embarkai/ui-kit'
 
function CustomLangPicker() {
  const languages = getAvailableLanguages(PASSPORT_TRANSLATIONS)
 
  const handleChange = (code: string) => {
    localStorage.setItem(LOCAL_STORAGE_I18N_KEY, code)
    window.location.reload()
  }
 
  return (
    <select onChange={(e) => handleChange(e.target.value)}>
      {languages.map((code) => (
        <option key={code} value={code}>
          {getLanguageIcon(code) ?? ''} {code.toUpperCase()}
        </option>
      ))}
    </select>
  )
}

Next Steps

Theming — customize visual appearance alongside language
Components — all components support the configured language
Provider Setup — pass translations via initialConfig