Internationalization

Configure multi-language support with 25+ built-in translations for all EmbarkAI UI components.

EmbarkAI ships with translations for over 25 languages out of the box. You can use the built-in translations as-is, extend them with custom keys, 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',
    },
  },
  es: {
    myApp: {
      welcome: 'Bienvenido a Mi App',
      dashboard: 'Panel',
    },
  },
}
 
const resources = combineI18NResources(customTranslations)
 
function App() {
  return (
    <Provider
      projectId="your-project-id"
      initialConfig={{
        translations: resources,
      }}
    >
      {/* Your app */}
    </Provider>
  )
}

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

getAvailableLanguages

Returns an array of language codes supported by the built-in translations:


import { getAvailableLanguages } from '@embarkai/ui-kit'
 
const languages = getAvailableLanguages()
// ['en', 'es', 'fr', 'de', 'ja', 'ko', 'zh', ...]

getLanguageIcon

Returns an emoji flag for a given language code:


import { getAvailableLanguages, getLanguageIcon } from '@embarkai/ui-kit'
 
function LanguageList() {
  const languages = getAvailableLanguages()
 
  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,
} from '@embarkai/ui-kit'
 
function CustomLangPicker() {
  const languages = getAvailableLanguages()
 
  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