Documentation

🚀 Quick Start

Get started with Multilingua.js in less than 5 minutes.

1. Include the Script

Add the Multilingua widget to your HTML file:

<script src="https://multilingua.ai/multilingua-widget.js"></script>
<script>
  new Multilingua({
    mainLanguages: ['gb', 'it', 'fr', 'de', 'es']
  });
</script>
            

2. Add Translation Tags

Mark elements you want to translate with data-i18n attribute:

<h1 data-i18n="welcome-title">Welcome to our website</h1>
<p data-i18n="intro-text">This content will be translated</p>
<button data-i18n="cta-button">Get Started</button>
            

3. Test It

Open your page and click the language selector that appears in the top-right corner. Select a language and watch your content translate instantly!

💡 Note: Each unique translation costs approximately $0.001-0.002. Translations are cached automatically to minimize costs.

⚙️ Configuration

Customize the widget behavior with these options:

Option	Type	Default	Description
`apiBaseUrl`	string	`'https://multilingua.ai'`	Base URL for API calls (default: multilingua.ai)
`position`	string	`'top-right'`	Widget position: 'top-right', 'top-left', 'bottom-right', 'bottom-left'
`mainLanguages`	array	`['gb', 'it', ...]`	Array of country codes to show in main menu
`defaultLanguage`	string	`'gb'`	Default language code
`apiKey`	string	`null`	Your Multilingua API key (optional for demo)

Example with all options:

new Multilingua({
  apiBaseUrl: 'https://multilingua.ai',
  position: 'bottom-left',
  mainLanguages: ['gb', 'it', 'fr', 'de', 'es', 'pt'],
  defaultLanguage: 'gb',
  apiKey: 'your-api-key-here'
});
            

📚 API Reference

Methods

translate(lang)

Programmatically translate page to specified language code

getCurrentLanguage()

Returns the currently active language code

destroy()

Removes the widget and cleans up event listeners

Usage example:

// Create instance
const widget = new Multilingua({
  mainLanguages: ['gb', 'it', 'fr']
});

// Programmatically translate
widget.translate('it');

// Get current language
const current = widget.getCurrentLanguage();
console.log(current); // 'it'

// Clean up
widget.destroy();
            

Events

The widget triggers custom events on the document:

Event	When	Event Data
`multilingua:start`	Translation starts	{ language: 'it' }
`multilingua:complete`	Translation completes	{ language: 'it', count: 42 }
`multilingua:error`	Translation fails	{ error: 'message' }

Listen to events:

document.addEventListener('multilingua:start', (e) => {
  console.log('Translating to:', e.detail.language);
});

document.addEventListener('multilingua:complete', (e) => {
  console.log('Translated', e.detail.count, 'elements');
});
            

💡 Examples

Basic Setup

Minimal configuration for a simple website:

<!DOCTYPE html>
<html>
<head>
  <title data-i18n="page-title">My Website</title>
</head>
<body>
  <h1 data-i18n="main-title">Welcome</h1>
  <p data-i18n="intro">This is my website</p>
  
  <script src="multilingua-widget.js"></script>
  <script>
    new Multilingua();
  </script>
</body>
</html>
            

E-commerce Site

Configuration for an online store with multiple regions:

new Multilingua({
  position: 'top-right',
  mainLanguages: [
    'gb', // English
    'it', // Italian
    'de', // German
    'fr', // French
    'es', // Spanish
    'nl', // Dutch
    'pt'  // Portuguese
  ],
  defaultLanguage: 'gb'
});
            

Dynamic Content

Re-translate after adding new content dynamically:

// Create widget instance
const widget = new Multilingua({
  mainLanguages: ['gb', 'it', 'fr']
});

// Add new content dynamically
const newElement = document.createElement('p');
newElement.setAttribute('data-i18n', 'dynamic-content');
newElement.textContent = 'This was added after page load';
document.body.appendChild(newElement);

// Re-translate with current language
const currentLang = widget.getCurrentLanguage();
if (currentLang !== 'gb') {
  widget.translate(currentLang);
}
            

✨ Best Practices

Use Descriptive Keys

Use meaningful data-i18n values like "hero-title" instead of "h1" for better organization

Cache Translations

Translations are automatically cached in localStorage to minimize API calls and costs

Keep It Semantic

Write clear, natural text in your default language for better AI translation quality

Test Translations

Review translations in different languages to ensure quality and context accuracy

❓ FAQ

How much does it cost?

Each unique translation costs approximately $0.001-0.002. Once translated, content is cached automatically, so returning visitors won't trigger new API calls.

How many languages are supported?

Over 250 languages are supported, from major world languages to regional dialects. The widget includes flags for the most common languages.

Do I need an API key?

For demo and testing purposes, no API key is required. For production use with higher volume, you'll need to register for an API key on our website.

Can I translate dynamic content?

Yes! Simply add the data-i18n attribute to new elements and call the translate() method again with the current language code.

Is the translation quality good?

We use state-of-the-art neural machine translation models that understand context, technical terminology, and maintain natural language flow. Quality is comparable to professional human translation for most content.

💬 Support

Need help or have questions? We're here to assist you.

GitHub Issues

Report bugs or request features on our GitHub repository

Email Support

Contact us at support@multilingua.dev for technical assistance

Check this page for detailed guides and API reference