Unicode and internationalization support

Android leverages the ICU library and CLDR project to provide Unicode and other internationalization support. This page's discussion of Unicode and internationalization support is divided into two sections: Android 6.0 (API level 23) and lower, and Android 7.0 (API level 24) and higher.

Unicode and internationalization support through Android 6.0 (API level 23)

The Android platform uses ICU and CLDR to implement various classes for handling both Latin and non-Latin orthographies, exposing classes like Locale, Character, and many subclasses of java.text. An app that requires internationalization functionalities beyond the exposed classes, and targets versions of the platform through Android 6.0 (API level 23), must include the ICU library.

Versioning

Successive releases of the Android platform correspond to newer versions of ICU and the corresponding CLDR and Unicode versions. Table 1 shows this correspondence through Android 6.0 (API level 23).

Table 1. ICU and CLDR versions used through Android 6.0 (API level 23).

The Android framework provides more comprehensive support for Unicode and internationalization for apps targeting Android 7.0 (API level 24) and higher. The next section of this page provides details about that support.

Unicode and internationalization support in Android 7.0 (API level 24) and higher

For Android 7.0 (API level 24) and higher, the Android platform exposes a subset of the ICU4J APIs for app developers to use under the android.icu package. ICU4J is an open-source, widely used set of Java libraries providing Unicode and internationalization support for software applications.

The ICU4J APIs use localization data present on the device. As a result, you can reduce your app's footprint by not compiling the ICU4J libraries into your app. Instead, you can call out to them in the framework. If you do this, you might want to provide multiple versions of your APK, so users running versions of Android lower than Android 7.0 (API level 24) can download a version of the app that contains the ICU4J libraries.

This section begins by providing some basic information on the minimum Android API levels required to support these libraries. It then explains what you need to know about the Android-specific implementation of ICU4J. Finally, it tells you how to use the ICU4J APIs in the Android framework.

ICU4J on Android

Android exposes a subset of the ICU4J APIs through the android.icu package, rather than com.ibm.icu. Some ICU4J APIs are not exposed by the Android framework, for reasons such as the APIs being deprecated or not declared stable. As the ICU team deprecates APIs in the future, Android also marks them as deprecated but continues to include them.

Here are a few reminders:

• The ICU4J Android framework APIs don't include all the ICU4J APIs.
• The APIs in the Android framework don't replace Android’s support for localizing with resources.
• In some cases, the Android framework supports more characters than the ICU libraries do. This is true, for example, of the android.text class's support for emoji.

Migrate to the android.icu package from com.ibm.icu

If you are already using the ICU4J APIs in your app, and the android.icu APIs meet your requirements, then migrating to the framework APIs requires you to change your Java imports from com.ibm.icu to android.icu. You can then remove your own copy of ICU4J files from the app.

Note: The ICU4J framework APIs use the android.icu namespace instead of com.ibm.icu. This is to avoid namespace conflicts in apps that contain their own com.ibm.icu libraries.

Migrate to android.icu APIs from other Android SDK APIs

Some classes in the java and android packages have equivalents to those found in ICU4J. However, ICU4J often provides broader support for standards and languages.

Table 2 shows some examples of these equivalencies to get you started:

Table 2.Android and Java ICU4J classes

ICU4C on Android

Android exposes a subset of the ICU4C APIs through the libicu.so library, rather than libicuuc.so or libicui18n.so. The APIs are available starting with Android 12 (API level 31). The NDK headers are available starting with the NDK release r22b. No C++ API is exposed through the Android NDK. Some of the C APIs are not available.

Versioning

Successive releases of the Android platform correspond to newer versions of ICU and the corresponding CLDR and Unicode versions. Table 3 shows this correspondence starting from Android 7.0 (API level 24).

Table 3. ICU and CLDR versions used in Android 7.0 (API level 24) and higher.

24h/12h Time format setting

val skeleton: String = if (DateFormat.is24HourFormat(context)) "Hm" else "hm"
val formattedTime: String = android.icu.text.DateFormat.getInstanceForSkeleton(
        skeleton,
        Locale.getDefault()).format(Date()
)

String skeleton = DateFormat.is24HourFormat(context) ? "Hm" : "hm";
String formattedTime = android.icu.text.DateFormat.getInstanceForSkeleton(skeleton, Locale.getDefault()).format(new Date());

Stability of Transliterator

Licensing

ICU4J is released under the ICU license. For details, see the ICU user guide.