{"id":7231,"date":"2026-02-12T09:24:55","date_gmt":"2026-02-12T09:24:55","guid":{"rendered":"https:\/\/poeditor.com\/blog\/?p=7231"},"modified":"2026-02-25T11:53:51","modified_gmt":"2026-02-25T11:53:51","slug":"android-localization","status":"publish","type":"post","link":"https:\/\/poeditor.com\/blog\/android-localization\/","title":{"rendered":"A practical guide to Android localization with string resources"},"content":{"rendered":"\n
\"\"<\/figure>\n\n\n\n

Android provides a built-in localization system<\/a> based on string resources. By defining user-facing text in XML files and organizing them by locale, Android can automatically load the correct translations at runtime based on the user\u2019s language settings.<\/p>\n\n\n\n

In most apps, this starts with <string><\/code> entries in strings.xml<\/code>. However, for real-world use cases, you also have to deal with pluralized strings, values that shouldn\u2019t be translated, and collections of strings defined as arrays.<\/p>\n\n\n\n

This guide walks through localizing an Android application that includes standard <string><\/code> resources, pluralized strings using <plurals><\/code>, non-translatable values using translatable=\"false\"<\/code> and a string-array<\/code> defined in a separate file and populated using references.<\/p>\n\n\n\n

How Android handles localized string resources<\/h2>\n\n\n\n

Android handles localization through its resource system. Instead of switching languages in code, you provide multiple versions of the same resource, and Android selects the appropriate one at runtime based on the user\u2019s language settings.<\/p>\n\n\n\n

For strings, this is done using resource directories under res\/values<\/code>. Every Android project includes a default values<\/code> directory:<\/p>\n\n\n\n

res\/\n\u2514\u2500 values\/\n   \u2514\u2500 strings.xml\n<\/code><\/pre>\n\n\n\n
This file represents the app\u2019s base language. If Android cannot find a localized version of a string for the current locale, it falls back to the value defined here.<\/p>\n\n\n\n
Because of that, res\/values\/strings.xml<\/code> should always be complete. Any string that may appear in the UI should exist in this file, even if translations are provided elsewhere.<\/p>\n\n\n\n
Locale-specific string resources<\/h3>\n\n\n\n
To support additional languages, you add locale-specific values-*<\/code> directories alongside the default one:<\/p>\n\n\n\n
res\/\n\u251c\u2500 values\/\n\u2502  \u2514\u2500 strings.xml\n\u251c\u2500 values-es\/\n\u2502  \u2514\u2500 strings.xml\n\u2514\u2500 values-ar\/\n   \u2514\u2500 strings.xml\n<\/code><\/pre>\n\n\n\n
Each directory contains a translated version of strings.xml<\/code>. The file name stays the same, but the folder name and the string values change.<\/p>\n\n\n\n
When the app runs, Android checks the user\u2019s preferred language and loads the matching resource set automatically. On Android 13<\/a> and later, users can also choose a language specifically for an app from system settings. This doesn\u2019t change how resources are defined or resolved.<\/p>\n\n\n
Improve your localization process<\/h3>Discover an easy to use and affordable localization app.<\/span><\/div>Get started<\/a><\/div>\n\n\n\n
Create a new Android project<\/h2>\n\n\n\n
In Android Studio<\/a>, create a new project with the Empty Activity<\/strong> template. Also select the Kotlin<\/strong> language and use minimum SDK<\/a> of API 24 or higher<\/strong>. API 24 is sufficient for everything covered in this guide and avoids extra compatibility code that isn\u2019t relevant to localization.<\/p>\n\n\n\n
You can give your project any name and then click Finish<\/strong>.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Once the project is created, you should have a structure similar to this:<\/p>\n\n\n\n
app\/\n\u2514\u2500 src\/\n   \u2514\u2500 main\/\n      \u251c\u2500 java\/ (or kotlin\/)\n      \u2502  \u2514\u2500 MainActivity.kt\n      \u2514\u2500 res\/\n         \u2514\u2500 values\/\n            \u2514\u2500 strings.xml\n<\/code><\/pre>\n\n\n\n
At this point, strings.xml<\/code> will contain only a default app_name<\/code> entry, and the UI will likely be showing placeholder text generated by the template.<\/p>\n\n\n\n
Localizing standard string resources<\/h2>\n\n\n\n
With the basic UI in place, the first step toward localization is to move user-facing text out of the code and into string resources.<\/p>\n\n\n\n
Android does not translate anything automatically. If a string is hardcoded in code or in a layout, Android has no way to replace it for different locales. To make a string localizable, it must live in a resource file.<\/p>\n\n\n\n
Open res\/values\/strings.xml<\/code>. You should see a file similar to this:<\/p>\n\n\n\n
<resources>\n    <string name=\"app_name\">Demo Localization<\/string>\n<\/resources><\/code><\/pre>\n\n\n\n
We\u2019ll start by adding a few basic strings that will be displayed on screen. Update the file as follows:<\/p>\n\n\n\n
<resources>\n    <string name=\"app_name\">Demo Localization<\/string>\n\n    <string name=\"name\">John Doe<\/string>\n    <string name=\"title\">Android Developer<\/string>\n    <string name=\"bio\">\n        A passionate developer who loves building beautiful and functional Android apps.\n    <\/string>\n<\/resources>\n\n<\/code><\/pre>\n\n\n\n
Each string is defined using a unique name. These names are what you\u2019ll reference from code. The actual text values are what will change per language.<\/p>\n\n\n\n
Referencing string resources in code<\/h3>\n\n\n\n
Next, update MainActivity.kt<\/code> to read strings from resources instead of hardcoding them. Replace the previous contents of MainActivity.kt<\/code> with this:<\/p>\n\n\n\n
package com.example.demolocalization\n\nimport android.os.Bundle\nimport androidx.activity.ComponentActivity\nimport androidx.activity.compose.setContent\nimport androidx.compose.foundation.layout.Column\nimport androidx.compose.foundation.layout.padding\nimport androidx.compose.material3.MaterialTheme\nimport androidx.compose.material3.Surface\nimport androidx.compose.material3.Text\nimport androidx.compose.ui.Modifier\nimport androidx.compose.ui.res.stringResource\nimport androidx.compose.ui.unit.dp\n\nclass MainActivity : ComponentActivity() {\n    override fun onCreate(savedInstanceState: Bundle?) {\n        super.onCreate(savedInstanceState)\n\n        setContent {\n            Surface(color = MaterialTheme.colorScheme.background) {\n                Column(modifier = Modifier.padding(16.dp)) {\n                    Text(text = stringResource(R.string.name))\n                    Text(text = stringResource(R.string.title))\n                    Text(\n                        text = stringResource(R.string.bio),\n                        modifier = Modifier.padding(top = 8.dp)\n                    )\n                }\n            }\n        }\n    }\n}\n\n<\/code><\/pre>\n\n\n\n
Note:<\/strong> The package name used in the code examples (com.example.demolocalization<\/code>) will depend on how you created your project. If your package name is different, make sure the package<\/code> declaration at the top of your Kotlin files matches your project\u2019s namespace.<\/p>\n\n\n\n
The key change here is the use of stringResource(...)<\/code>. This tells Compose to fetch the string value from Android\u2019s resource system instead of using a literal value.<\/p>\n\n\n\n
At runtime, Android resolves the string based on the current locale.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Adding a second language<\/h3>\n\n\n\n
In your project, right-click the res folder and select New<\/strong> > Android Resource Directory<\/strong>. A modal appears, use strings as the file name, ensure the Resource type<\/strong> is set to values. Then for the Available qualifiers<\/strong>, click Locales<\/strong> and the arrow shown below:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
This loads up all languages and then you can select your preferred language, leave the region as Any Region<\/strong> and then click the OK<\/strong> button. You will notice that the Directory name changes to use values-*<\/code>:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Note:<\/strong> Android Studio\u2019s Android<\/em> view groups locale-specific resource files together. Even though strings.xml (es)<\/code> and strings.xml (ar)<\/code> appear under the same values node, they are stored in separate values-es<\/code> and values-ar<\/code> directories on disk.<\/p>\n\n\n\n
Inside the new strings.xml<\/code> file, add the same string keys, but with translated values:<\/p>\n\n\n\n
<resources>\n    <string name=\"app_name\">Demo Localization<\/string>\n\n    <string name=\"name\">Juan P\u00e9rez<\/string>\n    <string name=\"title\">Desarrollador de Android<\/string>\n    <string name=\"bio\">\n        Un desarrollador apasionado al que le encanta crear aplicaciones de Android hermosas y funcionales.\n    <\/string>\n<\/resources>\n<\/code><\/pre>\n\n\n\n
The important rule here is that the string names must match exactly. Android uses the name to look up the value; the folder determines which language version is used.<\/p>\n\n\n\n
Verifying the result<\/h3>\n\n\n\n
Run the app with the device or emulator language set to English and then to Spanish.<\/p>\n\n\n\n
\"\"<\/figure>
\n
<\/p>\n<\/div><\/div>\n\n\n\n
You should see the same UI, but with text changing automatically based on the selected language.<\/p>\n\n\n\n
Handling plural strings with <plurals><\/code><\/h2>\n\n\n\n
Simple string replacement isn\u2019t enough when text depends on a number. Different languages have different grammatical rules for quantities, and handling that logic manually in code doesn\u2019t scale.<\/p>\n\n\n\n
Android solves this with plural resources, defined using the <plurals><\/code> element. This lets you define all grammatical variants of a string in one place and have Android select the correct one at runtime.<\/p>\n\n\n\n
Open the default res\/values\/strings.xml<\/code> file and add a plural definition for a project count:<\/p>\n\n\n\n
<plurals name=\"project_count\">\n    <item quantity=\"one\">%d project<\/item>\n    <item quantity=\"other\">%d projects<\/item>\n<\/plurals><\/code><\/pre>\n\n\n\n
Here project_count<\/code> is the resource name, %d<\/code> is a placeholder for the number, one and other are plural categories used by English.<\/p>\n\n\n\n
Android follows CLDR plural rules<\/a> under the hood, so the categories you define depend on the language.<\/p>\n\n\n\n
Using plurals in Compose<\/h3>\n\n\n\n
To use this plural resource in code, update MainActivity.kt<\/code> to include a numeric value and fetch the plural string using pluralStringResource()<\/code>.Update the content inside setContent<\/code> as follows:<\/p>\n\n\n\n
import androidx.compose.ui.res.pluralStringResource\n\nval projectCount = 5\n\nText(\n    text = pluralStringResource(\n        id = R.plurals.project_count,\n        count = projectCount,\n        projectCount\n    )\n)<\/code><\/pre>\n\n\n\n
The count<\/code> argument determines which plural form Android selects, while the final argument supplies the value for the %d<\/code> placeholder.<\/p>\n\n\n\n
Adding translations for plurals<\/h3>\n\n\n\n
Just like regular strings, plural resources must be translated per locale. Open res\/values-es\/strings.xml<\/code> and add a Spanish version:<\/p>\n\n\n\n
<plurals name=\"project_count\">\n    <item quantity=\"one\">%d proyecto<\/item>\n    <item quantity=\"other\">%d proyectos<\/item>\n<\/plurals><\/code><\/pre>\n\n\n\n
The resource name stays the same. Only the values change.<\/p>\n\n\n\n
Languages with complex plural rules<\/h3>\n\n\n\n
Some languages require more plural categories than English. Arabic, for example, defines categories such as zero<\/code>, one<\/code>, two<\/code>, few<\/code>, many<\/code>, and other.<\/code><\/p>\n\n\n\n
In res\/values-ar\/strings.xml<\/code>, the same plural resource might look like this:<\/p>\n\n\n\n
<plurals name=\"project_count\">\n    <item quantity=\"zero\">\u0644\u0627 \u0645\u0634\u0627\u0631\u064a\u0639<\/item>\n    <item quantity=\"one\">\u0645\u0634\u0631\u0648\u0639 \u0648\u0627\u062d\u062f<\/item>\n    <item quantity=\"two\">\u0645\u0634\u0631\u0648\u0639\u0627\u0646<\/item>\n    <item quantity=\"few\">%d \u0645\u0634\u0627\u0631\u064a\u0639<\/item>\n    <item quantity=\"many\">%d \u0645\u0634\u0631\u0648\u0639\u064b\u0627<\/item>\n    <item quantity=\"other\">%d \u0645\u0634\u0631\u0648\u0639<\/item>\n<\/plurals><\/code><\/pre>\n\n\n\n
Android selects the correct form automatically based on the number and the current locale.<\/p>\n\n\n\n
Using placeholders in localized strings<\/h2>\n\n\n\n
In addition to static text and plurals, Android string resources can also contain placeholders. Placeholders allow you to inject dynamic values into a localized string at runtime, while still keeping the full sentence translatable.<\/p>\n\n\n\n
This is commonly used for greetings, labels that include user input, or messages that reference dynamic values such as names or titles. They are defined directly in strings.xml <\/code>using standard formatting tokens, such as %s<\/code> for strings.<\/p>\n\n\n\n
In the default res\/values\/strings.xml<\/code>, add the following entry:<\/p>\n\n\n\n
<string name=\"greeting\">Hello %s<\/string><\/code><\/pre>\n\n\n\n
Next, add translated versions in your locale-specific files. For Spanish (res\/values-es\/strings.xml<\/code>):<\/p>\n\n\n\n
<string name=\"greeting\">Hola %s<\/string><\/code><\/pre>\n\n\n\n
The placeholder itself stays the same across languages. What changes is the surrounding text and, if needed, the position of the placeholder within the sentence.<\/p>\n\n\n\n
To use a string with placeholders in Jetpack Compose, you pass the dynamic values directly to stringResource()<\/code>. For example, to display a greeting that includes the user\u2019s name:<\/p>\n\n\n\n
Text(\n    text = stringResource(\n        R.string.greeting,\n        stringResource(R.string.name)\n    )\n)<\/code><\/pre>\n\n\n\n
When you run the app and switch the device or emulator language. You should see the greeting update automatically, for example:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Excluding strings from translation<\/h2>\n\n\n\n
Not every string in an Android app should be translated. Brand names, company names, product identifiers, and certain technical terms are often meant to stay the same across all languages.<\/p>\n\n\n\n
Android allows you to explicitly mark these values using the translatable=\"false\"<\/code> attribute:<\/p>\n\n\n\n
<string name=\"brand_name\" translatable=\"false\">Acme Corp<\/string><\/code><\/pre>\n\n\n\n
This tells both Android and any localization tools that the string should be ignored during translation.<\/p>\n\n\n\n
Using non-translatable strings in code<\/h3>\n\n\n\n
You reference non-translatable strings the same way as any other string resource. For example, in Compose:<\/p>\n\n\n\n
Text(text = stringResource(R.string.brand_name))<\/code><\/pre>\n\n\n\n
Note:<\/strong> Strings marked with translatable=\"false\"<\/code> should exist only in the default values directory. There\u2019s no reason to duplicate them in locale-specific folders, and doing so can cause confusion in translation workflows. This pattern works well with localization platforms like POEditor<\/a>. Since these tools usually import strings.xml<\/code>, marking non-translatable strings explicitly prevents them from being flagged or accidentally translated.<\/p>\n\n\n\n
Defining a string-array in a separate file<\/h2>\n\n\n\n
In addition to individual strings, Android also supports string arrays. These are useful when you need a fixed list of related values, such as menu options, labels, or system-defined items.<\/p>\n\n\n\n
A string-array<\/code> is defined using the <string-array><\/code> element and contains multiple <item><\/code> entries. By default, these arrays are often placed directly in strings.xml, but that you can also manage them separately, if the localization tool you\u2019re working with does not support arrays.<\/p>\n\n\n\n
There are multiple advantages to keeping all translatable text in strings.xml<\/code> and referencing strings to string array items, including:<\/p>\n\n\n\n