Improve Context Matching With Instrumented Files

What is an Instrumented File?

Instrumented files are a modified version of the original source file, used to improve the speed and accuracy of matching strings to HTML context. When you download the instrumented version of a file, Smartling appends a character to the end of each string in the source file that maps to a unique Smartling string hashcode. 

Example Source File

 

Example Instrumented Source File

 

The appended characters are only visible in development applications. Typically, for the end user, these instrumented strings will look the same. However, in some cases, the character may bleed through. For this reason, we recommend using instrumented files in non-production environments only.

Smartling's automated matching process uses these invisible characters to match source strings exactly with their equivalent strings in a Smartling Project.

Advantages to Using Instrumented Files

When your HTML context file contains regular strings, the automated matching process cross-references the text in the HTML context file with the text of each string in your Smartling project (unless you are using a Connector or direct API). With instrumented context files, Smartling uses the invisible appended character to match hashcode to hashcode instead, which improves both accuracy and speed.

Matching accuracy 

Without instrumented files, Smartling strings will match with all strings in the HTML context file that have the same text. For example, if you have the string “Orange” to describe the color of a product and the string “Orange” to describe the fruit-themed pattern of a product, each source strings will match with both strings in context.

Example of context matching without Instrumented Files

 

However, if the HTML context is generated with an instrumented file, Smartling matches the strings based on the specific hashcode for each string. This means each source string will only match with the correct string in context.

 

Example of context matching with Instrumented Files

 

Matching speed

It takes a long time for the matching process to look at the text for every single string in the project to see if it can find a full or partial match, especially with projects with tens of thousands of strings. With instrumented files, Smartling only has to match that invisible character that maps to the string hashcode to the correct hashcode, which is a much faster operation.

How to use instrumented files

Step 1: Get an Instrumented version of your source file

To get an instrumented file, you first need to upload the source file to Smartling, then download the instrumented version of the file from Smartling.

This can be achieved manually in the Smartling dashboard, or via the API, but we recommend the API to keep files in sync

Manual 

1. In your Smartling project, go to the Files tab
2. Click Upload File 
3. Once uploaded, the file will be listed in the Files tab
4. Click the ellipses (3 dots) in the top-right corner of the tile
5. Click Download instrumented file

API

1. Use upload file endpoint to upload file
2. Use download translated file endpoint to download the instrumented file with the retrievalType property set to contextMatchingInstrumented.

Step 2: Generate your HTML Using Instrumented Files

Replace your source file with its instrumented version in whatever environment you plan to generate context from. You can use an “instrumented” locale in your codebase, or just replace the default source language.

Step 3: Capture Context

Once your HTML page includes strings from your instrumented file, you can send the context to Smartling using one of the following methods:

• Context JS library
• Context Capture Chrome extension
• API integration

Instrumented files also improve the speed and accuracy of matching for the In Site Review Tool.

Smartling’s automatic matching process will match each source string to its corresponding string in your HTML context. 

If the context matcher detects instrumented strings, it will only match with instrumented strings. Any regular strings present in the HTML context file will not match.

Whenever strings are added to a source file, re-upload the file to generate Smartling hashcodes for new strings and download its instrumented version to update.

Considerations

• Instrumented strings only work for HTML context.
• Some devices and browsers may show the invisible hashcode character as a missing character or rectangle with a question mark. Please test accordingly before publishing content with instrumented files.

• Depending on the font, tech stack and other development factors, there's a chance the "invisible" characters used for instrumented files are actually visible. For this reason, we recommend using instrumented files in non-production environments only.