I18n Entries Resources Management

Explanation

• SDK: Foxit PDF SDK for Web.
• Addon: The addon features in the uix-addons directory of Foxit PDF SDK for Web.
• Entries: Defined in the JSON configuration file and placed in a directory named after the language code based on the language type.
• Application layer: The upper layer architecture developed by the SDK interface.

Overview

This section provides some details about the management of i18n entries resources. It includes:

• SDK entries resources file, namespace management
• How to add a new language
• How to rewrite some existing entries
• Customize the entries of Addon

SDK I18n Entries Resource Management

The directory structure and the role of the file

In the SDK release package, internationalized entries are placed in the 'lib/locales/' directory and sorted by language code. Create the sub-directories based on the language code:

lib/locales
        ├── en-US
        ├── ja-JP
        └── zh-CN

In the language code directory, there are 'ui_.json' and 'viewer_.json' files. If application layer is developed based on PDFViewCtrl library, it only relies on the 'viewer_.json' entry file; if application layer is developed based on UIExtension library, it relies on both the 'ui_.json' and 'viewer_.json' files.

The directory of the custom entry file

If the default entries of SDK cannot meet the needs of the application layer, so that you need to rewrite the entries, or add new languages. In this case, it is recommended that developers should create a new directory at the application layer to store the custom entries.

The structure of the created directory should be consistent with the entries directory structure of the SDK release package, and the name of the entries file must be ui_.json and viewer_.json, for example:

/custom/locales
        ├── en-US
        │   ├── ui_.json
        │   └── viewer_.json
        ├── ja-JP
        │   ├── ui_.json
        │   └── viewer_.json
        └── zh-CN
            ├── ui_.json
            └── viewer_.json

After determining the entry directory path, specify the entry path when constructing a PDFUI or PDFViewer instance:

Based on PDFViewCtrl:

new PDFViewer({
    i18nOptions: {
        absolutePath: '/custom/locales/'
    }
})

Based on UIExtension:

new PDFUI({
    i18n: {
        absolutePath: '/custom/locals'
    }，
})

Verify the configuration in developer environment

1. Clear your browser caches to ensure the latest i18N resources will be loaded.
2. Refresh your browser, open the Network panel in DevTools,and check if the ui_.json or viewer_.json request url points your custom language path. If so, it means success.

Add new languages

Based on the above method of customizing the entry file directory, for adding new languages, you should only add the language code directory in the /custom/locales/ directory, and then write the entry file for the corresponding language according to the en-US entry.

Taking ko-KR for example, after adding new entry, the directory structure will look like:

/custom/locales
        ├── en-US
        │   ├── ui_.json
        │   └── viewer_.json
        ├── ja-JP
        │   ├── ui_.json
        │   └── viewer_.json
        ├── ko-KR
        │   ├── ui_.json
        │   └── viewer_.json
        └── zh-CN
            ├── ui_.json
            └── viewer_.json

After finishing adding new languages, you can specify the default language when initializing the library:

Based on PDFViewCtrl:

const pdfViewer = new PDFViewer({
    i18nOptions: {
        initOption: {
            lng: 'ko-KR'
        }
    }
})

Based on UIExtension:

const pdfui = new PDFUI({
    i18n: {
        lng: 'ko-KR'
    }
})

In addition, you can switch languages dynamically:

pdfViewer.changeLanguage('ko-KR');
pdfui.changeLanguage('ko-KR');

Rewrite some of the entries

If most of the SDK entries can meet the requirements of the application layer, and just need to do some minor modification, then you can use the functions addResources (opens new window) and addResourceBundle (opens new window) of i18next.js (opens new window) to overwrite the entries.

Based on PDFViewCtrl:

pdfViewer.i18n.addResource('en-US', 'viewer_', 'contextmenu.hand.zoomin', 'Custom Zoom in');
pdfViewer.i18n.addResources('en-US', 'viewer_', {
    'contextmenu.hand.zoomin': 'Custom Zoom in',
    'contextmenu.hand.zoomout': 'Custom Zoom out'
});
pdfViewer.i18n.addResourceBundle('en-US', 'viewer_', {
    contextmenu: {
        hand: {
            zoomin: 'Custom Zoom in',
            zoomout: 'Custom Zoom out'
        }
    }
}, true, true);

Based on UIExtension:

pdfui.waitForInitialization().then(() => {
    pdfui.i18n.addResource('en-US', 'ui_', 'contextmenu.tools.handTool', 'Custom Hand Tool');
    pdfui.i18n.addResources('en-US', 'ui_', {
        'contextmenu.tools.handTool': 'Custom Hand Tool',
        'contextmenu.tools.selectAnnotation': 'Custom Select Annotation Tool'
    });
    pdfui.i18n.addResourceBundle('en-US', 'ui_', {
        contextmenu: {
            tools: {
                handTool: 'Custom Hand Tool',
                selectAnnotation: 'Custom Select Annotation Tool'
            }
        }
    }, true, true);
    // make the above configuration work on the interface.
    pdfui.getRootComponent().then(root => {
        root.localize();
    });
})

Customize the entries of Addon

For Addon, please refer to this section Introduction to addons.

The following table lists all Addons and the corresponding entries namespaces:

Addon	i18n namespace
edit-graphics	ega
export-form	export
file-property	file-property
form-designer	form-designer
h-continuous	h-continuous
h-facing	h-facing
h-single	h-single
import-form	import
print	print
recognition-form	recognition-form
text-object	edit-text
thumbnail	thumbnail

When adding/overwriting the entries, you can use the namespaces in the above table to add/overwrite the entries of a specific addon, as follows:

pdfui.waitForInitialization().then(() => {
    pdfui.i18n.addResourceBundle('en-US', 'print', {
        dialog: {
            cancel: 'custom cancel'
        }
    }, true, true);
    pdfui.getRootComponent().then(root => {
        root.localize();
    });
})

For more details about the addon entries, you can refer to the uix-addons/{addon-name}/locales/en-US.json file in the SDK release package.