# @wix/multilingual

A type-safe Wix Multilingual SDK for accessing available languages on a site. This package provides a browser-only interface that proxies to the global `window.multilingual` methods with full TypeScript support.

## Installation

```bash
npm install @wix/multilingual
```

## Quick Start

```typescript
import { listSupportedLanguages } from "@wix/multilingual";

// Get all available languages
const languages = listSupportedLanguages();
console.log("Available languages:", languages);

// Find the primary language
const primaryLanguage = languages.find(lang => lang.primary);
if (primaryLanguage) {
  console.log("Primary language:", primaryLanguage.displayName);
  console.log("Primary language URL:", primaryLanguage.url);
}

// Iterate through all languages
languages.forEach(lang => {
  console.log(`${lang.displayName} (${lang.id}): ${lang.url}`);
});
```

## Features

- ✅ **Type-safe** - Full TypeScript support for all language operations
- ✅ **Browser-only** - Works in Wix applications where `window.multilingual` is available
- ✅ **Zero dependencies** - Lightweight proxy implementation
- ✅ **Silent failure** - Graceful handling of missing dependencies with console warnings
- ✅ **External site support** - Supports URLs for sites hosted outside Wix
- ✅ **Comprehensive API** - Full access to language information including URLs and regional formats

## API Reference

### `listSupportedLanguages()`

Gets an array of all available languages as defined in ML. Provides an array of all the available languages as defined in ML. Array of Language object.

**Returns:** `Language[]` - Array of Language objects, or empty array if not available

```typescript
const languages = listSupportedLanguages();
// [
//   {
//     id: "en",
//     displayName: "English",
//     regionalFormat: "en-US",
//     url: "https://mysite.com/en",
//     primary: true
//   },
//   {
//     id: "fr",
//     displayName: "Français",
//     regionalFormat: "fr-FR",
//     url: "https://mysite.com/fr",
//     primary: false
//   }
// ]
```

## Language Type

### Language

Represents a language available on the site:

```typescript
interface Language {
  /**
   * The language identifier (e.g., "en", "fr", "es").
   */
  id: string;
  /**
   * The display name of the language (e.g., "English", "Français", "Español").
   */
  displayName: string;
  /**
   * The regional format identifier (e.g., "en-US", "fr-FR", "es-ES").
   */
  regionalFormat: string;
  /**
   * The URL for the language version of the site. Supports URLs for sites hosted outside Wix.
   * (e.g., "https://mysite.com/en", "https://mysite.com/fr").
   */
  url: string;
  /**
   * Whether this is the primary language for the site.
   */
  primary: boolean;
}
```

## Examples

### Get Primary Language

```typescript
import { listSupportedLanguages } from "@wix/multilingual";

const languages = listSupportedLanguages();
const primaryLanguage = languages.find(lang => lang.primary);

if (primaryLanguage) {
  console.log(`Primary language: ${primaryLanguage.displayName}`);
  console.log(`URL: ${primaryLanguage.url}`);
}
```

### Build Language Switcher

```typescript
import { listSupportedLanguages } from "@wix/multilingual";

const languages = listSupportedLanguages();

// Create language switcher dropdown
const languageSwitcher = languages.map(lang => ({
  label: lang.displayName,
  value: lang.id,
  url: lang.url,
  isPrimary: lang.primary,
}));

// Use in your UI component
languageSwitcher.forEach(lang => {
  console.log(`${lang.label} - ${lang.url}`);
});
```

### Support External Sites

```typescript
import { listSupportedLanguages } from "@wix/multilingual";

const languages = listSupportedLanguages();

// Works with both Wix-hosted and externally-hosted sites
languages.forEach(lang => {
  // lang.url can be:
  // - "https://mysite.com/en" (external site)
  // - "https://www.wixsite.com/mysite/en" (Wix-hosted)
  console.log(`Switch to ${lang.displayName}: ${lang.url}`);
});
```