跳到主要内容

本地化

所有插件默认使用英文创建。如果你希望插件支持你的语言，可以为其添加翻译。

翻译 config.json 部分​

首先，你可以翻译 config.json 文件。打开该文件，找到其中的所有英文字符串。通常它们位于配置对象的 name、variations.description 和 variations.buttons.text 节点中。

为这些键添加新的以 Locale 结尾的节点，值为一个以语言区域码为键、翻译内容为值的对象。例如，对于 name 键，其本地化对象如下所示：

{
  "name": "Highlight code",
  "nameLocale": {
    "de": "Code hervorheben",
    "es": "Resaltar el código",
    "fr": "Code en surbrillance"
  }
}

highlighting 插件代码的完整 config.json 翻译如下：

{
  "name": "Highlight code",
  "nameLocale": {
    "de": "Code hervorheben",
    "es": "Resaltar el código",
    "fr": "Code en surbrillance"
  },
  "variations": [
    {
      "description": "Highlight code",
      "descriptionLocale": {
        "de": "Code hervorheben",
        "es": "Resaltar el código",
        "fr": "Code en surbrillance"
      },
      "buttons": [
        {
          "text": "Cancel",
          "textLocale": {
            "de": "Abbrechen",
            "es": "Cancelar",
            "fr": "Annuler"
          }
        }
      ]
    }
  ]
}

本地化 index.html 和插件代码文件​

从 index.html 和 pluginCode.js 文件中找出你希望本地化的所有字符串并创建一个列表。然后在插件目录中创建 translations 文件夹，使目录结构如下：

highlightcode/
├── translations/
├── scripts/
    ├── pluginCode.js
├── config.json
├── index.html

为每种语言创建对应的 .json 文件，文件名使用语言的四位语言区域码（如 de-DE.json）。这些文件包含一个对象，键为原始英文单词或短语，值为对应语言的翻译。例如，德语翻译文件如下：

{
  "Language": "Sprache",
  "Highlight": "Hervorheben",
  "Style": "Stil"
}

从 7.2 版本开始，你可以在翻译文件夹中添加 langs.json 文件。该文件以数组形式列出包含翻译内容的语言文件名：

[
  "cs-CZ",
  "de-DE",
  "es-ES",
  "fr-FR"
]

系统首先会请求 langs.json 文件，并尝试完整匹配语言码和文件名。如果没有找到完全匹配项，则会检查 "-" 前的前两个字符。如果 langs.json 中不包含所需文件名，插件将使用英文。若未提供 langs.json 或其解析出错，将使用旧的翻译机制。

添加完所有本地化文件后，插件文件结构如下：

highlightcode/
├── translations/
    ├── de-DE.json
    ├── es-ES.json
    ├── fr-FR.json
    ├── langs.json
├── scripts/
    ├── pluginCode.js
├── config.json
├── index.html

你现在可以将文件中的字符串替换为对应的翻译结果。

应用翻译到插件​

为了应用翻译，你需要为每个包含待翻译字符串的元素添加唯一 ID。例如，若想本地化以下代码中的 New 按钮：

<button>New</button>

则需要添加 id 属性，修改为：

<button id="button_new">New</button>

然后在 pluginCode.js 文件中添加 window.Asc.plugin.onTranslate 函数：

window.Asc.plugin.onTranslate = () => {
  const label = document.querySelector("button_new")
  if (label) {
    label.innerHTML = window.Asc.plugin.tr("New")
  }
}

window.Asc.plugin.onTranslate 函数将在插件启动后立即调用，也会在更改插件语言时再次调用。

如果你需要本地化多个词语/短语，window.Asc.plugin.onTranslate 函数可写为如下形式：

window.Asc.plugin.onTranslate = () => {
  document.querySelector("button_delete").innerHTML =
    window.Asc.plugin.tr("Delete");
  document.querySelector("button_new").innerHTML = window.Asc.plugin.tr("New");
  document.querySelector("button_rename").innerHTML =
    window.Asc.plugin.tr("Rename");
  document.querySelector("button_run").innerHTML = window.Asc.plugin.tr("Run");
};

每一行对应一个待本地化的元素，通过相应的 ID 进行定位。

备注

翻译使用的是 .innerHTML 方法，因此翻译内容不仅可以是文字，还可以包含一些 HTML 元素（标签、链接等）。请不要忘记在翻译内容中转义引号（就像处理所有的 .json 文件一样），以确保其正确解析。

现在，当编辑器启动后，将根据当前界面语言判断插件是否具有相应语言的翻译内容。如果匹配，插件语言将自动切换为编辑器界面语言，并应用相应翻译。

故障排除：本地化问题​

JavaScript 文件错误​

错误名称： 函数名错误

错误示例
var language = document.getElementBy("language");
正确示例
var language = document.getElementById("language");

错误输出："document.getElementBy 不是一个函数" (开发者工具)

错误名称： 元素 ID 不匹配

错误示例
var language = document.getElementById("lanuge");
language.innerHTML = window.Asc.plugin.tr("Language");
正确示例
var language = document.getElementById("language");
language.innerHTML = window.Asc.plugin.tr("Language");

错误输出：静默回退为英文 / ONLYOFFICE 将默认语言设为英语，且不报错。

错误名称： 变量名拼写错误

错误示例
var language = document.getElementById("language");
lanuge.innerHTML = window.Asc.plugin.tr("Language");
正确示例
var language = document.getElementById("language");
language.innerHTML = window.Asc.plugin.tr("Language");

错误输出：控制台显示 "lanuge is not defined"，直接指向拼写错误。

错误名称： 翻译键名错误

错误示例
language.innerHTML = window.Asc.plugin.tr("Lanuge");
正确示例
language.innerHTML = window.Asc.plugin.tr("Language");

错误输出：不会显示错误，而是将错误的键名直接显示在用户界面中。用户将看到 "Lanuge" 而不是翻译后的文本。

结构错误​

错误名称： 缺少或错误命名的翻译文件

错误示例
highlightcode/
├── translations/
    ├── de-WRONG-NAME.json
    ├── es-ES.json
    ├── fr-FR.json
    ├── langs.json
├── scripts/
    ├── pluginCode.js
├── config.json
├── index.html
正确示例
highlightcode/
├── translations/
    ├── de-DE.json
    ├── es-ES.json
    ├── fr-FR.json
    ├── langs.json
├── scripts/
    ├── pluginCode.js
├── config.json
├── index.html

错误输出："ERR_FILE_NOT_FOUND ; translations/de-DE.json" (开发者工具)

配置文件错误​

错误名称： 配置中使用了错误的语言代码

错误示例
{
  ...
  "name": "Highlight code",
  "nameLocale": {
    "de-WRONG-NAME": "Code hervorheben",
    "es": "Resaltar el código",
    "fr": "Code en surbrillance"
},
正确示例
{
  ...
  "name": "Highlight code",
  "nameLocale": {
    "de": "Code hervorheben",
    "es": "Resaltar el código",
    "fr": "Code en surbrillance"
},

错误输出：静默回退为英文 / ONLYOFFICE 将默认语言设为英语，且不报错。