TypeScript SDK

Microapp Localization for Any Web App

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

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 => {
  // ...
});