Локализация результатов

Локализация результатов — это механизм адаптации ответов геосервисов под язык, региональные стандарты и культурные особенности конкретной страны или пользователя. В HERE Maps API локализация влияет на отображение:

  • названий стран, городов и улиц;
  • адресных компонентов;
  • результатов геокодирования;
  • подсказок поиска;
  • категорий объектов;
  • информации о маршрутах;
  • текстовых инструкций навигации.

Правильно настроенная локализация позволяет получать результаты на нужном языке даже при работе с международными адресами и объектами.

Роль параметра lang

Большинство сервисов HERE поддерживают параметр lang, определяющий язык ответа.

Пример запроса к Geocoding & Search API:

const url =
  'https://geocode.search.hereapi.com/v1/geocode' +
  '?q=Paris' +
  '&lang=ru' +
  '&apiKey=YOUR_API_KEY';

fetch(url)
  .then(response => response.json())
  .then(data => {
    console.log(data);
  });

В результате:

  • названия стран будут возвращены на русском языке;
  • административные регионы локализуются;
  • адресные компоненты адаптируются под выбранную локаль.

Например:

{
  "countryName": "Франция",
  "state": "Иль-де-Франс",
  "city": "Париж"
}

Без параметра локализации сервис может вернуть:

{
  "countryName": "France",
  "state": "Île-de-France",
  "city": "Paris"
}

Использование языковых кодов

HERE Maps API использует стандартные языковые идентификаторы ISO.

Наиболее распространённые варианты:

Код Язык
ru Русский
en Английский
de Немецкий
fr Французский
es Испанский
it Итальянский
pt Португальский
ja Японский
ko Корейский
zh Китайский

Пример:

const language = 'de';

const url =
  `https://discover.search.hereapi.com/v1/discover?q=restaurant` +
  `&at=52.5200,13.4050` +
  `&lang=${language}` +
  `&apiKey=YOUR_API_KEY`;

Локализация поиска объектов

Сервис Discover Search позволяет получать объекты на выбранном языке.

Пример поиска музеев:

async function searchMuseums() {
  const response = await fetch(
    'https://discover.search.hereapi.com/v1/discover' +
    '?q=museum' +
    '&at=48.8566,2.3522' +
    '&lang=ru' +
    '&apiKey=YOUR_API_KEY'
  );

  const result = await response.json();

  console.log(result.items);
}

searchMuseums();

Если локализованное название существует в базе HERE, оно будет возвращено автоматически:

{
  "title": "Лувр"
}

В противном случае используется оригинальное название:

{
  "title": "Louvre Museum"
}

Локализация обратного геокодирования

Reverse Geocoding преобразует координаты в адрес.

Пример:

const latitude = 51.5074;
const longitude = -0.1278;

const url =
  `https://revgeocode.search.hereapi.com/v1/revgeocode` +
  `?at=${latitude},${longitude}` +
  `&lang=ru` +
  `&apiKey=YOUR_API_KEY`;

fetch(url)
  .then(response => response.json())
  .then(data => {
    console.log(data.items[0]);
  });

Результат может содержать:

{
  "city": "Лондон",
  "countryName": "Великобритания"
}

Для английской локали:

{
  "city": "London",
  "countryName": "United Kingdom"
}

Локализация автодополнения

Autocomplete API также поддерживает языковые настройки.

Пример:

async function autocomplete(query) {
  const response = await fetch(
    `https://autocomplete.search.hereapi.com/v1/autocomplete` +
    `?q=${encodeURIComponent(query)}` +
    `&lang=ru` +
    `&apiKey=YOUR_API_KEY`
  );

  return response.json();
}

Поиск:

autocomplete('мос');

Может вернуть:

[
  {
    "title": "Москва"
  }
]

Для английской локали:

[
  {
    "title": "Moscow"
  }
]

Локализация маршрутов

Routing API поддерживает локализованные инструкции движения.

Пример:

const url =
  'https://router.hereapi.com/v8/routes' +
  '?transportMode=car' +
  '&origin=55.7558,37.6173' +
  '&destination=55.7512,37.6184' +
  '&return=summary,actions' +
  '&lang=ru' +
  '&apiKey=YOUR_API_KEY';

Фрагмент ответа:

{
  "instruction": "Поверните направо на Тверскую улицу"
}

При использовании английского языка:

{
  "instruction": "Turn right onto Tverskaya Street"
}

Это особенно важно для навигационных приложений и голосовых помощников.

Автоматический выбор языка браузера

Распространённый подход — определение языка пользователя через браузер.

const browserLanguage = navigator.language;

console.log(browserLanguage);

Примеры значений:

