JavaScript Context Capture Library

If your website is interactive, with many variations of how pages can be viewed, meaning many variations to how your website's content can be viewed, it can be difficult to ensure that content has the right visual context for any given user journey. Smartling's JavaScript Context Capture Library allows you to capture visual context of any dynamic website or application.

Internet Explorer 11 and earlier versions are not supported.

How the JS Library Works

Smartling’s Context Capture Library is a JavaScript library, which can be embedded in a web page to automatically send HTML snapshots of the current page state to a Smartling project.

The library is triggered when a page is rendered in a browser and also as the page UI is updated from user interactions (the DOM changes). You will need to integrate and use it in an environment that is generating page requests and interactions. The library has been calibrated to minimize any impact on page performance. You can use it on your development, staging or production environment.

It is important to note that when it is implemented on your production environment, the HTML snapshots from your end-user sessions are sent to Smartling. This means a high volume of context could be generated and ingested in Smartling, and depending on what the end-user is doing on your site, it could include sensitive information, if applicable. All of which will be visible in the Context Dashboard and Context panel in the CAT Tool. For this reason, we recommend that you implement the library on a development or staging environment, so you can control what is ingested and visible in Smartling.

The unique Smartling Org Id will be visible to anyone who inspects your page.

The content you want to contextualize with the Context Capture JavaScript Library must exist in the Smartling platform before context can be associated with the strings using this tool.

You can submit content via Smartling's API, Global Delivery Network, Connectors, or upload manually by dragging and dropping files into a project.

Configure the JS Library

The library uses a unique your Smarting Organization Identifier (orgId) to upload context for your project. To locate your Smarting Organization Identifier (orgId), go to Account Settings > API

Configuration Options

orgId - organization ID, has a direct correlation to projectId.
host - API host for context and resources submissions, defaults to “api.smartling.com”.
mode - “auto” or “manual”, manual mode stops tracking DOM changes, defaults to “auto”.
resourceFetchLimit - number of missing resources to upload after the context is submitted, accepted values 1 - 100, defaults to 1.
snapshotSizeLimitBytes - context submission is skipped if resulting snapshot size is greater than this value, accepted values 0 - 10,000,000, defaults to 2,097,152.
traverseElementsLimit - context submission is skipped if number of elements to process on the page is greater than this value, accepted values 0 - 50,000, defaults to 20,000.
childElementsLimit - context submission is skipped if any DOM element has more children than this value, accepted values 0 - 10,000, defaults to 2,000.
instrumentationProcessingEnabled - if true, the library removes instrumentation markers from the page and any XMLHttpRequest submissions and inserts <smartling:edit /> tags with corresponding string hashcodes, effectively submitting wrapped HTML, providing bound context, defaults to false
calculateHashsumsSignatureDisabled - if true, similarity signature calculation will be disabled with the effect of increasing traffic, but considering every context submission, defaults to false.

Content Filter

contentFilter:
contentFilter: function (request, onSuccess, onError) {
        // do something with request.html and request.url;
        return onSuccess(request);
    }

Limitations: contentFilter function can't point to other functions. The whole filtering should be processed inside of it. contentFilter function is executing in browser's web worker and you need to consider these limitations (e.g., DOM processing is not available).

Embedding the Library

JavaScript Embedding

For a Single-Page Application or any other JavaScript-based page, use the following snippet to load the Context Capture Library:

JavaScript:

    (function (w, o) {
      try {
        var h = document.getElementsByTagName('head')[0];
        var s = document.createElement('script');
        s.type = 'text/javascript';
        s.async = 1;
        s.crossOrigin = 'anonymous';
        s.src = '//d2c7xlmseob604.cloudfront.net/tracker.min.js';
        s.onload = function () {
          w.SmartlingContextTracker.init({ orgId: o });
        };
        h.insertBefore(s, h.firstChild);
      } catch (ex) {
      }
    })(window, 'xbPHx3Meq7RDCMuPKxeb7w')

Here is a full HTML example:

<!DOCTYPE html>
<html lang="en">
<head>
     <meta charset="UTF-8">
     <title>Example HTML Snippet</title>
     <!-- Include script that creates SmartlingContextTracker object in global scope -->
     <script src="//d2c7xlmseob604.cloudfront.net/tracker.min.js"></script>
     <!-- Initialize the SmartlingContextTracker -->
     <script>
            SmartlingContextTracker.init({
                 orgId: 'your-orgID',
            });
     </script>
</head>
<body>
     <p>This is a content</p>
</body>
</html>

HTML Embedding

For an HTML-based page, just reference the script, and initialize the SmartlingContextTracker object:

JavaScript: 

<script type="text/javascript" src="//d2c7xlmseob604.cloudfront.net/tracker.min.js"></script>
<script>
           SmartlingContextTracker.init({
              orgId: 'your-orgId'
          });
</script>

Here is a full HTML example:

