国际化词条资源管理

名词解释

• SDK: Foxit PDF SDK For Web.
• Addon: 发布包 uix-addons 目录下的扩展功能
• 词条: 定义在 JSON 配置文件，并根据语言类型放在以语言代码命名的目录中。
• 应用层: 使用 SDK 接口开发的上层功能架构

概览

本节介绍了关于国际化词条资源管理的一些细节，包括：

• SDK 词条资源文件、命名空间管理
• 如何新增语种
• 如何重写部分已有的词条
• 自定义 Addon 词条

SDK 国际化词条资源管理

目录结构以及文件的作用

SDK 发布包中， 国际化词条被放置在 lib/locales/ 目录中， 并按照语言代码分类。根据语言代码创建相应的子目录：

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

在语言代码目录下，有 ui_.json 和 viewer_.json 两个文件。如果应用层基于 PDFViewCtrl 库开发，则只依赖 viewer_.json 词条文件；如果应用层基于 UIExtension 库开发，则其将依赖 ui_.json 和 viewer_.json 两个文件。

自定义词条文件的目录

如果 SDK 默认的词条不能满足应用层的需求，则需要重写词条，或者新增语种。在这种情况下，建议开发人员在应用层创建一个目录，用来专门存放自定义词条。

该目录的结构要和 SDK 发布包的词条目录结构一致，且词条文件名称必须是 ui_.json 和 viewer_.json, 例如：

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

确定词条目录的路径后，在构造 PDFUI 或者 PDFViewer 实例时指定词条路径：

基于 PDFViewCtrl:

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

基于 UIExtension:

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

在开发环境中验证配置

1. 清除浏览器缓存以确保加载最新的 i18n 资源。
2. 刷新浏览器，在 DevTools 中打开 Network 面板，检查 ui_.json 或者 viewer_.json 请求 url 是否指向您自定义的语言路径。如果是，则说明配置成功。

新增语种

基于上述自定义词条文件目录的方法，新增语种只需在 /custom/locales/ 目录中新增语言代码目录，并对照 en-US 的词条编写对应语种的词条文件。

以 ko-KR 为例，新增词条后的目录结构如下所示：

/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

新增词条完成以后，可以在初始化库时指定默认语言：

基于 PDFViewCtrl:

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

基于 UIExtension:

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

此外，也可以动态切换语音：

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

重写部分词条

如果 SDK 大部分词条可以满足应用层需求，只需要进行小部分的修改，则可以通过 i18next.js (opens new window) 的 addResources (opens new window) 和 addResourceBundle (opens new window) 方法来重写词条。

基于 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);

基于 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);
    // 使上面的配置在界面上生效。
    pdfui.getRootComponent().then(root => {
        root.localize();
    });
})

自定义 Addon 词条

关于Addon，请参阅 Addons简介章节。

下表列出了所有 Addon 以及对应的词条命名空间：

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

添加/覆盖词条时，可以使用上述表格中的命名空间来添加/覆盖指定 addon 的词条，如下所示：

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

有关 addon 词条更详细的信息，请参阅 SDK 发布包中的 uix-addons/{addon-name}/locales/en-US.json 文件。