Перейти к основному содержимому

Локализация

Система Workflow поддерживает локализацию на несколько языков, позволяя одному и тому же Workflow отображать соответствующие имена и описания в различных языковых интерфейсах Zotero.

Иерархия локализации​

Локализация Workflow откатывается в следующем порядке приоритета:

Встроенные сообщения (manifest.i18n.messages)  ← Наивысший приоритет
        ↓
Локализованные файлы на уровне пакета (locales/ пакета workflow-package)
        ↓
Сырые поля манифеста (label / description и т.д. английские значения по умолчанию)
        ↓
Откат по ключу (например, "workflows.my-id.label")

Встроенная локализация (одиночный Workflow)​

Определяется непосредственно в workflow.json:

{
  "id": "my-workflow",
  "label": "My Workflow",
  "i18n": {
    "defaultLocale": "en-US",
    "messages": {
      "zh-CN": {
        "label": "我的 Workflow",
        "taskNameTemplate": "处理中: {query}",
        "parameters.language.title": "语言",
        "parameters.language.description": "选择输出内容的语言"
      },
      "ja-JP": {
        "label": "マイワークフロー",
        "taskNameTemplate": "処理中: {query}"
      }
    }
  }
}

Поля, такие как label и taskNameTemplate в сыром манифесте, служат значениями по умолчанию (обычно английскими), и переводы в i18n.messages переопределяют отображаемый текст для соответствующего языка.

Соглашения по именованию ключей​

label                                    — Название Workflow
taskNameTemplate                         — Шаблон названия задачи
parameters.<paramKey>.title              — Заголовок параметра
parameters.<paramKey>.description         — Описание параметра
skills.<skillId>.name                    — Отображаемое имя skill в текущем workflow

skills.<skillId>.name влияет только на отображаемое имя в интерфейсе. runner.json.name пакета Skill остаётся именем по умолчанию; если workflow не объявляет соответствующий перевод, интерфейс отображает runner.json.name в качестве резервного варианта.

Локализация на уровне пакета (пакет из нескольких Workflow)​

Объявите локализованные файлы в workflow-package.json:

{
  "id": "my-package",
  "i18n": {
    "defaultLocale": "en-US",
    "locales": {
      "zh-CN": "locales/zh-CN.json",
      "ja-JP": "locales/ja-JP.json"
    }
  }
}

Содержимое locales/zh-CN.json:

{
  "workflows.my-workflow.label": "我的工作流",
  "workflows.my-workflow.taskNameTemplate": "处理中: {query}",
  "workflows.my-workflow.skills.my-skill.name": "我的技能",
  "workflows.my-workflow.parameters.language.title": "语言",
  "workflows.another-workflow.label": "另一个工作流"
}

Ключи в локализованных файлах на уровне пакета используют полностью квалифицированный формат: workflows.<workflowId>.<field>.

Смешанное использование​

Локализованные сообщения на уровне пакета и встроенные сообщения Workflow могут сосуществовать, при этом встроенные сообщения имеют более высокий приоритет. Лучшие практики:

  • Оставьте язык по умолчанию (например, английский) в полях workflow.json
  • Поместите переводы в локализованные файлы на уровне пакета для унифицированного управления
  • Если перевод очень специфичен для конкретного Workflow, он также может быть помещён во встроенные сообщения Workflow

Логика сопоставления языка​

Система пытается сопоставить языковые настройки пользователя в следующем порядке:

  1. Точное совпадение: Локаль пользователя "zh-CN", ищем сообщения "zh-CN"
  2. Совпадение подтега языка: Локаль пользователя "zh-Hans-CN", если точное совпадение не найдено, пробуем сопоставить "zh"
  3. Откат к defaultLocale: Используйте язык, указанный в i18n.defaultLocale
  4. Откат к значению сырого поля: Используйте сырые значения полей в workflow.json (например, label)
  5. Откат к ключу: Отобразите само имя ключа

Локализация значений enum параметров​

Если параметр имеет значения enum, отображаемый текст для значений enum в настоящее время использует поля title и description параметра. Для сложных сценариев, требующих локализации самих значений enum, рекомендуется объяснить это в label или описании Workflow.

Добавление нового языка в Workflow​

  1. Создайте новый файл <locale>.json в каталоге locales/ пакета
  2. Обратитесь к существующим локализованным файлам (например, zh-CN.json) и переведите все ключи
  3. Добавьте новую запись языка в i18n.locales файла workflow-package.json
  4. Перезагрузите плагин для вступления в силу

Справочник​

  • Пример официального локализованного файла: content/official/workflows/literature-workbench-package/locales/zh-CN.json
  • Пример объявления i18n на уровне пакета: content/official/workflows/literature-workbench-package/workflow-package.json

Следующие шаги​