Localization

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)
  • Finnish (fi)
  • French (fr)
  • 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)
  • Serbian (sr)
  • Slovak (sk)
  • Slovenian (sl)
  • Spanish (es)
  • Swedish (sv)
  • Thai (th)
  • Turkish (tr)
  • Ukrainian (uk)

The full list of supported languages is exposed as PSPDFKit.I18n.locales.

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:

1
2
3
4
PSPDFKit.load({
  locale: "de"
  // other configuration options
});
1
2
3
4
PSPDFKit.load({
  locale: "de"
  // other configuration options
});

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

1
2
await instance.setLocale("de")
console.log("Successfully changed the language to German.");
1
2
3
instance.setLocale("de").then(function() {
  console.log("Successfully changed the language to German.");
});

Customizing Existing Translations

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

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

Copy
1
2
3
4
5
6
7
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."
Copy
1
2
3
4
5
6
7
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."

Preloading Localization Data

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:

Copy
1
2
3
4
5
6
7
await PSPDFKit.I18n.preloadLocalizationData("en")
PSPDFKit.I18n.messages.en.searchNextMatch = "Go to the next search result.";
// ...
PSPDFKit.load({
    locale: "en",
    // other configuration options
});
Copy
1
2
3
4
5
6
7
8
9
PSPDFKit.I18n.preloadLocalizationData("en").then(function() {
  PSPDFKit.I18n.messages.en.searchNextMatch =
    "Go to the next search result.";
  // ...
  PSPDFKit.load({
    locale: "en"
    // other configuration options
  });
});

Add More Localization

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

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

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 three objects above, as shown below.

  1. Push the new locale to the PSPDFKit.I18n.locales array:
1
PSPDFKit.I18n.locales.push("fr");
1
PSPDFKit.I18n.locales.push("fr");
  1. Add the translated messages to the PSPDFKit.I18n.messages object:
1
2
3
4
PSPDFKit.I18n.messages.fr = {
  searchNextMatch: "Prochain"
  // other translations here
};
1
2
3
4
PSPDFKit.I18n.messages.fr = {
  searchNextMatch: "Prochain"
  // other translations here
};

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

  1. Add the localization rules to the PSPDFKit.I18n.localeData object:
1
2
import fr from "react-intl/locale-data/fr";
PSPDFKit.I18n.localeData.fr = fr;
1
2
var fr = require("react-intl/locale-data/fr");
PSPDFKit.I18n.localeData.fr = fr;

Internally, PSPDFKit for Web uses React Intl’s locale data modules and includes the necessary information for the built-in default locales to work.

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.
  • Add the locale data to PSPDFKit.I18n.localeData.

Here’s how to add the locale data for French via the script tag:

Copy
1
2
<script src="https://unpkg.com/[email protected]/locale-data/fr.js"></script>
<script>PSPDFKit.I18n.localeData.fr = ReactIntlLocaleData.fr</script>

And here’s how to add the locale data for French via JavaScript’s import:

1
2
import fr from "react-intl/locale-data/fr";
PSPDFKit.I18n.localeData.fr = fr;
1
2
const fr = require("react-intl/locale-data/fr");
PSPDFKit.I18n.localeData.fr = fr;

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.