Localize an Android app
Translate Android resources, place them in the correct locale directories, and verify the messages in the app.
Android chooses localized text from resource directories while application code continues to use the same resource names. Lingo.dev translates those resources into the target directories. A useful first change takes one greeting, one list, and one plural from the default resource file to a screen running in another locale.
Use this procedure for native Android XML. For Flutter, follow ARB resources and generated localization code; for JSON catalogs, follow React Native localization.
Prepare the resources the screen loads #
Keep default resources in app/src/main/res/values/strings.xml:
<resources>
<string name="welcome">Welcome, %1$s!</string>
<string name="product_name" translatable="false">ExampleApp</string>
<string-array name="delivery_options">
<item>Standard delivery</item>
<item>Express delivery</item>
</string-array>
<plurals name="items_count">
<item quantity="one">%d item</item>
<item quantity="other">%d items</item>
</plurals>
</resources>Connect these resources to the screen through the application's existing resource calls. welcome identifies the message; %1$s accepts the name supplied by code. The plural resource needs the count for selection and formatting. translatable="false" keeps the product name outside translation work.
The Android file handler selects plain-text items and skips mixed inline child markup. If a message contains child elements such as <b> or <xliff:g>, account for those entries separately. CDATA text can be translated while keeping its wrapper; markup inside it is text rather than protected child structure. Check rich resources through the application's actual renderer.
Configure source selection and locale paths #
From the project root, install and link the CLI:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,pt-BR,zh-Hans --files 'app/src/main/res/values/strings.xml' --yes
lingo linkIn .lingo/config.json, keep the linked organization and localization engine IDs, then set the file's format explicitly:
{
"pattern": "app/src/main/res/values/strings.xml",
"format": "android"
}Use that object as the file entry. The .xml extension alone cannot distinguish Android from another XML vocabulary. Add source entries for other resource files, such as arrays.xml, without including generated target directories.
The current CLI recognizes the unqualified values/ directory and renders Android qualifiers for target paths:
| Target locale | Target directory |
|---|---|
es | values-es |
pt-BR | values-pt-rBR |
zh-Hans | values-b+zh+Hans |
A values-en symlink is unnecessary for this layout. If an older configuration used one, update and inspect the configuration before removing it. A raw directory such as values-pt-BR does not use the expected regional qualifier. CLI configuration covers explicit target paths and locale spelling.
Translate and load the first target #
For missing target files, run:
lingo push --backfill-missing --waitWait for the run to finish, including any configured review, and inspect the retrieved XML. Compare resource names, array order, quantity attributes, the fixed product name, and format specifiers with the source. Without --wait, retrieve the completed run with lingo pull in the submitting checkout.
Build with the project's Gradle configuration, then run the app on a device or emulator in a target locale. Open the screen and supply a name and several counts. A successful build checks resource syntax and references; the device check confirms that Android actually selected the translated directory.
Read the output for counts that exercise the target language's plural categories. The handler retains source plural structure, so English one and other do not establish complete target-language forms. Check long labels, accessibility text, and right-to-left layout where required. lingo check does not replace Android resource or completeness checks.
Continue with source changes #
Commit the source, accepted targets, linked configuration, and .lingo/lock.json together. After editing source strings, translate the changes with:
lingo push --waitTo regenerate every translation in one source file after changing engine guidance, save the accepted targets and run:
lingo push "app/src/main/res/values/strings.xml" --force --waitThis replaces the selected file's translations in the configured target locales. See CLI scopes for file selection and regeneration.
Keep a before-and-after target diff. Mark fixed Android resources with translatable="false", as in the product-name example above. Save existing corrections before a refresh. To detect target edits made after submission, omit --wait and inspect lingo pull --dry-run before retrieval. Preserve reviewed translations explains this check and conflict handling.
After one screen works, use the GitHub App or a CI runner for recurring translation. The runner owns authentication and reviewable writeback; Android builds and representative screen checks still belong before acceptance. Translations committed elsewhere arrive through version control, while lingo pull retrieves the locally recorded submission.