Internationalization (i18n)

The PDFViewer 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.

<PDFViewer
  config={{
    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.

const changeLanguage = async (locale: string) => {
  // 1. Wait for the registry to be ready
  const registry = await viewerRef.current?.registry;
  
  // 2. Get the i18n capability
  const i18n = registry.getPlugin('i18n').provides();
  
  // 3. Set the new locale
  i18n.setLocale(locale);
};

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 viewerRef.current?.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
  }
};
 
<PDFViewer
  config={{
    i18n: {
      defaultLocale: 'es',
      // Register your custom locale
      locales: [customSpanish] 
    }
  }}
/>