Internationalization string resources

Terminology

SDK: Foxit PDF SDK for Web

Addons: Extension plugins under lib/uix-addons in the release package

Strings: Entries defined in JSON configuration files, organized in folders named by language code

Application layer: Your product built on top of the SDK APIs

Tip: If you develop with UIExtension components, see the I18n component guide for UI-specific usage.

Overview

This topic covers:

• SDK string files and namespaces
• Adding a new language
• Overriding existing strings
• Custom add-on strings

SDK string resource management

Directory layout and files

In the SDK package, strings live under lib/locales/, grouped by language code:

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

Each language folder contains ui_.json and viewer_.json.

• Applications built on PDFViewCtrl use only viewer_.json.
• Applications built on UIExtension use both ui_.json and viewer_.json.

Custom string directories

When default SDK strings are not enough—or you add a new language—create an application-level folder for your overrides.

Mirror the SDK locale layout and keep the filenames 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

Point PDFUI or PDFViewer at your locale path when constructing the instance.

With PDFViewCtrl:

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

With UIExtension:

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

Verify configuration in development

1. Clear the browser cache so the latest i18n files load.
2. Refresh the page, open the Network panel in DevTools, and confirm requests for ui_.json or viewer_.json hit your custom locale path.

Add a new language

Add a folder under /custom/locales/ for the new language code and copy strings from en-US as a starting point.

For ko-KR, the layout might 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

Set the default language at initialization:

With PDFViewCtrl:

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

With UIExtension:

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

You can also switch language at runtime:

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

Override selected strings

When most SDK strings are fine and you only need small changes, use i18next.jsaddResources and addResourceBundle.

With 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);

With 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);
    // Apply the overrides to the UI.
    pdfui.getRootComponent().then(root => {
        root.localize();
    });
})

Custom add-on (Addons) strings

For add-ons, see Add-ons.

Add-on namespaces:

Addons	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

Use the namespace from the table when adding or overriding add-on strings:

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

For more add-on string keys, see uix-addons/{addon-name}/locales/en-US.json in the SDK package.