JavaScript Context Capture Library

Most modern websites have dynamic or interactive elements in their design. These elements often control what content is shown to a user based on things like logged-in state, previous visits to the site, or what particular journey they took to get to a page. This makes it difficult to ensure that all translatable content for that website has good visual context for use during the translation and review process.

Smartling's JavaScript Context Capture Library allows you to capture the visual context of any dynamic website or application. It automatically triggers context captures as the visual (rendered) state of a page changes while a user browses your website.

Tip: 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 in 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, and Connectors or upload manually by dragging and dropping files into a project.

Configure the JS Library

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

Embedding the Library

JavaScript Embedding

This is the preferred method of embedding the Library. It works asynchronously and therefore does not block page loading.

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 JS Snippet</title>
    <!-- Initialize the SmartlingContextTracker -->
    <script>
        (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, "your-org-id-here");
    </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'
             });
     </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.

Parameter	Purpose	Valid Values
orgId	Smartling project to submit context to	Your Smartling orgID, found under Account Settings > API
host	API host name, defaults to api.smartling.com	valid host name
mode	Operation mode, defaults to `auto`	`auto` or `manual`
requestTimeout	Context submission request timeout, defaults to `2000`ms	positive number
snapshotSizeLimitBytes	If captured HTML page is larger than this number, submission will be skipped, defaults to `2Mb` in bytes	max `40mb` in bytes
instrumentationProcessingEnabled	Removes the invisible characters which may appear as squares in some browsers on Windows operating systems. If `true`, removes instrumentation marks and transforms HTML into WrappedHTML with `<smartling:edit />` tags, defaults to `false`.	`true` or `false`
overrideContextOlderThanDays	If specified, the submitted context will override any existing context for matched strings, which is older than the specified number of days	positive number
cleanupInputFields	Whether to clear form input fields before submitting context, defaults to `false`	`true` or `false`
domContentFilter	If specified, should be a function that returns its first parameter. The parameter passed is the cloned DOM, which can be manipulated and filtered, if needed.	Function `(HTMLElement) => HTMLElement`
calculateHashsumsSignatureDisabled	If `true`, JS Library stops calculating page signatures, potentially increasing traffic for similar pages, defaults to `false`	`true` or `false`
resourceFetchLimit	The number of missing resources to upload after the context is submitted.	values 1 - 100 defaults to 1.
traverseElementsLimit	The context submission is skipped if number of elements to process on the page is greater than this value.	values 0 - 50,000 defaults to 20,000
childElementsLimit	The context submission is skipped if any DOM element has more children than this value.	values 0 - 10,000 defaults to 2,000.

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

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).

Limit Source Domains for Context

In some scenarios, you may want to limit the domains where the JS Context Library can function and generate context snapshots. For example, you may want to generate context from a UAT (user acceptance testing) environment but not a development environment.

You can restrict the domains used to generate context by navigating to your project settings and entering the Context page (Settings > Contexts).

Within that page, you can change the mode of the JS Context Library. The two options are:

All domains except banned ones
- In this mode, the library captures context on all domains unless you specify domains for which it will not generate context.
Only specific domains
- This mode turns off the JS Context Library until you specify some allowed domains. Those allowed domains are the only domains where the library will capture context.

Tip: Note that changes to these settings can take up to 30 minutes to propagate and be applied.

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.
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 builtin page mutation events and throttling
the event handlers with the corresponding interval. All event processing is nonblocking
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.

Hey! Hoi! ¡Oye! Ciao ! 你好! Hallo! Salut ! Hey! How can we help?