Preparing & Translating Supported File Types

Java Properties


Extension .properties
Smartling Identifier javaProperties
Example File (see example below)
Resources Java Localization Documentation


Java properties example file:

#Global = Ok = Cancel = Save = Save Changes = Close = Edit = Enable = Disable = Next = Continue = Back = Finish = On = Off

# Menus Selector Owner Information

# Welcome
selfservice.intro = Hello {0}, welcome

Keys - Variants

Every string is created with key/variant metadata based on the keys in the file. If the keys are different for two strings with the same value, Smartling will create two strings using the key as context metadata. It is invalid to have the same key in a single resource file, though Smartling will not report any errors for such a file.

Formatting and Escaping

Review the Formatting and Escaping section and carefully review your source files and test the round-trip with Smartling using Pseudo Translation download to determine the correct integration before you begin translating with strings from Java Properties files.

When capturing strings from a Java Properties file Smartling assumes that the strings are being used for Format and MessageFormat. This has two specific implications for how we capture and deliver strings, and handle automatic integration of variables as placeholders.

The default behavior is the same as if you integrated with the following commands


placeholder_format=JAVA implies that the strings are being formatted using java.util.Formatter. A string using that class will have standard c-style/printf format specifiers for variables and bebecause those variables use the percent char ‘%’ to mark them, when you want an actual percent character to display in your string you must escape it as ‘%%’ (both in the original and in translated strings).

string_format=MESSAGE_FORMAT implies that the strings are being formatted using java.text.MessageFormat. A string using that class will have FormatElements in curly braces and because the single quote character is used to escape the special characters { and } a single quote that you want to appear as a character must be escaped as ‘’ (both in the original and in translated strings)

The most frequent integration issues encountered in Smartling when using java properties files is caused by not integrating your file to get the behavior needed for the strings in regards to placeholder formatting and special character escaping.

For example, if your original file has:

string=Your subscription is %d% off.

The string captured by Smartling will have incorrect placeholder integration and not be correctly translatable. Strictly speaking “% o” is a valid format specifier. There are two ways to avoid this integration issue.

If your strings are formatted by Formatter, the % should be escaped in your resource file:

string1=Your subscription is %d%% off.

Conversely if you have a string like this:

string=Your subscription is 50% off.

That is NOT being formatted by Formatter Smartling will still identify a placeholder (‘% o’) for the same reason. To avoid this string being captured with a placeholder, turn off the formatting and then turn it back on if you need subsequent strings to be captured ready for formatting:

string=Your subscription is 50% off.

With this integration the string will be captured without a placeholder, and assuming the % char is still present in the translation it will not be escaped as %% when you download the translated files.

Similar issues are seen for the MessageFormat behavior. If your source file has this string which will be passed through MessageFormat:

string1=You can't delete {0}.

The ‘ should be escaped if it’s passing through MessageFormat:

string1=You can''t delete {0}

Similarly if you have a string with the literal characters { } or the ‘ character that is NOT passing through MessageFormat:

string1=You can't delete it. {We won't let you!}

You can ensure proper capture and delivery of the translation by turning off MessageFormat and then turning it back on when needed after the string to insure subsequent strings get MessageFormat treatment:

string1=You can’t delete it. {We won’t let you!}
# smartling.string_format=MESSAGE_FORMAT

When integrating the directives “inline” in your file once your set a directive it will apply to all subsequent strings. So for example, if you know your file is entirely made of strings that require MESSAGE_FORMAT but not JAVA formatting you can place the following at the top of your file:



Remember that this behavior will be true for capturing strings and delivering translations. It is very common for translators to use the single quote character as part of their translation even when the original language string did not have any quote characters.

We recommend uploading your complete set of Java Properties files and then downloading the pseudo translation, and then use that to bring up your application with the pseudo localization to check for any issues or errors.

See Placeholders in Resource Files for more on placeholders.

String Instructions

For files using Parser version 3, Smartling will automatically capture and display file comments as instructions for translators. The comments must immediately precede the string.

For example, for the following comment, the text “Back button label” will be captured as a file instruction.

# Back button label
Back = Back

Return Untranslated Strings as Empty

When using file/get to download properties 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.


File directives are supported, both inline and via our APIDirectives are specified in comments within the files, in the following format:

Inline File Format

# smartling.[directive_name] = [value] or [path]

API Parameter

smartling.[directive_name] = [value] 

Here are some examples of [directive_name], along with example values or paths.


Exact delivery depends on file type.

Values auto (default) | true | yes | false | no

