Translate view content

In HERE Core UI 45 or later, Browser can translate the text inside a view so users can read a page written in another language and stay in the same window. Translation uses Chromium's built-in Google Translate integration. HERE Core exposes that capability on fin.View and fin.Window, and Browser adds it to the view tab context menu.

Translation replaces the visible text in place, without reloading the page. The page keeps its layout and application state. Chrome's automatic translate prompt and address-bar translate control stay hidden. A page translates only when a user chooses the menu item or your code calls translatePage().

This feature translates web content inside a view. It does not translate PDFs or native UI. Menus, buttons, and tooltips in the Browser shell stay in the language configured for HERE Core UI. To localize those strings, see Provide localized strings for HERE Core UI Components.

Requirements

Requirement	Detail
Translation API key	A Google Translate API key must be configured on the machine. You supply your own key. HERE does not provide one.
Network access	The runtime must be able to reach Google Translate.

Without a configured key, getTranslationState() reports translationEnabled: false for every view, and Browser does not offer translation in the view tab menu.

info

Contact HERE Support for the runtime configuration that supplies your Google Translate API key.

Supported languages

Translation supports all languages supported by the Google Translate API.

Chromium detects the page language. The view tab menu offers translation whenever Chromium reports the page as translatable.

Translate from the view tab menu

Right-click a single view tab. Browser reads the view's translation state when the menu opens.

• Translate to language appears when the page can be translated and is not already translated. The target language comes from the runtime's UI locale. With an English UI, the item reads Translate to English.
• The translate item is not available when the page cannot be translated or while a translation is in progress.
• Revert Translation appears after the page is translated. Selecting it restores the original text in the same view.
• Translation items do not appear when more than one view is selected.

Developer API

fin.View and fin.Window expose the same translation methods and event. In Browser, call them on the view that contains the page.

Method or event	Purpose
getTranslationState()	Resolves to a WebContentTranslationInfo that describes the current language and translation state.
translatePage(options)	Translates the page in place. options is a PageTranslateOptions object with sourceLang and targetLang.
revertTranslation()	Restores the original page text. If the page is not translated, the call does nothing and resolves successfully.
translation-state-changed	Fires when translation state changes, such as when a foreign-language page is detected or a translation completes.

Translate options

Property	Type	Description
sourceLang	string	BCP-47 code of the source language, or an empty string to auto-detect.
targetLang	string	BCP-47 code of the target language, such as en.

If translation is unavailable, translatePage() does nothing and a translation-state-changed event is emitted.

Translation state

getTranslationState() returns one of two shapes, distinguished by translationEnabled.

When translationEnabled is false, the view cannot be translated. For example, no translation API key is configured, or the current page is not translatable. The object has no other properties.

When translationEnabled is true, the object includes:

Property	Type	Description
translationEnabled	true	Translation is supported on this view.
detectedLanguage	LanguageInfo or undefined	The detected page language. undefined until detection completes.
state	TranslationStatus	The current translation status, described below.

state.status is one of these values:

status	Meaning	Other properties on state
'untranslated'	The page shows its original text.	None
'pending-translation'	A translation is in progress.	sourceLanguage, targetLanguage
'translated'	The page shows translated text.	sourceLanguage, targetLanguage
'translation-failed'	The last translation attempt failed.	sourceLanguage, targetLanguage, errorMessage

LanguageInfo objects have a code (such as fr), an English display name in nameEn (such as French), and a localized display name in nameI18N (such as Français). errorMessage is a human-readable description of why the translation failed.

Detect the source language

Read detectedLanguage before you offer a custom translate action.

async function getViewLanguage(identity) {
  const view = fin.View.wrapSync(identity);
  const info = await view.getTranslationState();

  if (!info.translationEnabled || !info.detectedLanguage) {
    return { canTranslate: false };
  }

  const { status } = info.state;

  return {
    sourceLanguage: info.detectedLanguage.code,
    sourceLanguageName: info.detectedLanguage.nameEn,
    canTranslate:
      status === 'untranslated' || status === 'translation-failed'
  };
}

Translate a view from your own UI

Platform code can start translation from a custom toolbar button, a tab menu item, or other platform logic. Call translatePage() on the view that contains the page.

async function translateView(identity, targetLang = 'en') {
  const view = fin.View.wrapSync(identity);
  const info = await view.getTranslationState();

  if (
    !info.translationEnabled ||
    info.state.status === 'pending-translation' ||
    info.state.status === 'translated'
  ) {
    return;
  }

  await view.translatePage({ sourceLang: '', targetLang });
}

async function revertViewTranslation(identity) {
  const view = fin.View.wrapSync(identity);
  await view.revertTranslation();
}

For a toolbar button, add a custom Browser button and call translateView from its custom action with the identity of the view to translate.

Listen for translation state

The translation-state-changed event includes translationEnabled and the view's uuid and name. Call getTranslationState() in the handler to read the detected language and translation status.

async function watchTranslation(identity, onState) {
  const view = fin.View.wrapSync(identity);

  await view.on('translation-state-changed', async () => {
    onState(await view.getTranslationState());
  });

  onState(await view.getTranslationState());
}

To report a failure, check for state.status === 'translation-failed' and show state.errorMessage.