> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microapp.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CodeGroup>
  ```bash npm theme={null}
  npm install @microapp-io/user-preferences
  ```

  ```bash yarn theme={null}
  yarn add @microapp-io/user-preferences
  ```

  ```bash pnpm theme={null}
  pnpm add @microapp-io/user-preferences
  ```
</CodeGroup>

### 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.

```typescript theme={null}
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:

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

<Warning>
  The `sandbox` prop should only be used for local development. Do not use it in production.
</Warning>

### 3. Getting User Language Preference

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

```typescript theme={null}
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:

```typescript theme={null}
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.

```typescript theme={null}
// 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.

```typescript theme={null}
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.

```typescript theme={null}
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 => {
  // ...
});
```