Android XML

Information about how Transifex handles the Android XML (.xml) file format.

Transifex avatar
Written by Transifex
Updated this week

File Extension(s)

.xml

i18n type(s)

ANDROID

Android uses an XML-based format for localization. There are three types of entries: string, string-array, and plurals.


Entry type: string

The first type of entry contains simple strings or sentences. Each entry in a resource must have a unique name attribute. This is represented as a single entry for translation in Transifex as well.

<resources> 
<string name="localization_manager">Localization Manager</string>
<string name="admin_users">Administrators are people that manage the organization.</string>
<string name="contribution">Become a translator or contribute to a Transifex project.</string>
<string name="updates">Keep me up to date with Transifex news</string>
<string name="live_status">Live status of Transifex service</string>
<string name="connect_with_users">Connect with users on Transifex</string>
</resources>

In the editor, such a string will be displayed as follows:

android_strings_editor.png#asset:3049


Entry type: string-array

The string-array type also has a name attribute, which must be unique in a resource file. Each string array contains multiple items. These items are represented as a single translation entity in Transifex, so it is possible to have a different number of entries in a particular language.

So, the whole content of a string-array is shown for now, and the translator is responsible for creating a correct list of translated items. For example:

<resources> <string-array name="account_details_array"> <item>username</item> <item>Email address</item> <item>Full name</item> <item>Contact info</item> </string-array> </resources>

The above items in Transifex will have the following keys assigned:

  • username: account_details_array[0]

  • Email address: account_details_array[1]

  • Full name: account_details_array[2]

  • Contact info: account_details_array[3]

The above entry lists the details of an account in English. It should be translated into French as:

<resources> <string-array name="account_details_array"> <item>Nom d'utilisateur</item> <item>Adresse de courriel</item> <item>Nom complet</item> <item>L’information de contact</item> </string-array> </resources>

And into Russian as:

<resources> <string-array name="account_details_array"> <item>имя пользователя</item> <item>Адрес электронной почты</item> <item>Полное имя</item> <item>Контактная информация</item> </string-array> </resources>


Entry type: plurals

The last type of entry, plurals, also has an attribute name (which is required to be unique) and contains a list of items, each with an attribute quantity used to select the appropriate plural form of the string for a particular number of elements.

So, if your project's source language is, for example, English (2 plural forms), each pluralized entry has to include the following two plural forms:

<resources> <plurals name="minutes_count"> <item quantity="one">%s minute</item> <item quantity="other">%s minutes</item> </plurals> </resources>

In case you omit a plural form and try to upload the file to Transifex, the following error message will appear:

missing_plural_form.png#asset:3060

In case an additional plural form is included (except for "one" & "other"), then the following error message will be displayed after trying to upload the file to Transifex:

additional_plural_form.png#asset:3061

After translating the above string into another language, for example, Russian, the translation file after downloading it from Transifex will look like this:

<resources> <plurals name="minutes_count"> <item quantity="one">%s минута</item> <item quantity="few">%s минуты</item> <item quantity="many">%s минут</item> <item quantity="other">%s минут</item> </plurals> </resources>

📝Note: Do you want to find out more about plurals in Transifex? Please check here.


Attributes

Any attributes in the string, string-array, and plural elements can be used.

Transifex will recognize, however, a specific attribute, translatable. When its value is false, Transifex will ignore the specific entry and not present it to translators in the web editor or in the files downloaded for offline translation. For instance, the following entry will not be translated:

<string name="name" translatable="false">Untranslated</string>

The product attribute is also recognized by the Transifex Android parser and can be used for entries where the same "name" attribute has been defined.

product_attribute.png#asset:3507

The parser will parse your content successfully without duplicate keys being an issue.


Escape behavior

Currently, we have two versions of Android parser coexisting in transifex:

  • Android parser version 2 is the version assigned to Android resources created before January 2024.

  • Version 3 of the Android parser is now assigned to resources created on or after January 2024.

The way escaping works may differ depending on the version of the Android parser you are using for your Android resources. In this regard, we will explain the escaping behavior that you should anticipate in the Android Version 3 parser. Please note that no previous versions are currently maintained.

📝Note: You can find out the version of the Android parser your resource has by checking your resource settings:


If you wish to upgrade the Android parser version of your files from any previous version to Android parser v3, you'll need to create a new resource and upload both the source file and the translation files to this new resource.


Special characters escaping behavior on Android Parser (Version 3)

Below are some tables explaining the escaping behavior that the Android parser (version 3) applies to special characters that it supports; these are the concepts described in the tables.

  • Character name: Special character identifier.

  • Character in source file: How the character was uploaded in the source file.

  • Character in rich mode: How the character will appear in a rich mode in the source and translation text.

  • Character in raw mode: The character appearance in translations when the editor is in raw mode or when the translation file is downloaded (only if the translation string was saved in rich mode).

