Compose Multiplatform Resources XML

Compose Multiplatform Resources XML files (usually found in composeResources/values/{languageCode}.xml) can be used to store localization (i18n) data. It is similar to Android Resources XML files but has some specific differences in escaping and placeholder handling. It supports plurals and arrays. To read more about using resources in your Compose Multiplatform application in general, read the official Compose Multiplatform documentation.

Example

<resources>
    <string name="user_settings_password_label">
      Password
    </string>
    <plurals name="dogs_count">
        <item quantity="one">%1$d dog</item>
        <item quantity="other">%1$d dogs</item>
    </plurals>
    <string-array name="string_array">
        <item>First item</item>
        <item>Second item</item>
    </string-array>
</resources>

File structure

The Compose Multiplatform Resources XML file is an XML-based file. When used for storing translations, it can contain these elements:

• resources

  • the root element of the file.

• string

  • a simple string value.

• plurals

  • a string that has different forms based on the quantity

  • attributes:

    • quantity: the plural keyword

      Possible keywords: zero, one, two, few, many, other.

      Get the full list of the keywords for each language here.

The MessageFormat and placeholder conversion

When importing data to Tolgee from the Compose Multiplatform XML files, you can turn the conversion to the Tolgee Universal ICU placeholders on or off. The conversion is enabled by default. You can also turn off the conversion globally in project settings by disabling the Use Tolgee Universal ICU placeholders option. We recommend keeping the conversion enabled, as it brings many benefits. Read more about the benefits of Tolgee Universal ICU placeholders.

When the conversion is disabled, the original placeholders like %1$s, %1$d etc. are preserved.

Placeholder conversion specification

The Java documentation about format specifiers can be found here

Only specifiers specified in the table below are supported. Tolgee doesn't support additional flags and modifiers and placeholders using them are not converted.

Specifier	ICU type	Example	Converted to ICU	Note
%	N/A	%%	%	%% is the way how to render %, in ICU we don't have such concept, so we just add %. When exporting, the % is converted back to %%.
s	none	%s	{0}
d	number	%d	{0, number}
f	number, [precision string]	%f	{0, number, 0.000000}	By default %f uses 6 decimal places, that's why we convert it to the number with such precision. %.2 f would be {0, number, 0.00} and so on.
e	number, scientific	%e	{0, number, scientific}	%E is not supported

Java also supports n$ positional specifiers. They are converted to the zero-based argument index. E.g. I am %2$@, and I have %1$lld dogs. is converted toI am {1} and I have {(0, number)} dogs.

Exporting

When exporting the data back to the .xml file, the placeholders are converted back to the original format.

Array support

When importing data to Tolgee from the Compose Multiplatform XML files, the array elements are converted into flat keys with arrayName[index] format.

For example, the following XML:

<resources>
 <string-array name="string_array">
        <item>First item</item>
        <item>Second item</item>
 </string-array>
</resources>

will be imported to Tolgee as

{
  "string_array[0]": "First item",
  "string_array[1]": "Second item"
}

and vice versa when exporting from Tolgee to the Compose Multiplatform Resources XML file.

Since the [ and ] characters are not allowed in the key names in the Compose Multiplatform Resources XML files, there should be no conflicts if you use the Tolgee project only for the Compose Multiplatform app. Otherwise, remember that keys named with the described syntax are converted to arrays.

Strings wrapped with CDATA

When Tolgee imports the Compose Multiplatform Resources XML file, it extracts the strings from the CDATA sections. e.g. <string><![CDATA[Hello]]></string> is imported as Hello. Keys with imported translations with CDATA-wrapped values are marked with _androidWrapWithCdata custom value (this is for legacy reasons as the Android format was the first to introduce the CDATA wrapping). When exporting, keys marked with _androidWrapWithCdata are wrapped with CDATA.

Tolgee does this because its primary goal is to enable users to use the same translation data on multiple platforms (e.g., Web, Android, Apple). So we have to strip all the additional syntax, which is removed by the XML Resources parser.

However, when Tolgee removes this syntax, without the androidWrapWithCdata custom value, it wouldn't be able to build the Resources XML resource file without possibly breaking the App.

Escaping

When importing data Tolgee unescapes escaped backslash \\, new line \n and tab (\t) characters. When exporting, these characters are escaped back. e.g. \\ is imported as \ etc. Other characters (e.g. escaped unicode characters like \u0020) are not unescaped.

Importing keys with tags

Unless the string is wrapped with CDATA, all tags are removed when importing data to Tolgee to match the functionality of the default stringResource function.

Tags and Placeholders

When the value contains XML tags and placeholders at the same time, it's always wrapped with CDATA when exported.

Importing / Exporting in general

To read more about importing and exporting with Tolgee, continue to import section or export section.