Translating Files

Placeholders in Resource Files

Resource files often use placeholders in strings to allow dynamic information to be inserted into a string, excluding it from translation, while still allowing the translator to position them as needed in the translated string. Placeholders are also known as “formatting strings”, “format specifiers” or just “specifiers”.

For example: "Welcome %{username}, you have $%{balance} in your account"

Formatting tags such as HTML and markdown are NOT placeholders. Please review Standard behavior and customization for localization resource files for more information.

Smartling will recognize standard placeholders by default. Exactly what is captured as a placeholder depends on the file format. In most cases you do not need to customize this behavior if you are using standard placeholders.

If you are using a custom file format, have custom placeholder syntax or use non-standard placeholders, you can integrate to get the behavior you want. Integration can be performed either in the file or via the API. So-called “file inline” integration gives you extra customization options - for example, you may be able to change placeholder behavior throughout the file - but requires you to customize the file for Smartling. API-based integration allows you to avoid adding Smartling specific code to your file but will affect all the strings in the file.

Smartling offers two directives to identify the types of placeholders that are used in your files:

  • The placeholder_format directive lets you specify that your placeholders adhere to a common standard. Options are C, IOS, PYTHON, JAVA, YAML, QT, or RESX.
  • The placeholder_format_custom directive lets you specify custom placeholders using a regular expression. Any group of characters matching the regular expression will be captured as a placeholder.

Positional Information

For some standard placeholder formats, Smartling automatically adds positional information, so that if a translator needs to switch the order of placeholders, they will still work correctly. For example, if you upload the string A room at %s is reserved for %s., Smartling will capture A room at %1$s is reserved for %2$s.. Note that this will not be done for custom placeholder formats, so if you have more than one custom placeholder in a string, make sure that a translator can tell them apart. For example: A room at [hotel] has been reserved for [user]. is safer than A room at [var] has been reserved for [var].

Specifying Standard and Custom Formats

These two directives work in tandem. For example if you were specifying placeholder behavior inside of a custom XML file you could specify both:

<!-- smartling.placeholder_format = PYTHON -->

and

<!-- smartling.placeholder_format_custom = \[\[.+?\]\] -->

Both the standard Python style placeholders, and a custom placeholder will be recognized when found in a string. In this example the custom placeholder is delineated by having two open and closed square bracket characters with text in between them: [[firstName]].

Here is a list of some of the example placeholders and directives:

Placeholder

Directive*

{{...}} # smartling.placeholder_format_custom=\{\{.+?\}\}
[[...]] # smartling.placeholder_format_custom=\[\[.+?\]\]
${...} # smartling.placeholder_format_custom=\$\{.+?\}
%{...}  # smartling.placeholder_format_custom=%\{.+?\}
#...#  # smartling.placeholder_format_custom=#.+?#

* The example shown is for an inline placeholder for a java properties file. The syntax for declaring the directive and the value may differ for different file types or integrations methods such as the API.  See the documentation for the file format for details on how to format inline directives and the API documentation for API directives.

Verify Placeholders

To check that your placeholders are being captured as expected, check the string in the List View in the Smartling Dashboard. Correctly captured placeholders will be highlighted. If you need to make changes to the formatting, see Insert, Remove, or Move Tags and Placeholders.

Escaping

When defining the regular expression for a custom placeholder you may need to escape characters that are part of the expression to account for the environment (file or shell). After escaping is accounted for the expression will be evaluated as a Perl compatible regular expression (PCRE).

So, in the above example, because brackets have special meaning for PCRE they must be escaped with a backslash ()for the regular expression engine. However, in another context the backslash itself may need to be escaped.

The most common example is seen in JSON where the backslash character in the value of name/value pair already has special meaning for JSON, and so must be escaped to be valid a character in JSON. Also note when defining a custom placeholder inline of a JSON file we require the expressions to be listed in an array. So the above directives modified to be inside of a JSON file would be:

JSON

"smartling": {
   
"placeholder_format" : "PYTHON",
   "placeholder_format_custom" : ["\\[\\[.*?\\]\\]"]
}

Not Specifying Placeholder Formats

If your file has non-standard placeholders and you do not integrate to define them Smartling will capture the string with the placeholder as ‘plain text’; they will typically be counted as “words” for translation, translators will have to manually enter the placeholder using the correct syntax, and the Smartling CAT tool will not be able to warn the translators about missing placeholders or incorrect syntax.

Was this article helpful?