This tutorial connects Android strings.xml resources to Hyperlocalise Cloud. The CLI translates <string> and <plurals> resources while preserving comments, namespaces, attributes, and Android placeholders.
Prerequisites
You need:
- an Android app with resources under
app/src/main/res;
- the Hyperlocalise CLI;
- a Cloud project with
en as source and fr and de as targets; and
HYPERLOCALISE_API_KEY and HYPERLOCALISE_PROJECT_ID in your environment.
This tutorial uses language-only Android qualifiers:
For region-specific resources, use valid Android qualifiers such as values-fr-rFR or BCP 47 resource directories. Make the locale values in i18n.yml resolve to the exact directory names your app uses.
1. Define strings and plurals
Create or update app/src/main/res/values/strings.xml:
Use resources from Kotlin:
The parser exposes plural items as keys such as saved_filter_count.one and saved_filter_count.other. It skips resources marked translatable="false".
2. Map Android resource directories
Create i18n.yml:
Android resource paths are special. Hyperlocalise selects the Android parser only for files named strings.xml under res/values*.
3. Check source resources
Build the app and preview the upload:
Before merging, confirm:
- every UI literal lives in a string resource;
- formatting arguments use stable positional forms such as
%1$s;
- plural calls pass both the quantity and formatting value;
- non-user-facing values use
translatable="false"; and
- the file contains only supported translatable resource shapes.
Hyperlocalise fails on translatable <string-array> resources instead of silently dropping them. Move those entries into supported strings, split them into another file and workflow, or keep them outside this bucket.
4. Push and review resources
After merge:
Start translation with a Source upload automation or New Request. In Content Editor, review:
%1$s, %d, and <xliff:g> placeholders;- each target locale’s required plural categories;
- UI length on small screens;
- capitalization conventions for Android controls; and
- comments that explain where the resource appears.
Approve the target translations after review.
5. Pull and check target resources
Run:
The pull creates:
Comments, namespaces, attributes such as formatted, and translatable="false" resources remain intact. Hyperlocalise replaces only supported translatable values.
Open a translation pull request with these files.
6. Test Android resource resolution
Run:
Then change the emulator or device language and verify:
- Android loads the target
values-* directory.
- Every placeholder renders with a real value.
getQuantityString selects correct plural forms for 0, 1, 2, and larger values.- Text fits phones, tablets, and large font scales.
- Right-to-left layouts work when you add an RTL locale.
Keep translation pull requests behind the same build and screenshot tests as feature code.
Troubleshooting
Hyperlocalise treats the file as generic XML
The source and target must be named strings.xml and live under res/values*. Generic XML intentionally rejects Android <resources> files.
Pull fails on <string-array>
The Android parser supports <string> and <plurals>. It fails closed on unsupported translatable resource shapes so content cannot disappear unnoticed.
A locale falls back to the source
Check that the generated folder uses a valid Android qualifier and that the device locale matches it. Compare the resolved to path from hl sync pull --dry-run with the app’s resource tree.
Next
