Поддержка языков

В Kepler.gl механизм поддержки языков построен вокруг системы интернационализации интерфейса (i18n), интегрированной в React-архитектуру библиотеки и связанной с Redux-состоянием приложения. Локализация охватывает текстовые элементы UI, форматирование чисел и дат, а также частично затрагивает отображение подписей на карте через Mapbox GL стили.

Система языков в Kepler.gl опирается на словарную модель сообщений, где каждый текстовый элемент интерфейса представлен ключом и соответствующим переводом. Эти словари передаются в компонент верхнего уровня и далее распространяются через контекст приложения.

Основные характеристики:

  • централизованное хранение переводов
  • использование структурированных message-объектов
  • интеграция с состоянием Redux
  • возможность переопределения встроенных текстов

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

Передача локали в KeplerGl компонент

Основная точка настройки языка — свойство locale, передаваемое в компонент KeplerGl. Оно содержит объект переводов, где ключи соответствуют идентификаторам текстовых ресурсов интерфейса.

import KeplerGl from 'kepler.gl';

const messages = {
  panel: {
    dataCatalog: 'Каталог данных',
    addData: 'Добавить данные'
  },
  toolbar: {
    select: 'Выбор',
    polygon: 'Полигон'
  }
};

<KeplerGl
  id="map"
  width={800}
  height={600}
  mapboxApiAccessToken={MAPBOX_TOKEN}
  locale={messages}
/>

Структура объекта locale повторяет иерархию UI-компонентов. При отсутствии ключа используется значение по умолчанию из встроенного английского словаря.

Структура сообщений и система ключей

Локализационные файлы Kepler.gl организованы в виде вложенных объектов:

  • panel — панели управления слоями и данными
  • toolbar — инструменты взаимодействия с картой
  • common — общие элементы интерфейса
  • map — элементы карты и подсказки
  • dataset — операции с данными

Каждый ключ представляет стабильный идентификатор, который не зависит от языка отображения.

Пример структуры:

const locale = {
  map: {
    mapLayers: 'Слои карты',
    baseMap: 'Подложка'
  },
  dataset: {
    title: 'Набор данных',
    add: 'Добавить'
  },
  common: {
    cancel: 'Отмена',
    confirm: 'Подтвердить'
  }
};

Переопределение встроенных переводов

Встроенные переводы Kepler.gl поставляются в виде стандартного набора сообщений (обычно английский язык). Механизм расширения реализован через глубокое объединение объектов.

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

const customLocale = {
  toolbar: {
    save: 'Сохранить проект',
    exportImage: 'Экспорт изображения'
  }
};

Такая модель позволяет частично локализовать интерфейс без необходимости полного перевода всех строк.

Интеграция с Redux-состоянием

Kepler.gl хранит часть локализационной информации в Redux-слое, что обеспечивает синхронизацию языка между различными компонентами приложения.

Основные моменты:

  • состояние locale может быть частью глобального store
  • изменения языка могут диспатчиться через actions
  • UI автоматически реагирует на обновления состояния

Пример структуры состояния:

{
  keplerGl: {
    map: {
      locale: {
        toolbar: {
          select: 'Выбор'
        }
      }
    }
  }
}

Такая организация позволяет централизованно управлять языком в приложениях с несколькими картами или разными экземплярами KeplerGl.

Динамическое переключение языков

Механизм переключения языка реализуется через замену объекта locale в состоянии или через обновление пропсов компонента.

При изменении объекта переводов происходит повторный рендер интерфейса без перезагрузки карты.

Ключевые особенности:

  • мгновенное обновление UI
  • отсутствие пересоздания map instance
  • сохранение состояния слоёв и данных

При работе через Redux изменение языка обычно осуществляется через dispatch соответствующего action, обновляющего часть state с переводами.

Форматирование чисел и дат

Локализация Kepler.gl затрагивает не только текст, но и форматирование значений, связанных с отображением данных.

Используются стандартные механизмы JavaScript Internationalization API:

  • Intl.NumberFormat для чисел
  • Intl.DateTimeFormat для дат

Это влияет на:

  • подписи шкал
  • значения всплывающих подсказок
  • легенды визуализаций

Пример различий:

  • десятичные разделители (, vs .)
  • формат даты (DD.MM.YYYY vs MM/DD/YYYY)
  • локальные обозначения времени

Поддержка локализации Mapbox GL

Отдельный слой языковой поддержки связан с картографической подложкой Mapbox GL. Kepler.gl не управляет напрямую переводом географических подписей, но использует Mapbox стили, где возможно включение локализованных названий.

В Mapbox GL поддерживаются выражения вида:

"text-field": "{name_ru}"

или динамический выбор языка:

"text-field": [
  "coalesce",
  ["get", "name_ru"],
  ["get", "name_en"]
]

Это позволяет синхронизировать язык интерфейса Kepler.gl с языком карты, но реализуется на уровне стиля Mapbox, а не самой библиотеки.

Подключение пользовательских словарей

Пользовательские переводы могут формироваться как отдельные модули и импортироваться в приложение.

Типичная структура:

const ruLocale = {
  toolbar: {
    select: 'Выделение',
    pan: 'Перемещение'
  },
  layer: {
    add: 'Добавить слой',
    remove: 'Удалить слой'
  }
};

Далее словарь объединяется с базовой локализацией:

import { LOCALE_EN } from 'kepler.gl/localization';

const locale = {
  ...LOCALE_EN,
  ...ruLocale
};

Такой подход обеспечивает постепенную локализацию без потери неизменённых частей интерфейса.

Поддержка множественных языков в одном приложении

В архитектуре Kepler.gl возможно одновременное хранение нескольких языковых наборов. Это актуально для приложений с переключением интерфейса в реальном времени.

Структура обычно выглядит следующим образом:

const locales = {
  en: englishLocale,
  ru: russianLocale,
  de: germanLocale
};

const currentLocale = locales[activeLanguage];

При изменении активного языка происходит перерасчёт props или обновление Redux state.

Ограничения и особенности локализации

Система языков в Kepler.gl имеет ряд архитектурных ограничений:

  • не все строки UI вынесены в словари (часть может быть в сторонних компонентах)
  • сложные визуальные элементы (подсказки, графики) частично зависят от deck.gl и mapbox
  • полная локализация требует синхронизации нескольких слоёв (UI, карта, форматирование)

Дополнительно важно учитывать, что глубина ключей в словарях должна строго соответствовать внутренней структуре библиотеки, иначе часть переводов не применяется.

Формат хранения локализационных данных

Локализация представлена в виде JSON-совместимых объектов. Основные требования к структуре:

  • отсутствие циклических ссылок
  • строгая иерархия ключей
  • строковые значения без HTML-логики (в большинстве случаев)
  • совместимость с deep merge стратегией

Такая структура обеспечивает предсказуемое объединение словарей при инициализации приложения и во время runtime-обновлений.

Оглавление