Localize Strings

The Android resource framework provides localization support. On top of the standard Android resource framework, TomTom Digital Cockpit provides additional tooling and additional metadata to facilitate localization.

Example application

To try it out, see the examples/examples_localizestrings application. This example project uses the default frontends and services from the TomTom Digital Cockpit platform and app suite. It also has the com.tomtom.tools.android.extractstringsources Gradle plugin applied (see Download string resource source files for details). Run:

./gradlew :examples_localizestrings_app:extractStringSources

The above command will download and extract all strings.xml files from modules in the artifact group com.tomtom.uxstrings used by the default frontends and services from the TomTom Digital Cockpit platform and app suite. After running the above command, you can find the downloaded files in the examples/localizestrings/app/build/string-sources directory.

From these files, you can create your own localized strings. The example project demonstrates this for the Media text in the menu bar:

• The string in src/main/res/values-fr-rCA/strings.xml is used when the Android language is set to French (Canada).
• The string in src/main/res/values-fr-rFR/strings.xml is used when the Android language is set to French (France) or other regions, like French (Algeria).
• The string in src/main/res/values-nl/strings.xml is used when the Android language is set to Dutch, no matter which region.

The British English version of the strings and the default value come included with the Digital Cockpit platform, so these are not included in the example application.

See Localize string resources to provide additional localizations.

Android resource framework localization support

Localize string resources

To localize strings see the Android localization documentation.

In a nutshell, provide alternative string resource values in a res/values-<qualifier>/strings.xml file per locale. See table 2 of Providing Alternative Resources for more information about the locale qualifier.

See Android String resources documentation for more information about how to define a string resource.

Using localized strings resources

See Language and locale resolution overview and Testing localized apps.

Additional tooling and metadata to facilitate localization

To facilitate (additional) localizations, TomTom Digital Cockpit platform provides additional tooling to discover the strings used in the IVI system. For strings, that can be visible to the end user, additional metadata is provided to provide additional context. The context describes how the string is used and where.

Download string resource source files

String resources are defined in strings.xml source files. You can download and extract the strings.xml sources files from dependencies used in your Android Application by running a Gradle task. This requires the com.tomtom.tools.android.extractstringsources Gradle plugin to be applied in your Android Application Gradle subproject. In this tutorial we refer to the Android Application Gradle subproject with app.

To apply the Gradle plugin define the following in your app/build.gradle.kts file:

1plugins {
2    id("com.tomtom.tools.android.extractstringsources")
3}

For this to work, you need to configure the version of this Gradle plugin. Add the following in your top-level build.gradle.kts file:

1plugins {
2   id("com.tomtom.tools.android.extractstringsources") apply false
3}

And a dependency to com.tomtom.tools.android:gradle-plugins:<version> in your buildSrc/build.gradle.kts file. For example:

1dependencies {
2    implementation(iviDependencies.gradlePluginTomtomTools)
3}

Next you can run Gradle task :app:extractStringSources. By default this will download and extract all strings.xml files from modules in the artifact group com.tomtom.uxstrings based on the dependencies used in your Android application. You can find the files in app/build/string-sources. Usually the following files are generated:

• Files app/build/string-sources/<group>:<module>:<version>/values/strings.xml contain the string resource definitions used in the default local (U.S. English).
• Files app/build/string-sources/<group>:<module>:<version>/values-en-rGB/strings.xml contain the British English localizations of the same strings.

Note: When a language-and-region string (for example values-en-rUS) is not provided, Android looks for a string with the correct language (for example values-en or values-en-rUK) before it falls back to the default string (read from values).

TomTom defines strings in British English. If the U.S. English localization for a string is not (yet) provided by TomTom, Android will use the British English string definition and not the default string.

Download string resource source files configuration

Without any additional configuration, Gradle task extractStringSources downloads and extracts all strings.xml files from modules in the artifact group com.tomtom.uxstrings. You can configure the plugin to download and extract strings.xml files from other Android Library source archives by configuring the plugin in the app/build.gradle.kts file. For example:

1ttExtractStringSources {
2    includeComponentIds.add("somegroup:somelibrary:*")
3}

The above configures Gradle task :app:extractStringSources to download and extract the strings.xml files from all modules in the artifact group com.tomtom.uxstrings and from the library somelibrary in the somegroup artifact group. For this to work, the Android libraries have to publish the strings.xml files as part of their sources archive (*-sources.jar).

Additional metadata

String resources defined in TomTom Digital Cockpit, which are visible to the end user, have additional metadata. This provides additional context per string resource to facilitate translations. For example:

1<resources xmlns:tomtom="http://www.tomtom.com/metadata">
2    <string name="ttivi_bluetoothconnectivity_availabledevices"
3      tomtom:description="Shown while searching for Bluetooth devices when at least one device is available."
4      tomtom:reviewed="yes"
5      tomtom:translate="yes"
6      tomtom:use="Text">Available devices</string>
7    <!-- ... -->
8</resources>

In the above example, a string resource ttivi_bluetoothconnectivity_availabledevices with text Available devices is defined. The tomtom: namespace attributes are added to provide more context. The following table describes each attribute:

Possible values for the use attribute: