Push notifications are often sent from external marketing systems, bypassing the main app translation repository and causing users to receive English notifications. When teams focus solely on translating the in-app user interface, they frequently overlook the external communication layer. This failure mode leads to a disjointed user experience where a customer in France receives a promotional alert in English, taps it, and lands on a localized French page. Alternatively, they might receive a localized message but follow a deep link that drops them on an English-only fallback screen. Standardizing your approach to localized push notifications ensures that every external trigger aligns with the internal language preferences of your user base.
Connecting your marketing systems to the central string repository solves this problem. This article explains how to standardize deep link routing for locales and connect CRM push payloads to your main localization pipeline. You will learn how to design an architecture that supports multi-language payloads, how to handle fallback logic securely, and how to verify that your messages reach the correct devices in the right language.
Understand the core architecture of notification delivery
Mobile platforms provide native mechanisms to deliver notifications, but the payload generation happens on your servers. When you send a message, the server must determine the correct language before dispatching it to the platform gateway.
Apple documents push notification payload structures in UserNotifications. The documentation explains that iOS devices can localize messages locally if the payload includes specific localization keys. However, relying on device-side localization requires the app bundle to contain all possible translated strings at the time of delivery. If a marketing team wants to send a brand-new promotional message, the client app will not have the corresponding string unless it is updated through an app store release.
Google provides messaging overviews in Firebase Cloud Messaging. Similar to the Apple ecosystem, Android devices can resolve string resources locally. Yet, the same limitation applies. You cannot easily send dynamic, timely marketing copy if you depend on bundled application resources.
A community developer thread asks about localizing push notifications from server side, highlighting the necessity of resolving translations before the payload leaves your backend. Server-side resolution gives you the flexibility to use dynamic content without pushing a new binary to the app stores.
Implement server-side localization for messaging payloads
The most robust strategy for marketing notifications involves translating the content on your server and sending a plain text payload to the device. This approach decouples your marketing timeline from your engineering release cycle.
To achieve this, your backend needs to know the preferred language of each user. When the mobile app registers for push notifications, it should also transmit the current device language code to your user database.
{
"user_id": "987654321",
"device_token": "abc123def456",
"locale": "fr-CA"
}
When the marketing automation system triggers a campaign, the delivery service fetches the user profile, extracts the locale, and retrieves the corresponding translated string from the central translation management system.
def generate_push_payload(user, campaign_message_key):
locale = user.get_locale()
translated_text = translation_service.fetch(campaign_message_key, locale)
if not translated_text:
translated_text = translation_service.fetch(campaign_message_key, "en-US")
return {
"title": translated_text.title,
"body": translated_text.body,
"deep_link": f"myapp://promo/{locale}/summer-sale"
}
This code explicitly falls back to English if the specific French Canadian translation is missing. Explicit fallback is critical because sending an empty string or a raw localization key provides a terrible user experience.
Standardize localized deep link routing
Push notifications lose their value if the destination screen is broken. Deep links must carry the locale context so the app knows which localized content to display upon opening.
If your marketing link looks like myapp://store/shoes, the app will render the store page in the default system language. If the system language does not match the notification language, the user experiences a jarring language switch.
Instead, structure your deep links to include the explicit locale parameter. A link like myapp://fr/store/shoes forces the application to load the French catalog. This is especially important for web-to-app routing patterns where a universal link first opens a browser and then redirects into the native application.
When the application launches from a notification, intercept the routing payload in your main application delegate or intent receiver. Parse the locale segment, override the internal application locale state temporarily if necessary, and render the target screen.
Handle missing translations and fallback scenarios
A resilient notification system must handle missing translations gracefully. Marketing campaigns often move quickly, and translators might not finish every language before the scheduled send time.
If you dispatch a notification before the translation is complete, the system should gracefully degrade to a widely understood language, usually English. However, you must track these fallback events. Emitting metrics when a fallback occurs allows the localization team to identify bottlenecks in the translation pipeline.
async function resolveNotificationText(campaignId, targetLocale) {
try {
const text = await db.getTranslation(campaignId, targetLocale);
if (text) {
return text;
}
} catch (error) {
logger.error("Database error during translation lookup", error);
}
metrics.increment("notification.fallback", { targetLocale });
return await db.getTranslation(campaignId, "en");
}
This function attempts to load the requested language. If it fails due to a missing record or a database error, it logs the failure, increments a metric, and returns the English fallback. This pattern ensures the notification is still sent, preserving the marketing opportunity while providing visibility into the translation gap.
Verify the solution through testing
Testing localized push notifications requires verifying both the backend generation and the client-side routing. You cannot simply trust that the backend sent the right string; you must confirm that the native platform handled the notification correctly and routed the user to the right view.
Use network proxy tools to inspect the exact payload leaving your server. The payload must contain the translated text in the title and body fields. The custom data dictionary must contain the localized deep link.
On the device side, create test accounts for each supported language. Trigger the campaign from the backend and observe the incoming notification. Tap the notification and verify that the application opens the specified deep link and renders the interface in the expected language.
Automated integration tests can simulate this process. A server-side test can trigger a message and assert that the generated payload contains the correct localized strings. A client-side UI test can mock an incoming notification event and assert that the application navigates to the localized view.
Common mistakes in notification localization
Many teams make the mistake of caching translations too aggressively on the notification server. If a translator corrects a typo in the main repository, the notification server might continue using the stale, cached version for several hours. Ensure your cache invalidation strategy accounts for rapid marketing corrections.
Another common error is failing to synchronize the device language with the backend. If a user changes their phone language from Spanish to English, but the app does not send an update to the backend, the user will continue receiving Spanish notifications. Always update the backend user profile whenever the device language changes or the application launches.
Finally, avoid hardcoding the fallback language deep within the notification generation logic. Store the fallback hierarchy in a configuration file so product managers can adjust the default language based on regional strategies. For example, the fallback for a missing Catalan translation should probably be Spanish rather than English.
Establish a cross-team workflow
Technical implementation is only half the battle. You must establish a workflow that connects the marketing team, the localization team, and the engineering team.
When the marketing team creates a new campaign, they should author the source copy in the central translation system, not directly in the CRM. The CRM should only reference the key of the message. This forces the copy to flow through the standard localization pipeline.
Translators then receive the new keys alongside the regular application strings. They translate the marketing copy and approve it using the same quality assurance checks.
Once the translations are approved, the backend notification service can access them immediately. This unified workflow prevents the marketing team from bypassing the localization process and ensures all external communication maintains a high bar for linguistic quality.
Next steps for your team
To fix broken notification localization, audit your current marketing campaigns. Identify which campaigns are sent directly from the CRM without going through the translation repository. Migrate these messages to your central localization system.
Update your mobile application to send the current device locale to your user database on every launch. Modify your backend notification service to look up translations dynamically before dispatching the payload. Implement explicit locale parameters in all your marketing deep links. By closing these gaps, you ensure a consistent, localized experience for every user from the moment they see the push notification to the moment they complete the action inside your application.
Detailed payload examples for Apple platforms
When targeting Apple devices, the payload structure must conform to strict JSON requirements. The alert dictionary can contain a body and a title. When performing server-side localization, you populate these fields directly with the translated strings.
{
"aps": {
"alert": {
"title": "Vente d'été",
"body": "Profitez de nos offres exclusives dès aujourd'hui."
},
"sound": "default",
"badge": 1
},
"custom_link": "myapp://fr/store/summer"
}
This payload is ready for display. The device does not need to perform any lookup. The backend has already determined that the user prefers French and has injected the correct French strings into the alert object. The custom link is included outside the aps dictionary, following Apple guidelines for custom data.
If you were using client-side localization, the payload would look different. It would use the loc-key and loc-args fields.
{
"aps": {
"alert": {
"loc-key": "SUMMER_SALE_BODY",
"loc-args": [],
"title-loc-key": "SUMMER_SALE_TITLE",
"title-loc-args": []
}
}
}
While client-side localization reduces the payload size, it requires the application binary to contain the SUMMER_SALE_BODY string. Marketing teams cannot launch spontaneous campaigns using client-side localization because they would have to wait for an application update to pass through the App Store review process. Therefore, server-side localization remains the superior choice for dynamic marketing efforts.
Detailed payload examples for Android platforms
Android devices receiving messages via Firebase Cloud Messaging follow a similar pattern but use a different JSON schema. Firebase supports both notification messages and data messages. For localized marketing campaigns, data messages often provide more control because they allow the client application to intercept the payload and build the notification natively.
A server-side localized notification message looks like this:
{
"message": {
"token": "device_token_here",
"notification": {
"title": "Vente d'été",
"body": "Profitez de nos offres exclusives dès aujourd'hui."
},
"data": {
"route": "myapp://fr/store/summer"
}
}
}
The Android system will automatically display this message in the system tray if the application is in the background. The title and body are already translated. When the user taps the notification, the application can extract the route from the data dictionary and navigate to the correct localized view.
If you choose to use data messages to handle everything manually, the payload omits the notification object entirely:
{
"message": {
"token": "device_token_here",
"data": {
"title": "Vente d'été",
"body": "Profitez de nos offres exclusives dès aujourd'hui.",
"route": "myapp://fr/store/summer"
}
}
}
In this scenario, your Android application must include a custom messaging service that receives the data, constructs a notification object, and posts it to the notification manager. This approach provides maximum flexibility but requires more client-side code. Regardless of whether you use notification messages or data messages, the backend retains the responsibility for translating the text before transmission.
Monitor and analyze localized campaign performance
After implementing the server-side architecture and deep link routing, you must monitor the performance of your localized campaigns. A notification that successfully reaches the device but fails to engage the user represents a missed opportunity.
Track delivery rates, open rates, and conversion rates across different languages. If the open rate for Spanish notifications is significantly lower than the open rate for English notifications, investigate the quality of the Spanish translations. Poorly translated marketing copy can alienate users and cause them to disable notifications entirely.
Ensure your analytics events include the locale of the notification. When the user taps the message, log an event that records the campaign identifier and the language.
function onNotificationOpened(notification) {
const campaignId = notification.data.campaign_id;
const locale = notification.data.locale;
analytics.logEvent("notification_opened", {
campaign: campaignId,
language: locale
});
router.navigate(notification.data.route);
}
By correlating engagement metrics with specific languages, the marketing team can determine which regions respond best to certain types of campaigns. This data justifies further investment in high-quality translation services and helps prioritize future localization efforts.
Address edge cases in language preferences
Users occasionally configure their devices in complex ways that complicate language selection. A user might set their device language to English but reside in a region where French is the primary language, such as Quebec. Or they might select a regional variant like Swiss German but fall back to Standard German if the specific dialect is unavailable.
Your backend user profile should distinguish between the device language and the user account preference. The device language is detected automatically, while the user account preference is explicitly chosen by the user within the application settings.
Always prioritize the explicit account preference over the automatically detected device language. If the user has taken the time to select a specific language in your application, they expect all communications to respect that choice.
Furthermore, support dialect mapping in your translation backend. If a user requests Mexican Spanish but you only have translations for European Spanish, your system should automatically map the request to the closest available variant before falling back to English. This intelligent routing provides a much better experience than a hard fallback to an unrelated language.
Secure your translation endpoints
When your notification service fetches strings from the central translation repository, it must do so securely. Marketing copy often contains details about upcoming promotions that should remain confidential until the official launch.
Authenticate all requests between the notification delivery service and the translation management system. Use secure tokens and encrypt the traffic to prevent internal unauthorized access.
Additionally, apply rate limiting to the translation fetching mechanism. If a campaign targets millions of users simultaneously, the delivery service could overwhelm the translation database with lookup requests. Implement a caching layer within the delivery service to store the translated strings for the duration of the campaign dispatch.
class TranslationCache:
def __init__(self, db_client):
self.cache = {}
self.db = db_client
def get(self, key, locale):
cache_key = f"{key}:{locale}"
if cache_key in self.cache:
return self.cache[cache_key]
text = self.db.fetch(key, locale)
self.cache[cache_key] = text
return text
This simple caching pattern ensures the database only receives one query per language, even when dispatching millions of messages. The cache can be cleared once the campaign finishes sending, ensuring that future campaigns fetch fresh strings from the repository.
Validate payload sizes before dispatch
Both Apple and Google impose strict limits on the maximum size of a push notification payload. For Apple, the limit is generally four kilobytes. For Firebase, the limit is also four kilobytes for most message types.
Translated text can sometimes expand significantly compared to the original English copy. A short English phrase might require twice as many characters in German or Russian. If you include long localized strings in the payload, you risk exceeding the platform limits, which will cause the notification to be rejected.
Implement a size validation check in your backend delivery service before transmitting the message to the platform gateways. If the payload exceeds the limit, the service should truncate the body text and append an ellipsis, ensuring the message can still be delivered.
function enforceSizeLimit(payload) {
const jsonString = JSON.stringify(payload);
const byteSize = Buffer.byteLength(jsonString, 'utf8');
if (byteSize > 4000) {
logger.warn("Payload exceeds limit, truncating body text");
payload.message.notification.body = truncateString(payload.message.notification.body, 100);
}
return payload;
}
This safety mechanism guarantees that unexpectedly long translations do not break the delivery pipeline. The user still receives the notification, and the deep link remains intact, allowing them to open the application and read the full message.
Connect the workflow to your continuous integration system
Your continuous integration pipeline should play a role in validating localized notifications. Just as you test the application code, you should test the integration between the translation system and the notification service.
Add a validation step to your pipeline that checks for missing translations in upcoming marketing campaigns. If a campaign is scheduled for release but the Spanish translation is still pending, the pipeline should flag the issue and alert the localization team.
This automated check prevents last-minute scrambles and ensures that every campaign goes out with complete language coverage. By integrating notification checks into the standard development workflow, you elevate the importance of external communication and treat it with the same rigor as internal application features.
References
- Apple: UserNotifications supports Apple payload structures.
- Google: Firebase Cloud Messaging supports Android notification structures.
- Stack Overflow: Localizing push notifications from server side supports the necessity of backend resolution.