1. When uploading unescaped special characters in the source file

Only the following characters are accepted unescaped, as described in the below table:

Character name

Character in source file

Character in rich mode

Character in raw mode

Backslash

\

\

\

Break line

At sign

@

@

@

Question mark

?

?

?

📝Note:

Translations associated with strings containing unescaped characters in the source will have these characters escaped once provided by translators. If you wish to retain these characters unescaped in translations too, you can switch to raw mode to bypass this rule.


In case you attempt to upload any of the following characters without escaping them, the upload will fail with an error:

  • Ampersand &

  • Less than <

  • Greater than >

  • Double quotes "

  • Single quotes '

These characters will only be accepted unescaped if they are part of an inline tag.

2. When uploading escaped special characters in the source file

Character name

Character in source file

Character in rich mode

Character in raw mode

Ampersand

&amp;

&

&amp;

Less than

&lt;

<

&lt;

Greater than

&gt;

>

&gt;

Double quotes

\"

"

\"

Single quotes

\'

'

\'

At sign

\@

@

\@

Question Mark

\?

?

\?

Backslash

\\

\\

\\

Line break

\n

\n

Backslash + Double quotes

\\"

\"

\\"

Example

Source string

Given the following string in the source file:

<string name="3">In this &gt; string \" there are a few of escaped characters &amp;</string>

Rich mode

The source and translations of this string will look as below in the editor's rich mode:

Raw mode and when downloading the translation file

In the editor's raw mode:

In the translation file:

<string name="3">En esta &gt; cadena \" hay unos cuantos caracteres escapados &amp;</string>

3. Escaping behavior on the translations

When translating in raw mode

When a user translates a string in raw mode, if a special character & > ' @ ? " isn't explicitly escaped, it will remain unescaped when downloading the translation because Transifex assumes that it was intentionally decided not to escape it to bypass the parser’s rules described in the above tables.

When translating in rich mode

When a user translates a string in rich mode and adds any of the following characters & > ' @ ? " in the translation text, these characters will automatically be escaped in raw mode, and when exporting the file from Transifex, following the parser's rules described in the tables above.

When translating strings with inline tags

When any of the special characters mentioned above are included within a tag, the system does not automatically escape them. These characters don't require escaping if they're part of an inline tag.

When adding new tags in the translation

If a translator adds the character '<' while working in the rich mode without closing the tag in the translation text, Transifex assumes that everything after the opening tag ‘<' is part of an inline tag that hasn’t been closed yet and, therefore, nothing is escaped automatically.


HTML inline tags

The Transifex Android parser does not escape double or single quotes in the following HTML inline tags:

INLINE_TAGS = ("xliff:g", "a", "annotation", "b", "em", "i", "cite", "dfn", "big", "small", "font", "tt", "s", "strike", "del", "u", "sup", "sub", "ul", "li", "br", "div", "span", "p")


Developer comments

Transifex also supports developer comments in Android .xml files. A valid XML comment preceding any of the elements string, plurals, or string-array will appear as an instruction in the editor.

For instance, if your source file looks like this:

<resources> <!-- Type of entry: string --> <string name="localization_manager">Localization Manager</string> <!-- Type of entry: string-array --> <string-array name="account_details_array"> <item>username</item> <item>Email address</item> </string-array> <!-- Type of entry: plurals--> <plurals name="minutes_count"> <item quantity="one">%s minute</item> <item quantity="other">%s minutes</item> </plurals> </resources>

Your translators will find the above comments as instructions:

developer_notes_android_2.png#asset:4946


Download options

  • Download file to translate: Any untranslated entries will be returned empty so that translators can work just on the untranslated ones.

  • Download for use: All the entries that have not been translated yet won't be included in the file.

  • Download only reviewed translations: Only the reviewed entries will be included in the translation file. In case the Proofread step is enabled, only the translations that have been proofread will be exported instead.

  • Download for translation as XLIFF: The translation file will be generated in the .xliff format and include both translated and untranslated strings. The latter ones will be returned without containing target elements.

  • Download untranslated strings as XLIFF: The translation file will be generated in the .xliff format and include only the untranslated strings.

📝 Note: XLIFF support is only offered on the Growth plan and up.

download_options.png#asset:3087

In addition to the above Interface options, you can use the API or Client to download the translation files according to your localization needs.

  • For a more detailed description of the download modes, consult the table below:

📝 Note: Proofreading must be enabled for this logic to take effect. To learn how to enable proofreading, click here.


Default placeholders

These are the default placeholders that you could have in your file, and they will be recognized:

match: ['%1$s', '%(key1)s', '%s', '%d', '%.2f', '%-5d', '%+2d']


Additional Information


💡Tip

Looking for more help? Get support from our Transifex Community Forum!

Find answers or post to get help from Transifex Support and our Community.

Did this answer your question?