This documentation outlines the use ofFCM localization fields(*_loc_key and*_loc_args) to deliver notifications that automatically adaptto a user's language settings on Android and iOS. This lets your server send asingle, language-agnostic payload, delegating the translation to the clientdevice.

FCM Localization Overview

To localize your app, you can send a key that corresponds to a string resourceentry inside the user's application. The device's operating system (OS) handlesthe lookup and insertion of dynamic arguments.

Step 1: Define localized string resources in your apps

To get started withFCM localization, it is important to make sure that you have the necessarytranslations available in your Android and iOS projects.

Android Setup

Define string resources: Enter your default language strings inres/values/strings.xml.Use format specifiers (%1$s,%2$d, etc.) for any dynamic values you plan topass in the*_loc_args.

Default (res/values/strings.xml):

<resources><stringname="welcome_title">Welcome,%1$s!</string><stringname="new_message_body">Youhave%1$dnewmessage(s)from%2$s.</string></resources>

Add translations: Create language-specific directories using the ISO languagecodes (e.g.,values-fr for French,values-es for Spanish) and translate the keys.

French (res/values-fr/strings.xml):

<resources><stringname="welcome_title">Bienvenue,%1$s!</string><stringname="new_message_body">Vousavez%1$dnouveau(x)message(s)de%2$s.</string></resources>

For more information, use the following documentation:

• String resources - Android Developers

• Localize your app - Android Developers

iOS Setup

Define string resources: Define your base strings in theLocalizable.stringsfile (typically in theBase.lproj folder or a String Catalog). Use formatspecifiers (%@,%ld, etc.) for dynamic values. Keys are often defined inall capital letters for convention.

Default (EnglishLocalizable.strings):

"WELCOME_TITLE"="Welcome, %@!";"NEW_MESSAGE_BODY"="You have %ld new message(s) from %@.";

Add translations: Create language-specific.lproj folders (or addlocalizations using a String Catalog) and translate the keys.

French (fr.lproj/Localizable.strings):

"WELCOME_TITLE"="Bienvenue, %@!";"NEW_MESSAGE_BODY"="Vous avez %ld nouveau(x) message(s) de %@.";

For more information, use the following documentation:

• Localization - Apple Developer Documentation

• String resources - Apple DeveloperDocumentation

Step 2: Construct theFCM message payload

When sending the notification using theFCM HTTP v1 API, your serverconstructs a single payload that uses the resource keys (*_loc_key) and thedynamic data (*_loc_args) as an array of strings.

ExampleFCM HTTP v1 Payload

The localization keys are placed within the platform-specific override blocks(android.notification andapns.payload.aps.alert).

{"message":{"token":"DEVICE_REGISTRATION_TOKEN","android":{"notification":{// Android keys match strings.xml resource names"title_loc_key":"welcome_title","title_loc_args":["Alice"],"body_loc_key":"new_message_body","body_loc_args":["3","Bob"]}},"apns":{"payload":{"aps":{"alert":{// iOS uses 'title-loc-key' and 'loc-key' (for the body)"title-loc-key":"WELCOME_TITLE","title-loc-args":["Alice"],"loc-key":"NEW_MESSAGE_BODY","loc-args":["3","Bob"]}}}}}}

Key considerations for payload arguments

• Order matters: The strings in*_loc_args must be in the exact orderrequired by the placeholders in the string resource file (e.g.,%1$s,%2$s).

• Strings only: All elements in the*_loc_args array must be strings, evenif they represent numbers (like"3" in the example). The client OS's stringformatter handles the final type conversion based on the format specifier(%ld or%1$d).

Step 3: Client processing and display

When the device receives the notification, the following steps occur automatically:

1. Language check: The device identifies the user's primary locale (e.g.,German, Italian).

2. Key lookup: The OS uses the*_loc_key value (welcome_title) to look upthe corresponding translated string in the app's resource files for thedevice's locale.

3. Argument insertion: The OS takes the array from*_loc_args (["Alice"])and inserts the values into the localized string, respecting the locale'sformatting rules (punctuation, word order, etc.).

This process makes sure that every user receives a message tailored to theirlanguage preferences, using the correct linguistic structure, all whilemaintaining a standardized payload from your server.

Example: notification message with localization options

The following example send request sends a notification to theTech topic,including localization options for the client to display localized messages.Here's an example of the visual effect on a user's device:

vartopicName='industry-tech';varmessage={android:{ttl:3600000,notification:{bodyLocKey:'STOCK_NOTIFICATION_BODY',bodyLocArgs:['FooCorp','11.80','835.67','1.43']}},apns:{payload:{aps:{alert:{locKey:'STOCK_NOTIFICATION_BODY',locArgs:['FooCorp','11.80','835.67','1.43']}}}},topic:topicName,};getMessaging().send(message).then((response)=>{// Response is a message ID string.console.log('Successfully sent message:',response);}).catch((error)=>{console.log('Error sending message:',error);});

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1Content-Type: application/jsonAuthorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA{  "message": {    "topic":"Tech",    "android": {      "ttl":"3600s",      "notification": {        "body_loc_key": "STOCK_NOTIFICATION_BODY",        "body_loc_args": ["FooCorp", "11.80", "835.67", "1.43"]      }    },    "apns": {      "payload": {        "aps": {          "alert": {            "loc-key": "STOCK_NOTIFICATION_BODY",            "loc-args": ["FooCorp", "11.80", "835.67", "1.43"]          }        }      }    }  }}'

To learn more, seeAndroidNotificationandApnsConfigin theHTTP v1 referencedocumentationfor complete detail on the keys available in platform-specific blocks in themessage body. For keys supported by APNS, see Apple'sPayload KeyReference.