Internationalization (i18n)

The EmbedPDF Snippet comes with built-in support for multiple languages. It allows you to translate the entire user interface—including tooltips, menus, and button labels—to match your application’s locale.

Built-in Locales

We provide out-of-the-box support for several languages, including:

• English (en) - Default
• Dutch (nl)
• German (de)
• French (fr)
• Spanish (es)
• Simplified Chinese (zh-CN)

Configuration

You can configure the initial language and available locales via the i18n property in your config object.

const viewer = EmbedPDF.init({
  // ...
  i18n: {
    defaultLocale: 'de', // Start in German
    fallbackLocale: 'en' // Use English if a translation is missing
  }
});

Changing Language at Runtime

You can switch languages dynamically without reloading the viewer. This is useful for synchronizing the PDF viewer with your application’s language picker.

How to Switch Language

To change the language programmatically, you need to access the i18n plugin instance from the viewer’s registry.

// 1. Wait for the registry to be ready
const registry = await viewer.registry;
 
// 2. Get the i18n capability
const i18n = registry.getPlugin('i18n').provides();
 
// 3. Set the new locale
i18n.setLocale('es');

Listening for Language Changes

If you need to know when the language changes (for example, to save the user’s preference to local storage or sync with another part of your app), you can subscribe to the onLocaleChange event.

const registry = await viewer.registry;
const i18n = registry.getPlugin('i18n').provides();
 
// Subscribe to changes
const unsubscribe = i18n.onLocaleChange(({ previousLocale, currentLocale }) => {
  console.log(`Language changed from ${previousLocale} to ${currentLocale}`);
});
 
// Later, you can unsubscribe if needed
// unsubscribe();

Custom Translations

If you need to support a language not included by default, or want to override specific labels, you can provide your own translation objects.

const customSpanish = {
  code: 'es',
  name: 'Español',
  translations: {
    zoom: {
      in: 'Acercar',
      out: 'Alejar',
    },
    document: {
      open: 'Abrir Documento',
    }
    // ... other keys
  }
};
 
const viewer = EmbedPDF.init({
  // ...
  i18n: {
    defaultLocale: 'es',
    // Register your custom locale
    locales: [customSpanish] 
  }
});