Android Resources (.xml)
Arthur Ziborov avatar
Written by Arthur Ziborov
Updated over a week ago

Android string resources file provide text data for your application with optional styling and formatting. There can be three types of string resources: string, string-array, plurals.

Here is an example of how Android resource file should look:

<resources>
    <string name="simple_string">Hello world!</string>
    <string name="string_with_placeholders">Hello %s!</string>
    <string name="string_w" formatted="false">%s jobs in %s days</string>
    <string name="string_with_html_formatting">Hello <b>world</b>!</string>
    <string name="string_with_other_html"><![CDATA[<h1>Hello world!</h1>]]></string>
    <plurals name="plural_string">
        <item quantity="one">%s cat</item>
        <item quantity="other">%s cats</item>
    </plurals>
    <string-array name="array_of_strings">
        <item>Always</item>
        <item>When possible</item>
        <item>Never</item>
    </string-array>
</resources>

Key naming limitations

All keys must be named according to the following regexp: ^[a-zA-Z_$]+[a-z0-9_$A-Z]*.

In other words:

  • Keys must start with a Latin character, underscore, or a $ symbol.

  • Keys can contain Latin characters, underscores, $ symbols, and numbers.

Using improper naming might cause unexpected results upon exporting (certain key names might be trimmed or even replaced with an empty string).

String arrays

All keys with square brackets and indexes are converted to string-arrays. In the example above the keys are array_of_strings[0], array_of_strings[1] and array_of_strings[2].

Plurals

Plurals are created by defining a key as plural in the Lokalise editor. Android supports the following plural forms: zero, one, two, few, many, other.

Key descriptions

You can add key descriptions to the uploaded XML translation files in the following way:

<?xml version="1.0" encoding="UTF-8"?>
<resources>
<!-- Key description for "key1" goes here!-->
<string name="key1">This is the base language\'s text for key1.</string>
</resources>

To preserve key descriptions upon downloading, make sure to tick the Include description option under the Advanced settings section.

Custom key attributes

You can read more about custom key attributes for other formats in the Custom attributes section.

If you want to mark a key as translatable="false"  or force it to be exported as CDATA, you can do so via custom attributes in the Lokalise editor. Keep in mind, that if a key is marked as translatable="false". The following custom attributes are available for Android keys:

{
    "translatable": "false",
    "force-cdata": true
}

How such keys will be exported depends on the Empty translations setting under the Advanced tab on the Download page. Here are all possible scenarios:

  • Replace with base value — if you choose this option, all untranslatable keys will be included in the target language exports and their content will be the same as in the base language.

  • Export as empty strings — untranslatable keys will be not be exported for the target languages and no XML elements will be created for them. Empty strings will still be exported as empty strings and empty XML elements will be created in all languages.

  • Do not export — untranslatable keys will not be exported in the target languages and the same will happen to the empty strings. In the base language, empty keys will be skipped as well.

Exporting resources

When exporting Android string resources from Lokalise, our exporter automatically performs the following tasks:

  • Automatic text wrapping in CDATA if HTML tags are present with the exception of <a>, <b>, <i>, <u>, <font>, and <xliff> tags.

    • However, please note that the above exceptions is not applied in cases when you have any tag with placeholders. For example: Welcome, <b>%s</b> or %s, <b>welcome</b>. In these cases the text will be wrapped in CDATA.

  • Automatic conversion of line breaks to \n.

  • Automatic escaping of single/double quotes and other symbols. Please note that all special characters (#, &, /, \, ', " etc) will be escaped. The only exceptions are . and _. Dash - will be converted to _ automatically. In rare cases Lokalise might incorrectly unescape wrapping quotes, when they should have been escaped. To solve this, you can manually add slashes in the corresponding positions using the editor.

  • Automatic setting of the formatted="false" attribute if there is more than one non-positional placeholder present.

Did this answer your question?