Android Localization: Complete Guide to Expanding Your App to New Markets

Android runs on many devices, in many regions. To reach the majority of users, make sure your app handles text, audio files, numbers, currency, and graphics in ways appropriate to the locales where it’s used.

This guide describes best practices for localizing Android apps. You should have basic knowledge of Kotlin or the Java programming language, and be familiar with Android resource loading, declaring UI elements in XML, development considerations such as activity lifecycle, and general internationalization and localization principles.

Overview: Resource Switching in Android

Resources are text strings, layouts, sounds, graphics, and any other static data that your Android app needs. An app can include multiple sets of resources, each customized for a different device configuration. When a user runs the app, Android selects and loads the resources that best match the device, all automatically.

This guide focuses on localization and locale. For a complete description of resource switching and all types of configurations you can specify, such as screen orientation or touchscreen type, see Providing Alternative Resources.

When you write the app, you create default and alternative resources for it to use. When users run the app, the Android system selects which resources to load based on the device’s locale setting. To create resources, place files inside subdirectories with special names within the res/ directory of your project.

Why Default Resources Are Important

When the app runs in any locale configuration for which you haven’t provided locale-specific text, Android loads the default strings from res/values/strings.xml. If this default file is absent or if any string needed by the app is missing, the app won’t run and displays an error.

AZbox Resource Management: AZbox helps ensure you never miss a translation by automatically detecting missing strings across all your resource files. When you add a new string to your default strings.xml, AZbox alerts you to translate it in all supported languages before deployment.

Use Resources for Localization

This section explains how to create default and alternative resources. It also explains how resources are prioritized and how to reference them in code.

Create Default Resources

Place your app’s default text in res/values/strings.xml. In these strings, use the default language, which is the language you expect most of your app’s users to speak.

The default resource set also includes any default layouts and drawables, and can include other types of resources, such as animations. These resources are located in the following directories:

• res/drawable/ (required directory containing at least one graphic file for the app icon on Google Play)
• res/layout/ (required directory containing an XML file that defines the default layout)
• res/anim/ (required if you have res/anim-<qualifiers> folders)
• res/xml/ (required if you have res/xml-<qualifiers> folders)
• res/raw/ (required if you have res/raw-<qualifiers> folders)

Tip: In code, examine each reference to an Android resource. Make sure a default resource is defined for each one. Also make sure the default string file is complete: a localized string file can contain a subset of strings, but the default string file must contain them all.

Create Alternative Resources

An important part of localizing an app is providing alternative text for different languages. In some cases, you might also provide graphics, sounds, layouts, and other locale-specific resources.

An app can specify many res/<qualifiers>/ directories, each with different qualifiers. To create an alternative resource for a different locale, you use a qualifier that specifies a language or a combination of language and region. The name of a resource directory must conform to the naming scheme described in Providing Alternative Resources; otherwise, your app won’t compile.

Streamline with AZbox: Managing multiple values-xx directories and keeping them synchronized can become overwhelming. AZbox automates this process:

• Automatic File Detection: AZbox automatically detects and imports your strings.xml files from all res/values-xx/ directories
• Centralized Management: Manage all translations in one place, regardless of which resource directory they’re in
• Version Control Integration: Sync your translations with your Git repository automatically
• Bulk Operations: Update multiple language files simultaneously

For a detailed step-by-step guide on implementing Android localization with Kotlin, see our complete Android translation guide.

Which Resources Take Priority?

If multiple resource files match a device’s configuration, Android follows a set of rules to decide which file to use. Among the qualifiers you can specify in a resource directory name, locale almost always takes priority.

Exception: The only qualifiers that take priority over locale in the selection process are Mobile Country Code (MCC) and Mobile Network Code (MNC).

Manage Strings for Localization

This section describes best practices for managing your localization-related strings.

Move All Strings to strings.xml

When you build your apps, don’t hardcode any strings. Instead, declare all strings as resources in a default strings.xml file, which makes them easy to update and localize. Strings in the strings.xml file can be extracted, translated, and integrated back into the app easily, with the appropriate qualifiers, without having to make changes to the compiled code.

If you generate images with text, place those strings in strings.xml as well and regenerate them after translation.

AZbox String Management: AZbox makes it easy to extract and manage all your strings:

• Automatic Extraction: Connect your repository and AZbox automatically extracts all strings from your strings.xml files
• Context Sharing: Upload screenshots to provide visual context for translators
• Translation Memory: Never translate the same string twice across projects
• Glossary Management: Maintain consistent terminology across all languages