<!DOCTYPE html>
<html lang="en">
<head>
     <meta charset="UTF-8">
     <title>Example HTML Snippet</title>
     <!-- Include script that creates SmartlingContextTracker object in global scope -->
     <script src="//d2c7xlmseob604.cloudfront.net/tracker.min.js"></script>
     <!-- Initialize the SmartlingContextTracker -->
     <script>
             SmartlingContextTracker.init({
                 orgId: 'your-orgID',
                 host: 'api.smartling.com'
             });
     </script>
</head>
<body>
     <p>This is a content</p>
</body>
</html>

Parameter Reference

Context Capture Library can be configured for a variety of use cases through the use of additional parameters, specified in the initialization function.

SmartlingContextTracker.init({
      orgId: 'your-orgID', host: 'api.smartling.com', mode: 'manual | auto', requestTimeout: 5000, snapshotSizeLimitBytes: 5000000, resourceFetchLimit: 50, instrumentationProcessingEnabled: true, overrideContextOlderThanDays: 1, cleanupInputFields: true, domContentFilter: (dom) => { const inputs = dom.querySelectorAll("input"); inputs.forEach(input => input.value = ""); return dom; }, calculateHashsumsSignatureDisabled: false });

All parameters except orgId are optional.

contentFilter: function (request, onSuccess, onError) {
        // do something with request.html and request.url;
        return onSuccess(request);
    }

Limitations: contentFilter function can't point to other functions. The whole filtering should be processed inside of it. contentFilter function is executing in browser's web worker and you need to consider these limitations (e.g., DOM processing is not available).

Control the Library

The following methods can be used to temporarily enable/disable the library. Call them from
JS console or your code.

• SmartlingContextTracker.disable() - Disable capture indefinitely for current browser
• SmartlingContextTracker.enable() - Enable capture library again
• SmartlingContextTracker.init(options) Re-initialize the library using different options, see [parameter reference]
• SmartlingContextTracker.clearResourcesCache() - Remove any information about locally cached resourceIds
• SmartlingContextTracker.config() - Display configuration information
• SmartlingContextTracker.captureContext() - Trigger manual context capture (manual mode only)
• SmartlingContextTracker.version() - Display version information

Capturing Context

Once the library is embedded on your site, context will be uploaded to your Smartling project. The package has been carefully designed to minimize impact on page load times. 

Technical Information

Performance

The Context Capture Library is carefully designed to have the least possible
performance and memory impact on the page. Taking into account performance factors
such as page load, ui thread, upload bandwidth and DOM interaction, the library
implementation is carefully constructed to avoid any issues with performance or browser
support.

Page Load

The following steps were taken in order to make sure the script doesn't impact page
load times:

• Asynchronous loading Unless the page has older design pattern, where scripts are loaded sequentially via <script> tags (see HTML Embedding), the Context Capture library is loaded via a tiny snippet, which, in turn, loads the actual library asynchronously, without any impact on page loading time.
• Small footprint tracker.min.js is about 50k, smaller than most images.
• Fetch time The context capture library script is edge­cached on Amazon
• Cloudfront CDN, and takes under 20ms to fetch. This allows the browser to complete requests fast, without exhausting limited number of concurrent resource requests. tracker.min.js is served to your visitors from a system of strategically positioned servers around the globe, which offers both fast loading and better availability.

The Context Capture Library will not slow your page ­load time, and, if it becomes unavailable for any reason, it will not impact your page.

UI Thread Utilization

The browser's most precious resource is CPU time spent in the main UI thread. All
javascript is executed on this thread and any delay of between 50ms and 100ms will be
noticeable to the user. The Context Capture Library avoids these "hangs" by leveraging
user event processing in conjunction with built­in page mutation events and throttling
the event handlers with the corresponding interval. All event processing is non­blocking
and control from the Library is returned as fast as possible to the browser event loop.
The only CPU intensive task in the thread is updating the document elements that have
new or changed visible text. We clone the document structure and instrument cloned
elements with appropriate CSS classes, leaving original DOM intact. The HTML of the
cloned DOM tree is then sent toweb worker ­ a separate background thread running in
the browser.

DOM and Script interaction

The following identifiers are exposed to the global scope by the script: SmartlingContextTracker.

SmartlingContextTracker

The script also uses the slTranslate DOM node property as an expando to track nodes
that needs text content matched.

Resource extraction and upload

Pretty much any HTML document that is used to represent a web page will have a
number of associated resources (style sheets, images and fonts) linked to the document
content. Capturing these resources along with HTML content is essential for displaying
accurate context to translators.

We do our best to capture resources snapshots by processing the uploaded HTML
snapshot the following way:

• CSS stylesheets, images and font links are extracted from the HTML snapshot.
• Extracted links are rewritten to point to Smartling resource storage.
• Actual resources are captured and uploaded to Smartling resource storage.

This way we can ensure that the captured HTML context will look exactly as it looked at
the time it was captured, even if original style sheets, images or fonts no longer
available. Smartling uses several methods to fetch the resources, which cover most of
the use cases. Smartling will not be able to fetch protected resources that reside on different domain than the original page, unless CORS headers are properly configured for that domain.

• Publicly available resources that reside on the same domain as the original page.
• Protected resources (private network or firewalled) that reside on the same domain as the original page.
• Publicly available resources that reside on a different domain than the original page.