Clinical Office:MPage Edition

LanguageTranslationService V4+

Using the Google Cloud Translation API it is now possible to translate your MPage content in real-time in your Cerner MPages with the assistance of the LanguageTranslationService service. To start using LanguageTranslationService, ensure that you have signed up for a Google Cloud Translation API at cloud.google.com and have set up an API Key.

Below is a sample from a patient kiosk MPage shown in English, French and Arabic translated in real time.

Import

The LanguageTranslationService should be imported and initialized in the component source that is responsible for displaying data from the service. Alternatively, if you have your required payload information available, you can initialize the loading of your data in the app.component.ts source.

import { LanguageTranslationService } from '@clinicaloffice/clinical-office-mpage-core';

Initialization

The first step is to assign your API key and the Google HTTPS endpoints. At the time of this writing, the endpoint for translation is https://translate.googleapis.com/language/translate/v2 and to list languages https://translate.googleapis.com/language/translate/v2/languages?target=en

There are two acceptable methods for assigning your Google API key and the endpoints. The first is by assigning your values to the config.json file found in your assets folder of your project.

{
  "contextRoot": "http://xxxxx.cerncd.com/discern/xxxx.xxxx.cerncd.com/mpages/reports",
  "domain": [
    "b1234",
    "c1234",
    "p1234"
  ],
  "translate": {
    "endPoint": "https://translate.googleapis.com/language/translate/v2",
    "languageListEndPoint": "https://translate.googleapis.com/language/translate/v2/languages?target=en",
    "apiKey": "[YOUR SECRET API KEY FROM GOOGLE]"
      },
  "languageAlias": "IETF3066",
  "languageOutboundAlias": "ISO6392"
}

Notes:

If you omit the entry for languageListEndPoint, a value of /languages?target=en will be appended to the value you entered for endPoint. While this will work right now, if Google ever makes a change you may find yourself scrambling to add the languageListEndPoint value.
The endPoint and languageListEndPoint values have been made configurable to allow quick changes if Google makes updates in the future. The Google Translate API is currently at version 2, however a version 3 is in beta at this time.
Storing your API key in the config.json file should only be done if you have locked down your API key from the Google Cloud to only run from your domain. Shown below is a sample locking the API key to a fictitious hospital called myhospital.org.

The second method you can use is to store your API key either directly inside your MPage source code or in Cerner in the DM_INFO or custom table. You can then use the setApiKey method described below.

Language List

Once your API has been initialized, loading the available list of languages in the Google API is necessary to not only retrieve a list of available languages but to map them to Cerner language code values.

This is done by calling the loadLanguageList() method in your TypeScript code. This can be anywhere including your app.component.ts file. If everything is set up correctly you can run your MPage and see an entry called Language List in the MPage activity log.

When examining your language list you may notice that some languages cannot be matched to languages in Cerner. For the most part this is just an issue of the language not existing in Cerner however there have been instances where a language is spelled incorrectly in Cerner (e.g. Ukrainian != Ukranian). In these cases you can correct the spelling in Cerner or set up a CODE_VALUE_ALIAS or CODE_VALUE_OUTBOUND value for the missing language. You will need to make sure you specify the ALIAS name you wish to use along with the matching code (e.g. "as" = "Assamese").

{
  "translate": {
    "endPoint": "https://translate.googleapis.com/language/translate/v2",
    "languageListEndPoint": "https://translate.googleapis.com/language/translate/v2/languages?target=en",
    "apiKey": "[YOUR SECRET API KEY FROM GOOGLE]"
      },
  "languageAlias": "IETF3066",
  "languageOutboundAlias": "ISO6392"
}

Translation Cost Savings

The Google Translation API is priced per character making it important that you avoid translating anything that isn't necessary. To aid in saving you money, checks are made when you perform translations that avoid re-translating text for a specific id that has already been translated to a specified language.

For example, you may have the following translation queue that you pass to the translate() method.

[
    {id: 'gender', Text: 'Male'},
    {id: 'complaint', Text: 'Patient has a fever and feels unwell.'}
]

Once run the translations will be stored under the id names of 'gender' and 'complaint'. If you happen to run the same entries in another call, the translations will only occur for new values.

[
    {id: 'gender', Text: 'Male'},
    {id: 'dnr', Text: 'Yes'},
    {id: 'complaint', Text: 'Patient has a fever and feels unwell.'}
]

In the example above, the only translation that will occur is for the 'dnr' value since the text for 'gender' and 'complaint' have not changed.

Changing an existing value results in that translation being re-executed by Google.

[
    {id: 'gender', Text: 'Male'},
    {id: 'dnr', Text: 'No'}, <-- This will be translated again.
    {id: 'complaint', Text: 'Patient has a fever and feels unwell.'}
]

Methods

clear(key: string = ''): void
Clears a translation for a specific key or if an empty string is passed all translations will be cleared from memory.

get(key: string): ITranslation
Returns a specific ITranslation object based on a key id.

getLanguageByCodeValue(codeValue: number): ILanguageCode | undefined
Returns an ILanguageCode entry for the specified code value or undefined if not found.

isLoaded(key: string): boolean
Determines if a specific key id has been translated.

loadLanguageList(): void
Instructs your MPage to load the list of languages from Google Translate and to map them to Cerner language code values. The completion of this task assigns the languages public array.

putLog(message: string): void
Outputs the content of the message parameter to the activity log component.

setApiKey(apiKey: string, endPoint: string = 'https://translate.googleapis.com/language/translate/v2', languageListEndPoint: string = ''): void
Assigns a Google Translate API key as well as the endPoint URL and languageListEndPoint URL. If omitted, the endPoint and languageListEndPoint values will be assigned the values 'https://translate.googleapis.com/language/translate/v2' and 'https://translate.googleapis.com/language/translate/v2/languages?target=en'

translate(content: ITranslationQueue[], languageCode: string | number, toEnglish: boolean, callback: any | undefined = undefined): boolean
Performs the Google Translation of all content in the content parameter. Completed translations are stored in the translations Map contained in the service.

The content parameter must contain an array of valid ITranslationQueue objects containing both an id and Text value.

[
    {id: 'gender', Text: 'Male'},
    {id: 'complaint', Text: 'Patient has a fever and feels unwell.'}
]

The languageCode parameter identifies the non-English language you are translating to or from. This field accepts a valid language code string such as 'fr' or a Cerner code value number. Paired with the toEnglish boolean parameter the translation will either translate from or to English.

The callback parameter accepts either a custom function call or undefined. This callback will be executed upon the completion of the translation method. If you need to perform any tasks immediately after translation, this callback method is the place to do it.

Public Variables

LanguageTranslationService exposes the following variable that can be useful in the development of your MPages.

languages: ILanguageCode[] - Array containing all possible languages.
translations: Map<string, ITranslation> - Map containing all translations indexed by id.

Interfaces

ITranslationEndPoint

export interface ITranslationEndPoint {
  apiKey: string;
  endPoint: string;
  languageListEndPoint: string;
}

ILanguageCode

export interface ILanguageCode {
  codeValue: number;
  code: string;
  name: string;
  nativeName?: string;
}

ITranslation

export interface ITranslation {
  id: string;
  englishText: string;
  foreignText: string;
  languageCode: string;
}

ITranslationQueue

export interface ITranslationQueue {
  id: string;
  Text: string;
}

<< Prev: ErrorHandlerService

Next: mPageService >>