Localization: Updating Languages in Our JavaScript PDF Viewer

PSPDFKit for Web comes with many built-in languages:

  • Chinese Simplified / Chinese Traditional (zh-Hans/zh-Hant)

  • Croatian (hr)

  • Czech (cs)

  • Danish (da)

  • Dutch (nl)

  • English (en)

  • English United Kingdom (en-GB)

  • Finnish (fi)

  • French (fr)

  • French Canada (fr-CA)

  • German (de)

  • Greek (el)

  • Indonesian (id)

  • Italian (it)

  • Japanese (ja)

  • Korean (ko)

  • Malay (ms)

  • Norwegian Bokmål (nb-NO)

  • Polish (pl)

  • Portuguese Brazil / Portugal (pt/pt-PT)

  • Russian (ru)

  • Slovak (sk)

  • Slovenian (sl)

  • Spanish (es)

  • Swedish (sv)

  • Thai (th)

  • Turkish (tr)

  • Ukrainian (uk)

  • Welsh (cy)

Adding Additional Localization to PSPDFKit

PSPDFKit for Web allows the addition of new locales in a simple and straightforward manner.

PSPDFKit.I18n consists of two parts, which the localization engine uses when translating:

Since PSPDFKit for Web 2020.1, pluralization and formatting rules don’t need to be added, as the native Intl API is used instead (a change introduced in react-intl v3).

Browsers that don’t support the Intl API (like Safari 13 and below) will include a polyfill for Intl.PluralRules, as well as an individual polyfill for each of the supported locales. If you want to keep supporting these browsers when providing additional locales, you can do so by including the corresponding locale polyfill:

// Add the locale to the locales list (Wolof language).
PSPDFKit.I18n.locales.push('wo');
// Is this browser using the `Intl.PluralRules` polyfill?
if (Intl.PluralRules.polyfilled) {
	// Then include the plural rules locale data polyfill.
	await import('@formatjs/intl-pluralrules/dist/locale-data/wo');
}
// Add Wolof translations for messages.
PSPDFKit.I18n.messages['wo'] = wolofMessages;
// Change current language to Wolof.
instance.setLocale('wo');

Add the locale data polyfills to your local node_modules folder by installing them using npm:

npm i @formatjs/intl-pluralrules

As a result of these changes, PSPDFKit.I18n.localizationData, which was used before PSPDFKit for Web 2020.1 to add localization data, is now deprecated.

Let’s say we want to add support for French (please note this is just an example and PSPDFKit for Web already supports French). To do this, we have to add the information about test to the two objects above, as shown below.

  1. Push the new locale to the PSPDFKit.I18n.locales array:

PSPDFKit.I18n.locales.push('fr');

  1. Add the translated messages to the PSPDFKit.I18n.messages object:

PSPDFKit.I18n.messages.fr = {
	searchNextMatch: 'Prochain',
	// Other translations here.
};

You can use the English messages object (PSPDFKit.I18n.messages.en) as a template.

  1. Optionally, add the polyfill for browsers not supporting the Intl API:

// Is this browser using the `Intl.PluralRules` polyfill?
if (Intl.PluralRules.polyfilled) {
	// Then include the plural rules locale data polyfill.
	await import('@formatjs/intl-pluralrules/dist/locale-data/fr');
}

In order to add locale data for a new language, you need to:

  • Follow the download instructions on the react-intl page.

  • Load react-intl/locale-data/YourNewLocaleSymbol (the locale data) either via the script tag or import.

  • Optionally, add the localization data polyfill for browsers not supporting the Intl API.

Now your application is ready to be used in French.

Please note that we don’t store your information. As such, you need to persist translations in your data store of choice.

Customizing Existing Translations

Once localization data is loaded, all the translated messages will be available on the PSPDFKit.I18n.messages object.

To customize a string for a specific locale, you can mutate this object directly:

console.log(PSPDFKit.I18n.messages.en.searchNextMatch);
// > "Next"

PSPDFKit.I18n.messages.en.searchNextMatch = 'Go to the next search result.';
console.log(PSPDFKit.I18n.messages.en.searchNextMatch);
// > "Go to the next search result."

Please keep in mind that, by default, translations are only available after you create an instance of PSPDFKit for Web. If you want to modify translations before creating an instance, you need to preload localization data using the PSPDFKit.I18n.preloadLocalizationData method:

await PSPDFKit.I18n.preloadLocalizationData('en');
PSPDFKit.I18n.messages.en.searchNextMatch = 'Go to the next search result.';
// ...
PSPDFKit.load({
	locale: 'en',
	// Other configuration options.
});

Forcing a Specific Language

By default, PSPDFKit for Web tries to detect the language using the navigator.language value. However, the locale can be programmatically set before loading PSPDFKit via the locale configuration option:

PSPDFKit.load({
	locale: 'de',
	// Other configuration options.
});

The locale can be changed at runtime using the instance method Instance#setLocale:

await instance.setLocale('de');
console.log('Successfully changed the language to German.');