ru-RU
en-US
de-DE
fr-FR

Получение базового языка:

const language =
  navigator.language.split('-')[0];

console.log(language);

Результат:

ru

Использование:

const url =
  `https://geocode.search.hereapi.com/v1/geocode` +
  `?q=Berlin` +
  `&lang=${language}` +
  `&apiKey=YOUR_API_KEY`;

Смена локали во время работы приложения

В многоязычных приложениях язык может переключаться динамически.

Пример:

let currentLanguage = 'ru';

function setLanguage(lang) {
  currentLanguage = lang;
}

Использование:

setLanguage('en');

Запросы автоматически используют выбранную локаль:

async function search(query) {
  const response = await fetch(
    `https://discover.search.hereapi.com/v1/discover` +
    `?q=${encodeURIComponent(query)}` +
    `&at=55.7558,37.6173` +
    `&lang=${currentLanguage}` +
    `&apiKey=YOUR_API_KEY`
  );

  return response.json();
}

Локализация элементов интерфейса карты

Сам объект карты отображает географические данные независимо от языка интерфейса приложения.

Для локализации элементов управления используется параметр языка при создании платформы.

const platform = new H.service.Platform({
  apikey: 'YOUR_API_KEY',
  language: 'ru'
});

Создание стандартных элементов управления:

const ui = H.ui.UI.createDefault(
  map,
  defaultLayers,
  'ru-RU'
);

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

Использование региональных настроек

Язык и регион — разные понятия.

Например:

en-US
en-GB
fr-FR
fr-CA
pt-BR
pt-PT

Одинаковый язык может иметь различные:

  • правила написания адресов;
  • единицы измерения;
  • форматы времени;
  • дорожные обозначения.

Пример:

const locale = 'en-GB';

const ui = H.ui.UI.createDefault(
  map,
  defaultLayers,
  locale
);

Работа с многоязычными объектами

Многие объекты HERE содержат несколько вариантов названий.

Например:

{
  "title": "Москва",
  "address": {
    "city": "Москва"
  }
}

или:

{
  "title": "Moscow",
  "address": {
    "city": "Moscow"
  }
}

Выбор конкретного варианта происходит автоматически на основании параметра локализации.

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

Часто язык сохраняется между сессиями.

Пример через Local Storage:

function saveLanguage(lang) {
  localStorage.setItem('language', lang);
}

Чтение:

function loadLanguage() {
  return localStorage.getItem('language') || 'en';
}

Использование:

const currentLanguage = loadLanguage();

Изменение:

saveLanguage('ru');

Локализация результатов поиска рядом с пользователем

Поиск ближайших объектов:

async function searchNearby() {
  const response = await fetch(
    'https://discover.search.hereapi.com/v1/discover' +
    '?q=hotel' +
    '&at=41.9028,12.4964' +
    '&lang=it' +
    '&apiKey=YOUR_API_KEY'
  );

  return response.json();
}

Ответ будет содержать:

{
  "title": "Hotel Roma"
}

а адресные данные будут возвращены на итальянском языке.

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

Не все объекты имеют локализованные версии.

Практикой считается организация запасного языка.

const preferredLanguage = 'kk';
const fallbackLanguage = 'en';

Функция получения данных:

async function fetchLocalized(url) {
  try {
    const response = await fetch(
      `${url}&lang=${preferredLanguage}`
    );

    return await response.json();
  }
  catch {
    const response = await fetch(
      `${url}&lang=${fallbackLanguage}`
    );

    return await response.json();
  }
}

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

Особенности локализации международных адресов

При работе с международными адресами необходимо учитывать несколько особенностей:

  • не все страны имеют полный набор переводов;
  • исторические названия могут отображаться в оригинале;
  • названия улиц часто сохраняются без перевода;
  • коммерческие объекты обычно используют оригинальный бренд.

Например:

{
  "street": "Champs-Élysées",
  "city": "Париж",
  "countryName": "Франция"
}

Город и страна локализованы, а название улицы осталось в оригинальном виде.

Практические рекомендации

Использовать язык пользователя по умолчанию

const lang =
  navigator.language.split('-')[0];

Сохранять выбранную локаль

localStorage.setItem('language', lang);

Передавать параметр lang во все поисковые запросы

&lang=ru

Локализовать инструкции маршрутов

&lang=ru

Использовать региональные идентификаторы для интерфейса

ru-RU
en-US
de-DE

Предусматривать резервный язык

en

Не рассчитывать на перевод собственных названий объектов

Многие компании, гостиницы, рестораны и достопримечательности сохраняют оригинальное написание независимо от выбранной локали, что является нормальным поведением сервисов HERE Maps API.

Оглавление