How to Localise a Trusted Web Activity for Google Play

When launching an application globally, localising the user experience is vital for user acquisition and retention. If your service supports multiple languages, simply translating your web application is only half of the journey. Because a Trusted Web Activity (TWA) is distributed via native app stores, you must manage localisation across both the native Android layer and your remote web application.

A mismatched language experience, where a user downloads a Spanish-localised listing from the Google Play Store, launches an app with a Spanish title, but is greeted by an English web interface, harms engagement. Aligning these layers ensures a seamless transition from the initial app store impression to daily usage.

The Two-Layer Localisation Strategy

To deliver a fully localised experience, you must coordinate translation efforts across both structural environments of a TWA:

Step 1: Localising the Native Android Shell

The native Android shell contains metadata that the mobile operating system displays before your web content has loaded. This includes the app's name underneath the launcher icon and any custom app shortcuts configured on the home screen.

To localise these strings, you must avoid hardcoding values inside your primary configuration. Instead, reference string resources. In your default /res/values/strings.xml file, declare your fallback language (usually English):

<resources>
<string name="app_name">My Application</string>
</resources>

To support a second language, such as Spanish, you create an alternative resource directory named /res/values-es/ and place a translated strings.xml file inside it:

<resources>
<string name="app_name">Mi Aplicación</string>
</resources>

When the user installs the application, Android automatically reads their system locale. If their device is set to Spanish, the operating system uses the string from values-es. If they use a language you have not explicitly translated, Android seamlessly falls back to the default values directory.

Step 2: Syncing the User Locale with the Web App

Once the user launches the application, the TWA transitions control to your web application hosted on your remote server. Your server and client-side JavaScript must quickly determine the correct language to display. There are three primary methods to pass the language context from the Android shell to the web app.

Method A: Reading System Locales via JavaScript

The simplest approach requires no custom native development. Because the TWA runs inside Chromium, standard web APIs are fully operational. You can read the user's system language preference directly using client-side JavaScript:

const userLanguage = navigator.language || navigator.userLanguage;
console.log('Target locale is: ' + userLanguage);
// Load appropriate translations based on userLanguage

This method automatically matches the device's system settings. If the user changes their system language, the PWA detects the change on the next initialization.

Method B: Query Parameters in the Launch URL

If you prefer to lock the initial language selection to the language of the downloaded native shell, you can configure your TWA to pass a locale parameter in its launch intent. In your build configuration, you can append a variable to your start URL:

https://example.com/?utm_source=twa&locale=es

Your web router can parse this query string on load, set the language context, and write the value to a persistent storage medium like localStorage or a secure cookie so the parameter is not required on subsequent page navigations.

Method C: Server-Side Language Negotiation

When the TWA makes its initial request to your server, it sends the standard Accept-Language HTTP header. This header contains a prioritized list of languages matching the user's Android operating system settings. Your server-side framework can parse this header and return a pre-rendered HTML document in the correct language instantly, avoiding client-side layout shifts.

Handling Language Switchers within the TWA

Many global applications offer a manual language selector within their settings menu, allowing users to override their system settings. If a user manually changes their language inside your TWA, this setting should be stored in localStorage or a cookie.

Your application boot flow should respect this priority queue:

• First, check for a manually selected language override saved in localStorage.
• Second, check for a launch URL query parameter (useful on first install).
• Third, fall back to the browser's navigator.language setting.

By prioritizing the manual selection, you ensure that if an Android user operates their phone in English but prefers your specific application in French, their preference is remembered permanently across app launches and service worker updates.

Translating the Google Play Store Presence

Your technical implementation is complete once the shell and web app are aligned, but you must also localise your marketing presence. You can upload translated descriptions, titles, and localized app screenshots inside the Google Play Console.

Avoid relying on automated store listing translations, as technical terms or brand names can be incorrectly translated. Localise your promotional screenshots to display translated versions of your web application interface. A user who sees screenshots featuring their native language is significantly more likely to click the install button, paving the way for a highly optimized global launch.