Controls whether base characters ( > < & " ) are "escaped" into entities when delivering translations. This can be set universally for the whole file via API, or by setting the directive at the top/start of the file. The directive can also be placed inline to control the behavior of specific strings.

To use inline:
# smartling.entity_escaping = false

# smartling.entity_escaping = auto


For example, your translation might look like this:
This is an <hr> & " example string4

By default, using the "auto" setting, we will assume this is HTML from the <hr> tag.

When the translated file is downloaded, the translated string will be escaped as:
This is an <hr> &amp; &quot; example string4

Using # smartling.entity_escaping = false will allow This is an <hr> & " example string4 to appear unescaped.

XML Characters (always escaped)

Character (name) Escape sequence

< (less-than)


> (greater-than)


& (ampersand)


' (apostrophe or single quote)


" (double-quote)




Exact delivery depends on file type.


html4 (default)|html5



By default, all html4 entities are unescaped, except the basic set: &lt; &gt; &amp; &quot;.

When this directive is set to html5, all html5 entities will be unescaped as well.


# smartling.entity_escaping_type = html5 



Values propagate | none

Used to retain entity escaping for all non-base entities. For example normally we turn &copy; into © but if we use this new directive the translation will automatically update to use escaping from the source. For each entity character we'll check to see if it was escaped in the source and try to match (propagate) it in the target.

The default is none which is the current behavior, which recognizes HTML4 entities only - if HTML5 entities are required as well, you must use the entity_escaping_type=propagate directive.

propagate will only affect non-base entities - all named entities except &amp; , &quot;, &lt;, &gt; . Base entities continue to be controlled by HTML detection and the entity_escaping directive.

If the same character is both escaped and unescaped in the same string propagate will return the characters in the translation escaped in the same order as they were in the source. However, if there are a different number of characters in the translation where the translation process removed or added some and the escaping is inconsistent among them, propagate will escape all entities for that character.

This directive can be placed inline, in the API or in a template (consult your SA about configuring directive templates).

This does not affect source content at all - so using it will not result in new strings.

Numerical entities are not considered at all with this directive, and are treated normally.


To use inline:
# smartling.entity_escaping_strategy = propagate



Values A sequence of characters to escape with the "\" escaper on download. Whitespaces are ignored.
Description Applies the backslash-escaping for custom characters.

# smartling.backslash_escaping_characters = "@%



Description Used to specify a standard placeholder format. 

# smartling.placeholder_format = IOS

Specifies iOS-style placeholders for the file.




Values 1) Custom Perl compatible regular expression.
2) NULL - disables any current custom placeholders 
Description Specifies a custom placeholder format. Any text in your file matching the regular expression you provide will be captured as a placeholder.. 

# smartling.placeholder_format_custom=\{([^}]+)\}

Any characters surrounded by curly brackets, e.g., {first name}, will be treated as a placeholder.

See Placeholders in Resource Files for more on placeholders.



Values integer - 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.




Values MESSAGE_FORMAT (default) or NONE 
Description String format is a parser directive for specialized file processing that enables string escaping and pre-processing rules as defined by various third party resource handlers. The default is MessageFormat, a standard Java resource handler. 



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

Specifies the format of strings for the specified paths and can enable other formats inside properties files.

  • Currently, supported formats are:
    • HTML - string value will be parsed as HTML
    • MARKDOWN (or MD) - string value will be parsed as GitHub Markdown
    • JSON - string value will be parsed as JSON (extracts the JSON values for translation)
    • PLAIN_TEXT (or TXT) - string value will be parsed as plain text
    • @default - (note the leading at-sign) string value will be treated as simple text.
    • NONE - reset all settings for the string_format_paths directive
      (Note: All format references are case-insensitive)
  • Separate multiple formats by commas
  • You may specify a single key for a format or a comma-separated list of keys enclosed in square brackets. The list may be empty.
  • Also, keys may have one or more wildcards (*) in them to target a group of keys.

Smartling parses values of all keys as HTML. The following example is segments from a single file:

# smartling.string_format_paths = html: *
java.html.string1 = <div>text is extracted from within block tags</div>

The above example shows parsing two different types of content - HTML within JAVA

# smartling.string_format_paths = HTML : java.html.*, markdown :*
java.html.string1 = <div>text is extracted from within block tags</div> = **text parsed as markdown**\n\n

The above example resets the parser to the default java properties format for particular keys - java.html and

# smartling.string_format_paths = @default: *
java.html.string1 = <div>entire string is parsed</div>
# smartling.string_format_paths = none
java.html.string1 = <div>entire string is parsed</div>
The above two examples resets the parsing to the default java properties format completely



Description ESCAPE_UNICODE indicates that all non-Latin1 (not in range 0000 - 007F of unicode) symbols after this comment should be escaped by a \uXXXX escaping expression in the process of a file download. 

# smartling.download_format = ESCAPE_UNICODE

Hello? will be escaped as Hello\u1D25 on download.




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.





on|yes|true or off|no|false or leading|trailing

The default value is on


A whitespace is any character or series of characters that represent horizontal or vertical space in typography. When rendered, a whitespace character is not a visible mark, but does occupy an area or space on a page.

Although whitespaces are necessary within a string (typically to separate words), unnecessary whitespaces can be found at the start of a string (leading) and at the end of a string (trailing).

With this directive, you can trim whitespaces, as it enables or disables whitespace trim management for the ingested strings.

By default, the leading and trailing whitespaces are trimmed.

You can choose to disable trimming or specify trimming for leading or trailing whitespaces.

The directive can be used inline or as the API request parameter.


# smartling.whitespace_trim=on

Smartling will trim leading and trailing whitespaces (default)

# smartling.whitespace_trim=off

Smartling will not trim leading or trailing whitespaces

# smartling.whitespace_trim=leading

Smartling will trim only leading whitespaces

# smartling.whitespace_trim=trailing

Smartling will trim only trailing whitespaces

Was this article helpful?