Standard behavior
Smartling automatically extracts strings from most localization resource files without any special direction. This includes extracting the translatable string, formatting it, and 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. Many file types also support some form of comments or instructions. Smartling will capture these as 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, XLIFF files, and others.
The main exception is custom XML documents. If they are not in Android or XLIFF format, you must provide Smartling with specific directions on how to read them. These directions are contained in file directives.
Customization via directives
For almost all formats you can provide direction on how to change the standard parsing behavior as well as how to capture additional metadata that is not included 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 include directives in the file.
With the right directives, Smartling will only capture translatable values as string, correctly assign the "keys", and even capture translator instructions.
How to Apply Directives
You can provide directives for processing the files a few different ways:
- Inline within the file itself, usually as "comments" or similar markup
- 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.
- Via API parameters
- API directives control how all strings in the file will be captured.
- Via "templates"* that will be available to users in the web dashboard when dragging and dropping files
- Like API directives, templates affect the entire file. But templates cannot be used by the API. API users must specify directives directly.
* Templates must be configured for your Account by Smartling. Please contact your Customer Success Manager for more information.
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 translated 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 unsure 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 if 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 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.
If you are uncertain if your strings should be processed as HTML, please contact your Smartling representative for guidance and best practices.
Other directives
The following is a list of some 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.
Directive name | Description |
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 JSON, XML and YAML files. |
*** translate_paths is REQUIRED for custom XML files
For more information on directives, please see the article specific to that file type.
Localizing Templated Applications
Many modern web stacks use HTML-like templates to compile a browser view. This can happen on the server or client side. HTML-like template styles include Angular, Backbone, Ember, Blaze, Handlebars, EJS, etc. Because these files look a lot like HTML, and sometimes even have a .html extension, you may want to upload them to Smartling as HTML files and try to translate them. However, Smartling does not support parsing HTML-like templates as HTML files.
If you are localizing a templated application, the best practice is to externalize ALL strings into a supported resource file and translate that resource file, rather than translating the template. Libraries are available for most web platforms to pass strings to your templating engine in the correct language, according to client IP address or the user’s stated preference. This is optimal both for translation with Smartling and for performance and scalability of your localized app.