Adding Custom Localization to PSPDFKit for Web

PSPDFKit for Web comes with many built-in languages, the full list of which is exposed as PSPDFKit.I18n.locales. However, we don’t include every language, so it might be that you have to add a new localization whenever your project is displayed in a language that we don’t support. In this post, we’ll focus on how to add your own custom localization to PSPDFKit for Web.

You can find more information about the default behavior and supported languages in this guide article.

Localization API

PSPDFKit.I18n provides a simple and straightforward way of adding new locales. It consists of three parts, which the localization engine uses when translating:

Add New Localization Files

For the purpose of this tutorial, I will change some toolbar messages from English to emoji. My browser language is set to English, so the localization is English. Your browser might be set to a different language.

As a first step, I’ll add PSPDFKit to my project using the Standalone deployment.

Now let’s head over to the HTML file where the PSPDFKit instance is being loaded. Your file should look like some version of this:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<!DOCTYPE html>
<html>
  <head>
    <title>My App</title>
    <!-- 1. Include required files. -->
    <script src="https://pspdfkit.your-site.com/pspdfkit.js"></script>

    <!-- Provide proper viewport information so that the layout works on mobile devices. -->
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
    />
  </head>
  <body>
    <!-- 2. Element where PSPDFKit will be mounted. -->
    <div id="pspdfkit" style="width: 100%; height: 480px;"></div>

    <!-- 3. Initialize PSPDFKit. -->
    <script>
      PSPDFKit.load({
        container: "#pspdfkit",
        pdf: "<pdf-file-path>",
        licenseKey: "yourLicenseKey"
      })
        .then(function(instance) {
          console.log("PSPDFKit loaded", instance);
        })
        .catch(function(error) {
          console.error(error.message);
        });
    </script>
  </body>
</html>

So how do we change this?

Well, it’s fairly simple.

1. Add a New Locale

First, what you want to do is add the new locale to PSPDFKit.I18n. You can do this by pushing the new locale to the PSPDFKit.I18n.locales array. It’s important to do this before PSPDFKit.load is called:

1
`PSPDFKit.I18n.locales.push("em")`;

2. Add the Translated Messages

Next, add the translated messages to the PSPDFKit.I18n.messages object. You can use the English messages object (PSPDFKit.I18n.messages.en) as a template:

1
2
3
PSPDFKit.I18n.messages.em = {
  pen: "🖊"
};

3. Add Localization Rules

Finally, add the localization rules to the PSPDFKit.I18n.localeData object.

Now, to understand how to add locale data for a new language, please consider that, internally, we use react-intl locale data modules. This 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) via either the script tag or import.
  • Add the locale data to PSPDFKit.I18n.localeData.

⚠️ IMPORTANT: If you don’t create a file with the localization rules, it won’t work. Additionally, copying another rule localization file and assigning it to PSPDFKit.I18n.localeData.em won’t work. A quick hack to make it work for development purposes is to copy the English rules localization file and replace the “en” with the “em” language code throughout the file.

So in the end, your HTML file should look similar to this:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<!DOCTYPE html>
<html>
  <head>
    <script src="/pspdfkit.js"></script>
    <script src="/em.js"></script>
  </head>
  <body>
    <div id="pspdfkit" style="width: 100%; height: 480px;"></div>
  </body>
  <script type="module">
    PSPDFKit.I18n.locales.push("em");
    PSPDFKit.I18n.localeData.em = ReactIntlLocaleData.em;
    PSPDFKit.I18n.messages.em = {
      pen: "🖊"
    };
    PSPDFKit.load({
        container: "#pspdfkit",
        pdf: "<pdf-file-path>",
        licenseKey: "yourLicenseKey"
      }).then(function(instance) {
        console.log("PSPDFKit loaded", instance);
      }).catch(function(error) {
        console.error(error.message);
      }):
  </script>
</html>

And here is our pen emoji, pen: "🖊", displayed in the toolbar.

Conclusion

PSPDFKit for Web comes with many built-in languages, but whenever the need for a custom localization arises, adding it is a very straightforward process. As shown in this blog post, you can customize your PSPDFKit localization using three simple steps.

If you want to know more about PSPDFKit for Web and what it is capable of, be sure to check out our excellent guide articles to learn more about the available features.

PSPDFKit for Web

PDF viewing, annotating, and collaboration for web apps.

Try Now