Follow Android Guidelines for UI Strings

When designing and developing UIs, pay close attention to how you address the user. In general, use a concise, summary style that’s friendly but brief, and make it consistent across all UIs.

Make sure to read and follow Material Design recommendations for writing style and word choice. Doing so makes your apps feel more polished to users, in addition to helping them understand the UI more quickly.

Also, whenever possible, use standard Android terminology, such as UI elements like the app bar, options menu, system bar, and notifications. Correct and systematic use of Android terms makes translation easier and results in a better final product for users.

Provide Sufficient Context for Declared Strings

If you declare strings in the strings.xml file, make sure to describe the context in which the string is used. This information is invaluable to the translator and results in better-quality translation. It also helps you manage your strings more effectively.

AZbox Context Features: AZbox helps translators understand context better:

• Screenshot Context: Upload app screenshots to show where strings appear
• Code Context: See which activity or fragment uses each string
• Usage Tracking: Know which strings are most frequently used
• Comments: Add translator notes directly in the platform

Mark Parts of Messages That Shouldn’t Be Translated

Often, strings contain text that won’t be translated into other languages. Some common examples are a code snippet, a placeholder for a value, a special symbol, or a name. As you prepare strings for translation, look for and mark text that should remain as-is, without translation, so the translator doesn’t change it.

To mark text that won’t be translated, use an <xliff:g> placeholder tag. AZbox automatically detects and preserves these tags during translation, ensuring placeholders remain intact.

Localization Checklist

For a complete overview of the localization and distribution process for an Android app, see How to translate and localize your app.

Localization Tips

Follow these tips while localizing your app.

Design Your App to Work with Any Locale Configuration

Don’t assume anything about the device on which a user runs your app. The device might have hardware you didn’t expect, or it might be set to a locale configuration you didn’t plan for or can’t test. Design your app to work normally or fail gracefully, regardless of the device on which it runs.

Important: Make sure the app includes a complete set of default resources: include the res/drawable/ and res/values/ folders, with no additional modifiers in their names, that contain all the images and text the app needs.

The app won’t run on a device with an incompatible locale configuration if even a single default resource is missing. For example, if the default res/values/strings.xml file is missing a string needed by the app, when the app runs in an incompatible locale configuration and tries to load res/values/strings.xml, the user sees an error message and a button to force close.

AZbox Quality Assurance: AZbox helps prevent these issues:

• Missing Translation Detection: Automatically flags missing translations before deployment
• Placeholder Validation: Ensures all placeholders are correctly formatted
• String Length Validation: Alerts you when translations exceed UI constraints
• Resource Completeness Checks: Verifies all required resources are present

Create a Flexible Layout

If you need to rearrange the layout to fit a particular language, you can create an alternative layout for that language, such as res/layout-de/main.xml for a German layout. However, this can make maintaining your app more difficult. It’s better to create a single layout that’s more flexible.

AZbox Layout Support: While AZbox focuses on string localization, maintaining consistent layouts across languages is crucial. Use AZbox’s string length validation to ensure your UI can accommodate longer translations.

Avoid Creating More Resource Files and Text Strings Than You Need

You probably don’t need to create a locale-specific alternative for every resource in your app. For example, the layout defined in the res/layout/main.xml file might work with any locale configuration; in that case, you don’t need to create any alternative layout files.

Also, you might not need to create alternative text for every string. For example, suppose the following:

• The app’s default language is US English. Every string the app uses is defined in res/values/strings.xml with US English spelling.
• For some important phrases, you want the spelling to be British English. You want these alternative strings to be used when the app runs on a device in the UK.

To do this, create a small file called res/values-en-rGB/strings.xml that includes only the strings that are different when the app runs in the UK. For the rest of the strings, the app falls back to the default values and uses what’s defined in res/values/strings.xml.

AZbox Smart Management: AZbox helps you identify which strings actually need translation:

• Usage Analytics: See which strings are most frequently used
• Translation Priority: Focus on translating high-impact strings first
• Incremental Localization: Add languages gradually without overwhelming your team

Use Android Context Object for Manual Locale Lookup

You can look up the locale with the Context object that Android makes available to you:

Kotlin:

val primaryLocale: Locale = context.resources.configuration.locales[0]
val locale: String = primaryLocale.displayName

Java:

Locale primaryLocale = context.getResources().getConfiguration().getLocales().get(0);
String locale = primaryLocale.getDisplayName();

Use the App Translation Service

