В этом руководстве вы узнаете, как перевести UI настроек интеграции в Medusa Admin.

В дескрипторе нет отображаемого текста, только i18n-ключи. Admin подставляет каждый ключ на языке пользователя, поэтому один дескриптор работает на всех языках, для которых ваша интеграция поставляет переводы.

Эти поля дескриптора принимают i18n-ключ, а не текст:

• displayName и description интеграции;
• title каждой секции;
• label, hint и placeholder каждого параметра;
• valueLabels параметра типа enum, по ключу на значение.

Всё остальное на странице модуль переводит сам, включая метку категории, статусы и действия. Его собственный интерфейс переведён на 34 языка из тех, что поддерживает Medusa Admin.

---

Модуль интеграций построен на переводах Admin в Medusa, поэтому переводы находятся там же, где их ищет Medusa в любом плагине, в src/admin/i18n/index.ts.

Храните по JSON-файлу на язык с теми же ключами, что и в дескрипторе:

src/admin/i18n/json/en.json
1{
2  "my": {
3    "name": "My Payments",
4    "credentials": "Credentials",
5    "apiKey": "API key",
6    "sandbox": "Sandbox mode"
7  }
8}

Ключ вида my.apiKey указывает во вложенные объекты, здесь "my": { "apiKey": ... }, так же, как его читает t("my.apiKey"). Начинайте каждый ключ с идентификатора провайдера, как это делают провайдеры ЮKassa и ApiShip в ключах своих дескрипторов (yookassa.*, apiship.*). Medusa объединяет переводы всех плагинов в одном пространстве имён translation поверх собственных ключей, поэтому ключ, совпадающий с ключом ядра или другого плагина, переопределяет его во всей Admin. Префикс отделяет ваши ключи от чужих. Что вкладывать под префиксом, решаете вы.

Затем экспортируйте все языки из src/admin/i18n/index.ts:

src/admin/i18n/index.ts
1import en from "./json/en.json" with { type: "json" }
2import ru from "./json/ru.json" with { type: "json" }
3
4export default {
5  en: { translation: en },
6  ru: { translation: ru },
7}

При сборке панели администратора Medusa объединяет эти переводы с переводами самой Admin, поэтому ключи дескриптора, сгенерированные секции и ваши собственные виджеты пользуются одними и теми же переводами. В виджете вызывайте t() из useTranslation с теми же ключами.

---

Если у ключа нет перевода на языке пользователя, Admin показывает английский перевод. Если нет и английского, Admin показывает сам ключ, например my.apiKey, поэтому пропущенный перевод заметен на странице.

---

Сообщение message, которое ваши правила валидации передают в addIssue, остаётся обычным текстом, и Admin показывает его как есть. То же относится к message, которое возвращает testConnection. Пишите эти сообщения на языке, который читают администраторы вашего магазина, или делайте их короткими и техническими.

Сообщения встроенных правил, например о формате URL или о минимальной длине, это английский текст валидатора, и Admin показывает их как есть. Переводится только собственное сообщение формы о том, что поле обязательно, и в нём названо пустое поле.

---

Admin ищет в списке интеграций по переведённым названию и описанию, а в истории изменений по переведённым названиям интеграций и полей. Ключ без перевода ищется как сам ключ.

История изменений хранит вместе с изменением ключ метки каждого поля. Поле, которое вы позже уберёте из дескриптора, сохранит в истории читаемое название, пока его перевод остаётся в вашем плагине.