Skip to main content
This tutorial connects Android strings.xml resources to Hyperlocalise Platform. The CLI translates <string> and <plurals> resources while preserving comments, namespaces, attributes, and Android placeholders. You can also upload a strings.xml file on the project Files page; other .xml names use the generic XML parser.

​
Prerequisites

You need:
  • an Android app with resources under app/src/main/res;
  • the Hyperlocalise CLI;
  • a Platform 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:
  1. Android loads the target values-* directory.
  2. Every placeholder renders with a real value.
  3. getQuantityString selects correct plural forms for 0, 1, 2, and larger values.
  4. Text fits phones, tablets, and large font scales.
  5. 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