Smartling Core Concepts of Translation

Standard and Customized Behavior for Localization Resource Files

Standard behavior

Smartling will automatically extract strings from almost all standard localization resource files without any special direction. This includes extracting the translatable string and formatting it, as well as capturing metadata about it. For most file formats that use a 'name' and 'value' structure Smartling will extract the value as a string for translation and the name (key) as metadata. In numerous file formats, Smartling will also capture translation instructions for the translators.

The string to translate and the 'key' metadata are automatically captured from most formats including YAML, iOS, Java Properties, JSON, Gettext, some "XML" formats such as Android XML, and XLIFF files, and other file formats. The main exception to this is a custom XML documents. Users must provide Smartling with specific directions on how to process XML files if they are not Android or XLIFF format.

Customization via directives

For almost all formats you can provide direction on how to change the standard default behavior as well as how to capture additional metadata that is not captured automatically. These directions are called "directives".

Without directives, for example, all the values in a JSON file will be captured as strings for translation. However many JSON files contain values that are metadata that shouldn't be captured as strings for translation. Rather than excluding all these untranslatable strings after uploading the file you can instead integrate the file with directives. With the right directives Smartling will only capture translatable values as string,  correctly assign the "keys", and even capture translator instructions.

You can provide directives for processing the files a few different ways:

  1. In the file itself, usually as "comments" or similar markup
    1. Most users apply the directives to the entire file; and some file formats only allow directives to apply to the whole file. Sometimes, however, you can target directives to specific strings within a file.
  2. Via API parameters
    1. API directives control how all strings in the file will be captured.
  3. Via "templates"* that will be available to users in the web dashboard when dragging and dropping files 
    1. Like API directives, templates affect the entire file. But templates cannot be used by the API. API users must specify directives directly.

Most directives apply to the original source language file and affect how Smartling captures strings and their metadata.

Some directives can only be used when you are downloading translations; they affect the the downloaded translation file; how to format the file and the translation strings.

Variables in formatted strings (placeholders) 

Placeholders represent the syntax in strings that will be formatted by your application with variables at runtime. The following are examples of strings with placeholders:

This document belongs to {{ownerName}}
This document belongs to %s
This document belongs to %@
This document belongs to {0}
This document belongs to ${ownerName}

It is a best practice to protect this part of your string as placeholders so that the translators do not need to enter the special syntax. This ensures that they do not accidentally break your application because of a poorly formatted string. By properly specifying the placeholder you also get the benefit that our standard quality checks can help make sure the placeholders are present in the translation - as omitting the placeholder could also cause problems with your application at build or run time.

Before you provide a placeholder directive check the documentation for the file type (or upload the file) to see if Smartling handles it already. Additional details are in the Placeholders in Resource Files article. Smartling has directives for both common formats specified by name and for custom placeholders specified via a regular expression.

Tags for markup (or markdown) are not placeholders

Smartling automatically handles HTML markup (and markdown for some file formats). For most cases you should not try to use placeholder directives for formatting tags. If formatting tags are not handled the way you would like, Smartling has some directives that can help customize the tag handling behavior.  

If you are not sure how to configure Smartling to handle your document or are considering using a directive to turn some kind of formatting tag into placeholders, please contact your Smartling CSM or Support for guidance and best practices.

HTML processing

Sometimes your resource file has strings with HTML tags. Usually the default behavior provides the best user experience for content owners and translators. Sometimes, however, it is better to process the string as an HTML document; even though it is stored in a resource file**.

For example, if your string has inline tags such as <a> or <span> or styling tags like <strong> or <em> the default behavior by Smartling should be fine; in fact turning HTML on won't really affect strings that don't have block level tags.  If your string has multiple block level tags such as many <p> or <div> tag pairs, in other words f it is basically an entire "document" contained as a value in your resource file, HTML processing of the strings, via a directive, might be appropriate.

If you are not sure if your strings should be processed as HTML please contact your Smartling CSM or Support for guidance and best practices.

Other directives

The following is a partial list of the kinds of directives that are available in different file formats. For a comprehensive list please check the documentation for the specific file format you will be uploading to Smartling, as not all directives are available for all formats.

placeholder_format Common placeholder formats by name like "C" or "Java"
placeholder_format_custom Custom placeholder via a regular expression
sltrans Smartling formatting markup used to exclude parts of a document from being captured and translated
translate_paths Path to find translatable strings in JSON and XML*** documents.
entity_escaping HTML entity character handling
download_format Unicode escaping behavior for JAVA and YAML
string_format_paths HTML document processing inside of JSON, XML and YAML files.
For other directives please see the article specific to that file type


* Templates must be configured for your Account by Smartling. Please contact your CSM or Smartling Support.

** If you process your strings as HTML, you will not be able to import existing translations into Smartling. Importing is usually a one time process completed when you onboard your content into Smartling. If you are planning to import your pre-existing translations at the time of onboarding, but also have HTML documents in those resource files your Smartling CSM will advise you as to the best strategy.

*** translate_paths is REQUIRED for custom XML files

Was this article helpful?