The App Translation Service is integrated into Play Console. It lets you get an instant quote and place an order with a translation company. You can request translations to one or multiple languages for app UI strings, Play Store listing text, IAP names, and ad campaign text.

AZbox Alternative: While Google’s App Translation Service is useful, AZbox provides more control and flexibility:

• Real-Time Collaboration: Work directly with translators in real-time
• Translation Memory: Reuse translations across projects to save time and money
• AI-Powered Suggestions: Get instant suggestions from DeepL and Google Translate
• Continuous Integration: Automatically sync translations with your codebase
• Over-the-Air Updates: Update translations in your app without waiting for Play Store approval using AZbox’s Android SDK

How to Test Localized Apps

Test your localized app on a device or in Android Emulator. In particular, test your app to make sure all necessary default resources are included.

Test on a Device

Keep in mind that the device on which you perform testing might be very different from devices available to consumers elsewhere. The locale configurations available on your device might be different from those available on other devices. Also, the device’s screen resolution and density might differ, which could affect the display of strings and UI design elements.

To change the locale or language on a device, use the Settings app.

Test in an Emulator

For details about using the emulator, see Run apps on the Android Emulator.

Create and Use a Custom Locale

A “custom” locale is a language or region combination that the Android system image doesn’t explicitly support. To test how your app runs in a custom locale, create a custom locale in the emulator.

AZbox Testing Tools: AZbox helps you test localizations more effectively:

• Pseudo-Localization: Test your UI with pseudo-localized strings to catch layout issues
• Translation Coverage Reports: See which languages have complete translations
• Missing String Alerts: Get notified when new strings are added but not yet translated

Test Default Resources

To test whether an app includes all the string resources it needs, do the following:

1. Set the emulator or device to a language your app doesn’t support. For example, if the app has strings in French in res/values-fr/, but doesn’t have strings in Spanish in res/values-es/, set the emulator locale to Spanish.
2. Run the app.
3. If the app displays an error message and a Force Close button, it might be looking for a string that isn’t available. Make sure the res/values/strings.xml file includes a definition for every string the app uses.

AZbox Pre-Deployment Checks: Before releasing your app, AZbox automatically:

• Verifies all default resources are present
• Checks for missing translations in supported languages
• Validates placeholder formatting
• Tests string lengths against UI constraints

Prepare for Global Markets

Investigate Market Factors

Market-specific demographics, such as population, language, and purchasing power, can help you better understand areas that might have an affinity or need for your app. Every market has its own preferences for the types of apps or categories customers most enjoy.

Consider selecting markets with similar attributes to those in which you have already established success, such as strong app downloads, sales, usage, or retention metrics, as this may make for easier growth.

Use Google Play Console Analytics

If you offer your app worldwide but haven’t localized for particular regions, you can look at key performance metrics, such as installs, active users, and retention, filtered by country. This can help you determine if your app is attracting users in a particular territory that might benefit from localization.

AZbox Analytics Integration: Track which languages generate the most engagement and prioritize your localization efforts accordingly. AZbox provides insights into translation usage and helps you make data-driven decisions about which markets to target next.

Consider Local Culture and Customs

While your app should provide a consistent experience across all markets, it’s sometimes valuable to refine certain elements for cultural relevance. For example, you might try incorporating market-specific content or cultural moments, such as special holiday content or regional art styles.

Localize Your App

Translate User-Visible Content

Use Android Studio’s built-in tools to extract all localizable content, including strings referenced from code, plurals resources, and layout files, as well as any localized assets. This process shouldn’t require modifications to your source code, making it easy to work on translations in-house or with an external localization service.

Enhance Your Workflow with AZbox: Instead of manually managing exported localization files, AZbox automates the entire process:

1. Automatic File Detection: AZbox automatically detects and imports your strings.xml and plurals.xml files from all res/values-xx/ directories
2. Real-Time Collaboration: Work with translators who can see context, screenshots, and previous translations
3. Translation Memory: Never translate the same string twice. AZbox remembers your translations and suggests them automatically
4. AI-Powered Suggestions: Get instant translation suggestions from DeepL and Google Translate, then refine with human translators
5. Over-the-Air Updates: Update translations in your app without waiting for Play Store approval using AZbox’s Android SDK

Be sure to also localize purpose strings for a consistent app experience, and consider localizing your privacy policy so that all users have a clear understanding of how their data may be handled.

Handle Pluralization

Android supports pluralization using plurals resources. Create a plurals.xml file for each language:

res/values/plurals.xml:

<plurals name="items_count">
    <item quantity="zero">No items</item>
    <item quantity="one">%d item</item>
    <item quantity="other">%d items</item>
