Android XML


Extension .xml
Smartling Identifier android
Resources Android String Resources
Android Localization

Smartling supports the Android XML resource file format. When uploading an Android XML file, make sure to specify that it is an android file, so it is not parsed as a custom XML file.


Every string is created with key/variant metadata, which is the value of the attribute. If the value of two strings is the same, but the attribute is different, Smartling creates two strings.

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 Android XML resource files.

The default behavior when uploading an Android resource file is as if you integrated with the following command

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

Smartling assumes that the strings are being 'formatted' in your application. This implies that the strings are being formatted in your application code using java.util.Formatter (java)(kotlin). This has specific implications for how we capture  strings and deliver the translations, and handle automatic integration of variables as placeholders.

A string using that class and method may have standard c-style/printf format specifiers for variables. 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).

A common integration issue encountered when using Android XML files with Smartling is that a string that has a % character in the source (and therefore in the translation) has the translation delivered with that character "escaped" as %%.

For example, if your original file has:

<string name="string2">Your subscription is 50% off.</string>

That is NOT being formatted in your application Smartling will still identify a placeholder ('% o'). Strictly speaking '% o' is a valid format specifier. To avoid this string being captured with a placeholder, and the translation being delivered with "escaped" percent characters, turn off the formatting and then turn it back on after the string in question so that subsequent strings will be captured with formatting:

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

<string name="string2">Your subscription is 50% off.</string>

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

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

Another case is seen in this example string:

<string name="string1">Your subscription is %d% off.</string>

The string captured by Smartling will have incorrect placeholder integration and not be correctly translatable. This string is surely being "formatted" in the application and so therefore the second % character really should be escaped in the source as '%%'.

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

<string name="string1">Your subscription is %d%% off.</string>

Smartling will correctly capture this string (we will show only one '%' char in the dashboard and to translators) and assuming the translation also uses the % character will escape it in the translated file.

We recommend uploading your complete set of Android XML 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 before beginning translation.

XML Characters (always escaped)

Character (name) Escape sequence

< (less-than)


> (greater-than)


& (ampersand)


' (apostrophe or single quote)


" (double-quote)


String Instructions

String instructions can be set using the instruction_comments_enabled and instruction_attributes directives

If instruction_comments_enabled is turned on any XML comment that immediately precedes a string is captured as the Instruction for that string.

Android Comments -> Smartling Instructions

<?xml version="1.0" encoding="UTF-8"?>
<!-- smartling.instruction_comments_enabled = on -->
     <!-- The instruction for string1 -->
     <string name="string1">string1</string>
     <!-- The instruction for string2 -->
     <string name="string2">string2</string>
     <!-- The instruction for string3 --><string name="string3">string3</string>
     <!-- It's multiline -->
     <!-- The instruction for string4 -->
     <string name="string4">string4</string>
     <!-- The instruction for plurals -->
     <plurals name="Nsongs">
        <item quantity="one">a song</item>
        <item quantity="other">%s songs</item>
<!-- smartling.instruction_comments_enabled = off -->
     <!-- It's just comment for string5 and not a string instruction -->
     <string name="string1">string5</string>

If instruction_attributes is configured with some valid XML element attributes, then the value of that attribute is captured as the instruction for that string.

Android string attributes -> Smartling string instruction

<?xml version="1.0" encoding="UTF-8"?>
<!-- smartling.instruction_attributes = comment, note -->
     <string name="string1" comment="comment for String01">String01</string>
     <string name="string2" note="note for String02">String02</string>
     <string name="string3" comment="comment for String03" note="note for         String03">String03</string>
     <!-- smartling.instruction_attributes = -->
     <string name="string5" comment="comment for String05 - not  instruction">String05</string>
     <!-- smartling.instruction_attributes = alert -->
     <string name="string6" alert="note for String06">String06</string>
     <plurals name="Nsongs" alert="Instruction for NSongs">
        <item quantity="one">a song</item>
        <item quantity="other">%s songs</item>
     <string-array name="items_array" alert="instruction for items">
        <item alert="instruction for item2">item2</item>

Excluding Strings from Translation

Smartling will not capture excluded strings, however, we do keep them in the delivered translation file. If you have a lot of resources that should not be translated, you can place them in a file named donottranslate.xml, and Lint will consider all of them as non-translatable resources.

To exclude a string from translation use the translatable="FALSE" attribute and value in the string tag:

Android XML:

<string name="string_11" translatable="FALSE">
     This android string has been marked not to be translated using the translatable attribute.

When downloading translated Android XML files via the File API, setting the parameter includeOriginalStrings=false can only strip strings that are intended for translation, but not yet translated.

Standard Placeholder Format

By default, Smartling recognizes Java-style placeholders in Android XML files. See Placeholders in Resource Files for more on placeholders.

Because of its unique markup language, all tags in Android XML files are ingested as placeholders in Smartling. This means that they will be checked under the Placeholder Consistency Quality Check option, and not Tag Consistency.


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] -->

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.


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 1. Custom [Perl compatible regular expression](
2. NONE - 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.



Description Used to specify a standard placeholder format.

<!-- smartling.placeholder_format = IOS -->
Specifies iOS-style placeholders for the file.


Values true OR false
Description If this directive is set to true, any comment in the file is ingested as an instruction for the next string.



Values Name of an attribute of a string or plurals nodes in your file.
Description Sets attributes of content nodes to be captured as file instructions for strings.



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 integer or NONE
Description Sets or removes the maximum characters allowed for a translation. If NONE is specified, character limits will be removed.

<!-- smartling.character_limit = 25 -->

The directive should go directly before the string where the character limit should be applied. This will apply a character limit of 25 to the string on the line after the directive.

<!-- smartling.character_limit = NONE -->

This will remove any character limits set for a string even if the character limit was set manually in the Dashboard.




Values  on|yes|true or off|no|false
Description  Enables or disables plurals detection. If using plural detection for a YAML file as part of a Ruby on Rails project, ensure your project is set up with correct pluralization rules.
By default, no strings are captured as plural (to avoid false positives).
Add this directive anywhere in your file to turn it on. For precision integration to avoid false positives add a Smartling "on" directive immediately before the plural group and an "off" directive immediately after.

<!-- smartling.plurals_detection = on -->

Smartling will detect plurals in strings below this directive.




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

Was this article helpful?