Translator Library

Translator Libary gives you the ability to translate any data representation to any other data representation, all driven by a declarative configuration-driven file.

An example would be to take a complex representation of, say, MICA services payload and translate it to your own representation of a service payload.

This can be used to create a "common language" across variety of different data representations - such as service or a product - that are inherently represented differently in their source systems.

The Translator can be used in variety of different scenarios. The above scenario aims to query service data from N number of systems, and rationalize it to a common representation.

Usage

Install the dependency

First step is to include our library as part of your dependencies defined in the package.json file.

{
    ...
    ...
    "dependencies": {
        "translator": "git+https://[email protected]/scm/hpse-eng/translator.git"
    }
    ...
    ...
}

Or you can also do

# npm install https://[email protected]/scm/hpse-eng/translator.git

Understanding the data

You then need to understand the source data you're working with. An example of this would be the original weather data structure (below):

[
    {
        title: "Melbourne",
        location_type: "City",
        woeid: 1103816,
        latt_long: "-37.817532,144.967148"
    }
]

YML Config File

After you've understood what your source system data representation is, then you can begin to define your translation config, which ultimately drives the translation process from one representation to another. Name the file translator.weather.yml.

translator: translator.weather
description: Weather Translator

maps:
  root:
    list: 'cities'
    item:
      cityName: 'title'
      lng: 'latt_long'
      lat: 'latt_long'
    operate:
      -
        run: extractLng
        on: 'lng'
      - 
        run: extractLat
        on: 'lat'

JS Custom Functions File

After you've understood what your source system data representation is, you need to understand if there are any custom translation functions you may need to write. In the weather example, the latt_lng attribute is holding the latitutde and longitude in a string, separated by a comma. We create two custom functions extractLng and extractLat and expose them via translator.weather.js custom file, which will be dynamically loaded when we load the config.

In the above section YML Config File, you can notice the extractLng and extractLat functions in the operate section under run.

module.exports = function () {

    let extractLng = function (val, context) {
        console.log(val);
        console.log(context);
        return val.split(',')[0];
    }

    let extractLat = function (val) {
        return val.split(',')[1];
    }    

    return {
        extractLng,
        extractLat
    }
}

Putting it all together

In this example, we will query a weather API endpoint, and translate the payload to our own representation.

let request = require('request');
let path = require('path');

let Translator = require('../index').Translator;

let weatherTranslator = new Translator(
    path.join(__dirname, 'translator.weather.yml')
);

request({
    url: 'https://www.metaweather.com/api/location/search/?query=melbourne',
    json: true
}, (error, response, body) => {
    if(error) {
        console.log(error);
        return;
    }
    console.log('\n\n--- ORIGINAL WEATHER DATA ---');
    console.log(body);

    let translationObject = {
        cities: body
    };

    let translatedObject = weatherTranslator.translate(translationObject);

    console.log('\n\n--- TRANSLATED WEATHER DATA ---');
    console.log(translatedObject);
});

Original Payload Output

[ 
    { 
        title: 'Melbourne',
        location_type: 'City',
        woeid: 1103816,
        latt_long: '-37.817532,144.967148' 
    } 
]

Translated Payload Output

[ 
    { 
        cityName: 'Melbourne', 
        lng: '-37.817532', 
        lat: '144.967148' 
    } 
]

Shout Outs

HPSE Transition Service Team