Back to top image

Android XML

 

Extension .xml
Smartling Identifier android
Example File Click here to download an example file with common directives
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.

Keys-Variants

Every string is created with key/variant metadata, which is the value of the string.name attribute. If the value of two strings is the same, but the string.name 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're 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>

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

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

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 -->
<resources>
     <!-- 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>
     </plurals>
<!-- smartling.instruction_comments_enabled = off -->
     <!-- It's just comment for string5 and not a string instruction -->
     <string name="string1">string5</string>
</resources>

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 -->
<resources>
     <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>
     </plurals>
     <string-array name="items_array" alert="instruction for items">
        <item>item1</item>
        <item alert="instruction for item2">item2</item>
        <item>item3</item>
     </string-array>
</resources>

Excluding Strings from Translation

Smartling will not capture excluded strings. However, we do keep them in the delivered translation file. If you have many 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.
</string>

Tip: The attribute value "FALSE" used to exclude strings is not case-sensitive. 

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.

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.

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 Android XML:

Directive name Values Description Example

character_limit
  • Any integer value
  • NONE

Sets or removes the maximum characters allowed for a translation.

The directive should go directly before the string, where the character limit should be applied.

If NONE is specified, character limits will be removed.

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

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.

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

instruction_attributes

 Comma-separated name of an attribute of a string or plurals nodes in your file.

Sets attributes of content nodes to be captured as file instructions for strings.

<!-- smartling.instruction_attributes = comment, instruction -->

instruction_comments_enabled
  • true
  • false

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

<!-- smartling.instruction_comments_enabled = true -->

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.

plurals_detection
  • on
  • yes
  • true
  • off
  • no
  • false

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.

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.

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

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