Back to top image

Java Properties

 

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

Java properties files are typically used to store project configuration data or settings in Java applications.

Example File

#Global
selfservice.global.buttons.ok = Ok
selfservice.global.buttons.cancel = Cancel
selfservice.global.buttons.save = Save
selfservice.global.buttons.saveChanges = Save Changes
selfservice.global.buttons.close = Close
selfservice.global.buttons.edit = Edit
selfservice.global.buttons.enable = Enable
selfservice.global.buttons.disable = Disable
selfservice.global.buttons.next = Next
selfservice.global.buttons.continue = Continue
selfservice.global.buttons.back = Back
selfservice.global.buttons.finish = Finish
selfservice.global.state.on = On
selfservice.global.state.off = Off

# Menus
selfservice.menu.settings.title=Settings
selfservice.menu.settings.subtitle=Settings
selfservice.menu.settings.languageSelector=Language Selector
selfservice.menu.settings.siteOwnerInfo=Site Owner Information

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

Keys and 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

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 Smartling captures content and delivers translations, and handle automatic application of variables as placeholders.

The default behavior is the same as if you applied with the following directives:

placeholder_format=JAVA
string_format=MESSAGE_FORMAT

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 because 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 parsing issues encountered in Smartling when using java properties files is caused by applying the right directives to get the behavior needed for the strings regarding 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 directive and not be correctly translatable. Strictly speaking, “% o” is a valid format specifier.

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:

#smartling.placeholder_format=NONE
string=Your subscription is 50% off.
#smartling.placeholder_format=JAVA

With this directive, the string will be captured without a placeholder, and assuming the % 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:

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

When applying the directives inline within your file, 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:

#smartling.string_format=MESSAGE_FORMAT
#smartling.placeholder_format=NONE

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.

For more information, read our documentation on Placeholders in Resource Files.

XML Characters

The following XML character are always escaped. You can control this by using the entity_escaping directive.

Character (character name) Escape sequence

< (less-than)

&lt;

> (greater-than)

&gt;

& (ampersand)

&amp;

' (apostrophe or single quote)

 &apos;

" (double-quote)

  &quot;

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

Plurals

ICU MessageFormat

To parse the strings using ICU MessageFormat you can use two Smartling directives (either inline or via API):

  1. string_format with a value of icu
  2. string_format_paths with a value of icu and then specifying array of the specific keys or paths.

Smartling paths support simple wildcards. See ICU MessageFormat for additional information.

ICU MessageFormat parsing implies both placeholders and support for advanced formatting syntax such as select statements and plurals. When parsing strings as ICU MessageFormat that default placeholder syntax takes precedence and will always apply if the syntax is present.

If ICU string formatting is used, then that takes precedence over HTML and any HTML directive will be ignored if your directives resolve in a value being parsed for both ICU and HTML. It is possible in a single file to have both HTML formatted strings and ICU formatted strings, but they must be on different paths.

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.

Directives

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

Inline File Format

# smartling.[directive_name] = [value] 

API Parameter

smartling.[directive_name] = [value] 

Here are examples of supported directives for Java Properties:

Directive name Values Description Example
backslash_escaping_characters
A sequence of characters to escape.

This directive applies the backslash-escaping for custom characters. Whitespaces are ignored.

Escapes on download from Smartling.

# smartling.backslash_escaping_characters = "@%

Smartling will escape the characters with a "\" character.
download_format
  • NONE (default)
  • ESCAPE_UNICODE

Controls Unicode character escaping on file download.

ESCAPE_UNICODE indicates that all non-Latin1 (not in range 0000 - 00FF of Unicode) symbols after this command should be escaped by \uXXXX 

# smartling.download_format = ESCAPE_UNICODE

Hello ?

Smartling will escape the ? on download as:

Hello \u1D25

entity_escaping
  • auto (default) 
  • true
  • yes 
  • false
  • no

(case-insensitive)

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.

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 the above string to appear unescaped.

entity_escaping_type

  
  • html4 (default)
  • html5

(case-insensitive)

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 

entity_escaping_strategy
  • none (default)
  • propagate

(case-insensitive)

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.

If HTML5 entities are required as well, you must use the entity_escaping_type=propagate directive.

 

# smartling.entity_escaping_strategy = propagate

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 does not affect source content at all - so using it will not result in new strings.

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.

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

placeholder_format
  • NONE
  • C
  • IOS
  • PYTHON
  • JAVA
  • YAML
  • QT
  • RESX

Used to specify a standard placeholder format.

# smartling.placeholder_format = IOS 

Specifies iOS-style placeholders for the file.

placeholder_format_custom
  • Custom (Java Regex)
  • NONE - disables any current custom placeholders.

Specifies a custom placeholder format. Any text in your file matching the regular expression you provide will be captured as a placeholder.

See Placeholders in Resource Files for more on placeholders.

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

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

pseudo_inflation

Integer values between

0 - 100

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.
string_format
  • NONE (default)
  • MESSAGE_FORMAT
  • ICU

This directive controls processing for strings parsed by JAVA parser.

#smartling.string_format=MESSAGE_FORMAT

Enables MessageFormat parsing
string_format_path
  • HTML
  • ICU

Specifies format of strings at the specified paths.

#smartling.string_format=ICU:<path>

sltrans
  • translate
  • notranslate

Use this directive to enable or disable processing of translation strings in the file. You must turn translation back on once you're done with notranslate.

Any content with this tag will not appear in the Smartling dashboard, but will appear in your translated file in your original source language.

 

 

# 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. 
unicode_escaping_characters

 
  • none (default)
  • one or more characters to escape

This directive controls Unicode escaping by pointing to the Unicode characters that must be unicode-escaped.

It results in (\uXXXX form) in the translated file.

This directive has priority over the unicode_escaping_strategy directive.

# smartling.unicode_escaping_characters = '&$😍
unicode_escaping_strategy
  • none (default)
  • propagate

This directive also controls Unicode escaping. When set to propagate, Smartling detects what Unicode characters should be escaped in the translated string according to their form (i.e. if they are escaped/non-escaped) in the source string.

The directive unicode_escaping_strategy overrides this directive.

# smartling.unicode_escaping_strategy = propagate

whitespace_trim
  • on (default)
  • yes
  • true
  • off
  • no
  • false
  • leading
  • trailing

 

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 manage whitespace trimming.

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

 

Table of Contents