</plurals>

AZbox Plural Support: AZbox automatically handles plural forms for all languages, ensuring correct grammar rules are applied based on each language’s pluralization rules.

Format Dates, Numbers, and Currency

Use Locale and formatting classes for localized formatting:

Dates:

val date = Date()
val formatter = SimpleDateFormat("EEEE, MMMM dd, yyyy", Locale.getDefault())
val localizedDate = formatter.format(date)

Numbers and Currency:

val number = 1234.56
val formatter = NumberFormat.getNumberInstance(Locale.getDefault())
val localizedNumber = formatter.format(number)

val amount = 1234.56
val currencyFormatter = NumberFormat.getCurrencyInstance(Locale.getDefault())
val localizedCurrency = currencyFormatter.format(amount)

Handle Right-to-Left (RTL) Languages

Android automatically handles RTL layouts when you use:

• start and end instead of left and right in XML
• paddingStart/paddingEnd instead of paddingLeft/paddingRight
• marginStart/marginEnd instead of marginLeft/marginRight

AZbox RTL Support: AZbox helps you test and validate RTL layouts by providing visual context and ensuring all strings are properly formatted for RTL languages.

Prepare for Launch

Localize Your Google Play Store Listing

Localize your Google Play Store metadata in Play Console — such as your app description, keywords, screenshots, and feature graphics — for each of the regions in which you offer your app. You can also translate your app’s name and tailor your keywords to reflect the values of each market so your app might better resonate with the local audience.

AZbox Play Store Integration: While AZbox focuses on in-app localization, maintaining consistent terminology between your app and Play Store listings is crucial. Use AZbox’s glossary feature to ensure your Play Store descriptions use the same terminology as your app.

International Payment Methods and Pricing

Google Play handles payment processing, so it’s easy to offer your content to users around the world. Users pay for your apps and in-app purchases with credit or debit cards, carrier billing, digital wallets, or Google Play gift cards, depending on regional availability.

When pricing your apps and in-app purchases, you’ll choose price points that are already adjusted appropriately for the market in each region.

Adapt Your Marketing Strategy

When launching your app in a new market, adapt your marketing strategy to the region to help your audience easily learn about your app and the value it provides. Research which social networks or other channels are most popular with local audiences, as these may vary significantly across markets.

Localize any materials you use in your marketing and user acquisition efforts, such as screenshots, banners, and advertisements.

Evaluate Success

Use Google Play Console Analytics to find out how customers discover and engage with your app, and filter this data by the territories in which you’ve expanded. See how many users discover your app while searching or browsing on Google Play and measure the percentage of views that result in a first-time download.

Find out if users continue to use your app, and see the number of installations, sessions, and active devices. Compare this data to that of other markets where your app has been available longer. You may find you need to adjust your marketing strategy or better localize your app to improve performance.

AZbox Performance Insights: Track which languages drive the most engagement and identify opportunities for improvement. AZbox’s analytics help you understand:

• Which translations are most frequently used
• Translation quality metrics
• Time-to-translation for new features
• Translator productivity and collaboration patterns

Once you’ve found success in your chosen markets, you can identify new markets and add additional localizations to provide a great user experience for even more customers.

Streamline Your Android Localization Workflow

While Android provides excellent built-in support for localization through resource files, managing translations across multiple languages, coordinating with translators, and keeping everything in sync with your codebase can become overwhelming as your app grows.

AZbox is designed specifically to solve these challenges:

• Seamless Integration: Connect your GitHub, GitLab, or Bitbucket repository and AZbox automatically syncs your strings.xml files from all res/values-xx/ directories
• Real-Time Collaboration: Work with translators in real-time, with built-in comments, context sharing, and review workflows
• Translation Memory: Never translate the same string twice. AZbox remembers all your translations and suggests them automatically
• AI-Powered Speed: Get instant translation suggestions from DeepL and Google Translate, then refine with human translators
• Over-the-Air Updates: Update translations in your app instantly without waiting for Play Store approval using AZbox’s Android SDK
• Quality Assurance: Automated checks catch missing translations, placeholder errors, and string length issues before they reach production
• Plural Support: Automatic handling of plural forms for all languages
• RTL Testing: Validate right-to-left layouts with visual context

For a detailed technical guide on implementing Android localization with Kotlin, including code examples and best practices, see our complete Android translation guide.

Ready to streamline your Android localization workflow? Start your free trial with AZbox and see how easy it is to manage translations for your Android app.