We've launched a new support center at help.smartling.com. This site will continue to be maintained into January 2017. Please update your bookmarks.
Follow

Smartling Global Delivery Network Content Coding Requirements

The following article applies to Global Delivery Network project types. 

The Smartling Global Delivery Network (GDN) supports standard technologies used across the Internet - HTML, JavaScript, JSON, HTML, and XML along with various encodings, escapings, and embedding of content types. The GDN will not be able to collect your source language content unless your website’s HTTP response content is valid and follows accepted web standards and other instructions in this documentation.

Smartling requires markup code elements to be properly balanced (well-formed). If the code is not properly balanced, it may not render properly or Smartling may attempt to balance the code by, for example, introducing additional closing tags.

Responsibility for well-formed code rests with you; Smartling is not responsible for errors caused by code that does not meet the requirements.

HTML Requirements

All elements of an HTML document must be well-formed. Each element is either:

  • Opened and subsequently closed
  • An empty element, which must be self-closed, or have a closing tag
  • Properly nested so that tags do not overlap - for example, block tags are not nested inside inline tags

For example, in HTML: <strong>word</strong> is a well-formed element, while <em><strong>word</em> is not, since the bold element is not closed. Additional examples:

Valid: <em><strong>word</strong></em>
Valid: Single sets of <html>, <head>, and <body> tags

Invalid: <em><strong>word</em></strong>
Invalid: Multiple or overlapping <html>, <head>, or <body> tags

If a document has malformed HTML, then the Smartling GDN may attempt to correct the HTML which in some cases could cause the page to not render as expected or at all.

In order to translate inline on a site using the Smartling contextual translation tools, <html> and <head> tags are required.

Smartling tag attribute values (such as notranslate, SL_split, or SL_hide) integrated with your HTML are case sensitive and must appear exactly as documented.

The head of each source HTML file should include a UTF declaration, for example:

<meta charset="UTF-8">

Templating:

Be careful not to enclose half of a tag pair inside template logic. For example:

<%if isSomething %> <span>Some text about true <%else>
 <span>Some text about false<%endif> </span>

Instead either keep both opening and closing tags inside the conditional, or leave them outside. Like:

<span><%if isSomething%> Some text about true <%else> Some text about false<%endif> </span>

 

Block Tags:

Smartling uses block tags to separate text into individual strings. Ideally, paragraphs of text should be enclosed in <p></p> tags. Excessive use of <br/> or using </p> as a standalone tag may display adequately in a browser but can cause the following issues:

  • All text in a section may be created as one very long string in the Smarting Dashboard.

  • Translated sites may display without line breaks.

Correct:

<p>A paragraph.</p>
<p>Another paragraph</p>

Incorrect:

A paragraph. <br/>
Another paragraph.

A paragraph </p>
Another paragraph.

HTML content can be validated using the W3C Validator Service: http://validator.w3.org/. This service is far more strict than Smartling, but can provide guidance when tags and code do not match.

XML Requirements

You can validate XML data at http://www.xmlvalidation.com/.

Smartling offers various methods of tagging content in XML for translation. In some cases, tagging content may be required. Smartling Client Services can recommend the best approach for translating XML content.

XML follows the same rules as HTML parsing.

JSON Requirements

Smartling parses JSON values and in most cases automatically detects JSON. JSON must follow the JSON specification, including:

  • Keys and values must be enclosed in double quotes
  • Translatable content must not be in keys

You can validate JSON data at http://jsonlint.com. If JSON data doesn't pass this test then Smartling won't consider it valid JSON.

Smartling offers various methods of tagging content in JSON for translation. In some cases, tagging content may be required. Smartling Client Services can recommend the best approach for translating JSON content.

Javascript Requirements

Smartling parses Javascript string literals for translatable content. Content should be properly escaped and encoded. For example:

Valid: var string1='Jack said, "Jack and Jill went up the hill"';
Valid
: var string1="Jack said, \"Jack and Jill went up the hill\"";
Valid
: var string1='Jack said, \'Jack and Jill went up the hill\'';

Invalid: var string1="Jack said, "Jack and Jill went up the hill"";
Invalid
: var string1='Jack said, 'Jack and Jill went up the hill'';

Smartling offers various methods to explicitly tag Javascript content for translation. In some cases, tagging content may be required, in particular if the Javascript contains quoted strings that should not be translated. Smartling Client Services can recommend the best approach to translating Javascript content.

As a best practice, you should never concatenate strings in Javascript with other strings. It is important to provide complete linguistic units for translation, not partial sentences to be concatenated client-side. While this is not a technical limitation, concatenating phrases according to the rules of one language may produce poor quality translations when the translated phrases are concatenated in the same manner.

You can validate Javascript content using JSLint: http://www.jslint.com/

HTTP Response Content-Type Requirements

Smartling uses the Content-Type on HTTP responses as the first indication of how to parse content. The Content-Type should match the type of content in the response. Smartling supports standard Content-Types as well as several deprecated and temporary Content-Types. The following are valid Content-Types (bold indicates the latest accepted standard value):

 

Content Type Valid Content -Type Header Values
HTML, XHTML text/html, application/xhtml+xml
Text text/plain
Javascript application/javascript, text/javascript, application/x-javascript
JSON application/json, text/json, text/x-json
XML application/xml, text/xml
.Net UpdatePanels text/plain

Smartling can override incorrect Content-Types with correct Content-Types through configuration performed by Smartling Client Services.

Invalid: A site makes an AJAX call and the response contains JSON data. The Content-Type on the response is text/html. Smartling will try to parse the JSON content as HTML which will produce invalid data.

Valid: A site makes an AJAX call and the response contains JSON data. The Content-Type on the response is application/json. Smartling will parse the content as JSON.

Minified Javascript Support

Depending on how Javascript is parsed for translation, translated strings may need to be separated from combined or minified Javascript files.

Encodings and Escapings Support

Smartling auto-detects various encoding and escaping schemes in content. The following are examples of (incomplete) encoding - refer to the respective specification for details:

Encoding Scheme Example Encoding
HTML Entity '&'<=>"&amp;"
'<'<=>"&lt;"
'>'<=>"&gt;"
""<=>"&quot;"
XML Entity ""<=>"&#34;"
'&'<=>"&#38;"
'<'<=>"&#60;"
'>'<=>"&#62;"
Unicode "\u003e" <=> "<"
New Line '\n' <=> "\\n"

These are the four encoding and escaping schemes supported by Smartling. If translatable content exists that contains an unsupported Encoding or Escaping, the content may need to be converted to a supported scheme. Smartling Client Services can advise on how to handle non-standard Encoding or Escaping.

Embedded Content-Type Support

Smartling supports various types of content within types of content; for example, HTML within Javascript, HTML within JSON, or JSON within Javascript (JSONp). Smartling Client Services can recommend the best method to translate this content which may include moving translatable content to an external resource file.

Javascript Template Support

Smartling provides limited support for Javascript templating including jQuery Templates and Mustache templates. Smartling Client Services can recommend the best method to translate content in Javascript Templates which may include moving translatable content to an external resource file.

.Net UpdatePanel Support

Smartling provides for limited support of .Net UpdatePanel content. This includes auto-detecting UpdatePanel content based on Content-Type and content structure (pipe-delimited) and modifying character counts in content for client side processing. There may be limitations based on .Net framework version, future updates to .Net, and changes in UpdatePanel content structure. Smartling Client Services can recommend the best method to translate content in .Net UpdatePanels.

Validation Resources

You can use the following online tools to validate code and check for quality:

W3C Validator: http://validator.w3.org/
JSONLint: http://www.jsonlint.com
JSLint: http://www.jslint.com/
XML Validator: http://www.xmlvalidation.com/

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request
Powered by Zendesk