The Localization SDK enables you to access and respond to user language preferences without requiring a particular frontend framework.

​
Getting Started

​
1. Install the SDK

Install the SDK with your preferred package manager.

npm install @microapp-io/user-preferences

​
2. Import and Initialize the SDK

To use the Localization SDK in your code, import it in any file where you need to use it.

import { UserPreferences } from '@microapp-io/user-preferences';

// Production initialization
const userPreferences = new UserPreferences();

When developing locally, you can use the sandbox configuration to test different language preferences:

// Sandbox initialization with custom language preference
const userPreferences = new UserPreferences({
  sandbox: {
    lang: 'en',
  },
});

The sandbox prop should only be used for local development. Do not use it in production.

​
3. Getting User Language Preference

You can use the getPreferences() method to retrieve the user’s language preference:

const { lang } = userPreferences.getPreferences();
console.log(`User language: ${lang}`);

​
4. Listen to Language Preference Updates

The SDK provides a way to listen to updates to the user’s language preference with the onUpdate() method:

userPreferences.onUpdate((newPreferences) => {
  const { lang } = newPreferences;
  console.log(`Language updated: ${lang}`);
  
  // Update your application based on the new language
  updateAppLanguage(lang);
});

​
5. Create Translation Files

Store translations in separate files outside of your application logic.

// translations.ts
export const translations = {
  'en': {
    title: 'Welcome',
    button: 'Get Started',
    loading: 'Loading...'
  },
  'es': {
    title: 'Bienvenido',
    button: 'Comenzar',
    loading: 'Cargando...'
  },
  'pt': {
    title: 'Bem-vindo',
    button: 'Começar',
    loading: 'Carregando...'
  }
};

​
6. Render Localized Content

Display content based on the user’s language preference.

import { translations } from './translations';
import { UserPreferences } from '@microapp-io/user-preferences';

// Initialize the SDK
const userPreferences = new UserPreferences();

// Get the user's language preference
const { lang } = userPreferences.getPreferences();

// Default to English if language not supported
const t = translations[lang] || translations['en'];

// Render content
document.getElementById('title').textContent = t.title;
document.getElementById('start-button').textContent = t.button;

// Update content when language changes
userPreferences.onUpdate((newPreferences) => {
  const newLang = newPreferences.lang;
  const newT = translations[newLang] || translations['en'];
  
  document.getElementById('title').textContent = newT.title;
  document.getElementById('start-button').textContent = newT.button;
});

​
7. Localize API Requests (Optional)

If you are making API requests, you can pass the user’s language preference in the headers.

import { UserPreferences } from '@microapp-io/user-preferences';

// Initialize the SDK
const userPreferences = new UserPreferences();

// Get the user's language preference
const { lang } = userPreferences.getPreferences();

// Fetch data with language preference
async function fetchLocalizedData() {
  try {
    const response = await fetch('https://api.example.com/content', {
      headers: {
        // Include the user's language preference in the request headers
        'Accept-Language': lang
      }
    });
    
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error fetching localized data:', error);
  }
}

// Use the localized data
fetchLocalizedData().then(data => {
  // ...
});