Capturing Javascript Content

It may be that not all translatable content on your site is delivered as plain HTML, especially for more complicated or dynamic sites. You may also have content delivered in JavaScript.

By default, Smartling doesn’t capture JavaScript content, in order not to disrupt the functionality of your site. To translate this content, you need to explicitly mark the content that you want to be translated. You can do this by using inserting Smartling directives as JavaScript comments. Wherever possible, consider externalizing your strings in separate files to make them easier to identify and translate.

Note that you may need a few tweaks to optimize your JavaScript for localization. The most important of these is to remove any string concatenation.

JavaScript Directives

Translate / Notranslate

<sl:translate> and <sl:notranslate> can be used to mark content to translate and not translate.

<sl:notranslate> tags can be nested inside <sl:translate> tags so you can mark a large block for translation, but single out select strings you don’t want translated. However, <sl:translate> tags cannot be nested inside <sl:notranslate> tags.

// Translate some Strings

// <sl:translate>
	var string 1 = 'Translate this string';
	var string 2 = 'And this string';
	var string 3 - 'And this string, too.'
// </sl:translate>

// Nest a notranslate block inside of a larger translate block

// <sl:translate>
	var string 1 = 'Translate this string';
	//<sl:notranslate>
		var string 2 = 'But not this string';
	//</sl:notranslate>
	var string 3 - 'Translate this string, too.'
// </sl:translate>

Translate HTML

Often HTML can be stored inside a Javascript string literal. To capture this content, you need to let Smartling know to parse the content as HTML so that block level tags can be captured as individual strings instead of capturing one large string for all content within the literal. Do this with the <sl:translate_html> tag. Here’s an example adding HTML to the DOM with jQuery.

JavaScript

$("#addUser").click(function{} {
 var username = $("#inputUsername").val();
 var role = $("inputRole").val();
 //<sl:translate_html>
 var template = '<p>New user has been added.<ul><li>Username: </li><li>role:</li></ul></p>'
 //</sl:translate_html>
 var message = Mustache.render(template, {username: username, role: role})
 ('#Messages').append(message);
});

Smartling captures the following strings from this example:

• ‘New user has been added.’
• ‘Username: {0}’
• ‘Role: {0}’

Avoid Concatenation

String concatenation is common in JavaScript, especially when handling variables, but it creates problems for localization and must be avoided in translatable content. Consider the following example:

var item = {...}
// <sl:translate>
var checkoutStatus = 'You added a ' + item.color + ' ' + item.type + ' to your cart.'
// </sl:translate>
Smartling captures each JavaScript string literal as a translatable string, so your translators will see three separate strings:

• ‘You added a ‘
• ‘ ‘
• ‘ to your cart’.

The variables will not be captured.

Apart from it being difficult for the translator to understand and translate these three strings in isolation, it is impossible for the translator to change the position of the variables to allow for non-English sentence structure.

A much more localization-friendly way to handle the same content is by using a simple templating engine like mustache.js or by extending the String class with a supplant method. Here’s an example using moustache:

<script type="text/javascript" src="/js/mustache.min.js"></script>
<script>
	var item = {...};
	// <sl:translate>
	var checkoutStatus = 'You added a {{item.color}} {{item.type}} to your cart.';
	// </sl:translate>
	var checkoutStatus = Mustache.render(checkoutStatus, item);
</script>

Minification

If you need to minify your JavaScript for faster delivery, comments won’t work for you, as they are usually stripped out by minifiers. As an alternative, you can use functions. Once you have your functions set up, you can use them exactly like comment directives. To use function names as directives in JavaScript for minification, add this to the top of your script.

 Javascript

// Declare an empty function
function sl_translate() {}

// Add as many of the following directives as you need, each calling the empty function
sl_tr_start = sl_translate;
sl_tr_end = sl_translate;
sl_notr_start = sl_translate;
sl_notr_end = sl_translate;
sl_tr_html_start = sl_translate;
sl_tr_html_end = sl_translate;
sl_tr_json_start = sl_translate;
sl_tr_json_end = sl_translate;

Using this syntax will ensure that the directive names survive minification intact.
You can then use your functions exactly the same way we use the comment directives above.
The functions don’t actually do anything in JavaScript, they only affect the Smartling parser.

JSON

Certain JSON key/value pairs may be required to remain in their source language to preserve the functionality of your site, and for this reason, Smartling does not automatically capture JSON content for translation. Instead, you need to identify where in your JSON the specific values to be translated are located.

Identify Translatable Content

Indicating what JSON values you need to be translated is as simple as creating a new key/value pair using our custom "sl_translate" key. To tell Smartling what to translate, you need to create an "sl_translate" entry at the top of your JSON object.

This key can have three values:

• "sl_all" - All values are translated.
• "sl_none" - No values are translated.
• Comma-separated list of JSON keys to identify that their values should be translated.

The examples below consider the three types of supported key/value pairs.

Using "sl_all"

{
"sl_translate": "sl_all",
"status": 200,
"messages": "The request was successful",
"user": {
    "firstName": "John",
    "role": "Editor",
    "admin": false
},
"string1": "Here's some content for John to translate.",
"string2": "<div>Smartling automatically recognizes HTML in a JSON string.</div>",
"string3": "This is an additional string from your site."
}

/* <sl:translate_json> */

/* </sl:translate_json> */

jquery
jquery.min.js
jquery.ui.js
prototype.js
yui
ext
ally
ample
artisan
blackbird
cappuccino
datejs
dhtmlx
dojo
puremvc
mootools
echo
flot
fuel
glow
closure-library
himle
jelly
joose
jwee
jsdraw2d
knockout
midori
mochikit
plotkit
pottisjs
processing.js
qooxdoo
rico
script.aculo.us
smartclient
soundmanager
spark
sproutcore
spry
sylvester
swfobject
taffydb
typeface.js
underscore.js
zwt
zreshk