# # 国际化词条资源管理

## # 名词解释

- 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` 文件。