Custom XML

Extension .xml
Smartling identifier xml
Example File customxml.xml
Resources XML Standards

Smartling supports generic XML files by processing text within specified tags and attributes. You must specify the tags and attributes you want translated using the translate_paths directive


Key and Variant metadata must be enabled and configured using the source_key_paths and variants_enabled directives.

Specifying Paths

Some directives require you to specify a path or set of paths to keys or strings in the file. A path is a slash-separated string which uses an Xpath-like syntax (although not all features of Xpath are supported). The node separator is always / (slash).

Wildcards are not allowed in path definitions.

To specify an attribute, use dot notation: node.attribute.

To specify paths based on an attribute value, use the syntax /node[@attribute="value"].

For the translate_paths directive, ending the path with a trailing / (slash) will also translate all child nodes.

For example, in the following file:

<string name="home-button">Smartling Hotels</string>
<string name="back-button">Back</string>
<localize name="navigation">
<string>Browse Hotels</string>
<string>About Us</string>
<string>Site Map</string>
<localize name="description">
<string>An excellent budget hotel in New York City</string>
<img src="/img/0156849.png" title="Bedroom - Basic Suite">
<img src="/img/0156849.png" title="Bathroom - Basic Suite">

Other Information

Note: Some XML files closely resemble HTML files and are more effectively translated by parsing them as HTML files. Smartling allows you to specify HTML as the file type when uploading an XML file in the dashboard to cope with this type of XML files. If uploading via API, give "html" as the Smartling identifier for the file.

Note: When using file/get to download XML files from Smartling, the parameter includeOriginalStrings=false ensures that if no translations are available, Smartling returns an empty string. If the parameter is set to true, Smartling returns the original string.


Directive Format

<!-- smartling.[directive_name] = [value] -->

The directive must be a single comment on one line, and there should not be any inline trailing symbols after the directive. Directives apply to all strings that follow them. Directives can be changed throughout the file


Values:A comma-separated list of paths to be captured as strings for translation.
Description:When included in this list, all plain text within the specified tag will be considered a translatable string. Optionally, you can append a "." and a relevant attribute name to the path to translate tag attributes with the file. You can end the path with a trailing slash, "/" and it will treat all child nodes as translatable (content must still be text within a tag).
<!-- smartling.translate_paths = data/localize/string, data/localize.title, data/localize/root/ -->

Smartling will translate content in the data/localize/string & data/localize/root nodes. The title attribute of the data/localize node will also be translated.


Values:The value of this directive is expressed as [format]:[paths]

Specifies the format of strings for the specified paths and can enable HTML inside another file format.

Currently supported formats are:

  • HTML - string value will be parsed as HTML
  • @default - (note the leading at-sign) string value will be treated as simple text.

Separate multiple formats by commas

You may specify a single path for a format or a comma-separated list of paths enclosed in square brackets. The list may be empty.

Note: Even if you have enabled HTML parsing, the content must still be valid XML and needs to be XML-escaped or wrapped in <![CDATA[]]> tags. For example, <b>Hi!</b> would be written as &lt;b&gt;HI!&lt;/b&gt; OR <![CDATA[<b>Hi!</b>]]>

<!-- smartling.string_format_paths = html: /product/description -->

Smartling enables HTML in /product/descriptions only.

<!-- smartling.string_format_paths = html: /product/description/ -->

Smartling enables HTML in /product/descriptions and all its child nodes.

<!-- smartling.string_format_paths = -->

Disables the effect of the previous string_format_paths instruction.


Values:1. Custom regular expression (pcre)
2. NONE - disable custom placeholders
Description:Used to define a custom placeholder format for strings in the file. See Placeholders in Resource Files for more information.
<!-- smartling.placeholder_format_custom = \[.+?\] -->

Any characters surrounded by square brackets will be treated as a placeholder.


Description:Used to specify a standard placeholder format. See Placeholders in Resource Files for more information.
<!-- smartling.placeholder_format = IOS -->

Specifies iOS-style placeholders for the file.


Values:translate OR notranslate
Description:Use this directive to enable or disable processing of translation strings in the file. You must turn translation back on after the strings you want to exclude.
<!-- smartling.sltrans = notranslate -->

Strings below this directive will be captured as strings but excluded from translation

<!-- smartling.sltrans = translate -->

Strings below this directive will be translated



A comma separated list of paths to use create "keys" for strings on translate_paths.

The key will be a space separated string of all the keys leading to the source string. For example: "string", "group1 string".


Used to define the schema for capturing a key for each source string. Keys are required:

  • If you want to import pre-existing translations from a file with the same structure
  • If you want to create variants of strings that would otherwise be duplicates (By default Smartling does not create duplicate strings.)

    Note: creating or updating variants for previously uploaded strings cause new strings to be created that will not have translations. The SmartMatch feature can be configured to automatically apply the existing translations, or translators can use the 100% match from the Translation to manually apply the translation.

  • Specify the full path to the value, then indicate which part of the path should be used as the key using {} notation.

<!-- smartling.source_key_paths = data/item/{} -->

Smartling will capture the name atribute of the data/item/string node as the key.

<!-- smartling.source_key_paths = data/item/{string_name} -->

Smartling will capture the content of the string_name node as the key.


Values:true|TRUE|on|ON OR false|FALSE|off|OFF

When enabled, Smartling will make strings unique using variant metadata. Must be used in conjunction with the code>source_key_paths directive, which provides the information needed to generate variant metadata.

Note: if you have previously uploaded a file with variants turned off, and reupload the file with variants on, Smartling will capture all content as new strings. You can configure Smartmatch to automatically match the existing translations.

<!-- smartling.variants_enabled = TRUE -->


Values:int - Accepted values are 0-100
Description:Sets the percentage by which original strings are inflated when downloading pseudo translations. If this directive is not set, pseudo translations are 30 percent longer than the original strings.
<!-- smartling.pseudo_inflation = 80 -->

Downloaded pseudo translations will increase the length of original strings by 80 percent.