En esta documentación, se describe el uso de los campos de localización FCM (*_loc_key y *_loc_args) para enviar notificaciones que se adaptan automáticamente a la configuración de idioma del usuario en Android y iOS. Esto permite que tu servidor envíe una sola carga útil independiente del idioma y delegue la traducción en el dispositivo cliente.
FCM Descripción general de la localización
Para localizar tu app, puedes enviar una clave que corresponda a una entrada de recursos de cadena dentro de la aplicación del usuario. El sistema operativo (SO) del dispositivo controla la búsqueda y la inserción de argumentos dinámicos.
| Campo de FCM | Descripción | Acción del cliente |
|---|---|---|
title_loc_key |
Es la clave de la cadena de título en los recursos de cadena de la app cliente. | El SO encuentra la cadena correspondiente en los archivos localizados de la app. |
body_loc_key |
Es la clave de la cadena del cuerpo en los recursos de cadena de la app cliente. | El SO encuentra la cadena correspondiente en los archivos localizados de la app. |
title_loc_args |
Es un array de valores de cadena dinámicos que se sustituirán en la cadena title_loc_key. |
El SO inserta estos argumentos en los especificadores de formato de la cadena localizada. |
body_loc_args |
Es un array de valores de cadena dinámicos que se sustituirán en la cadena body_loc_key. |
El SO inserta estos argumentos en los especificadores de formato de la cadena localizada. |
Paso 1: Define recursos de cadenas localizadas en tus apps
Para comenzar con la localización de FCM, es importante que te asegures de tener las traducciones necesarias disponibles en tus proyectos para Android y iOS.
Configuración de Android
Define recursos de cadenas: Ingresa tus cadenas en el idioma predeterminado en res/values/strings.xml.
Usa especificadores de formato (%1$s, %2$d, etc.) para cualquier valor dinámico que planees pasar en *_loc_args.
Predeterminado (res/values/strings.xml):
<resources>
<string name="welcome_title">Welcome, %1$s!</string>
<string name="new_message_body">You have %1$d new message(s) from %2$s.</string>
</resources>
Agregar traducciones: Crea directorios específicos para cada idioma con los códigos de idioma ISO (p.ej., values-fr para francés y values-es para español) y traduce las claves.
Francés (res/values-fr/strings.xml):
<resources>
<string name="welcome_title">Bienvenue, %1$s!</string>
<string name="new_message_body">Vous avez %1$d nouveau(x) message(s) de %2$s.</string>
</resources>
Para obtener más información, consulta la siguiente documentación:
Configuración de iOS
Define recursos de cadenas: Define tus cadenas base en el archivo Localizable.strings (por lo general, en la carpeta Base.lproj o en un catálogo de cadenas). Usa especificadores de formato (%@, %ld, etc.) para los valores dinámicos. Por convención, las claves suelen definirse en mayúsculas.
Predeterminado (inglés Localizable.strings):
"WELCOME_TITLE" = "Welcome, %@!";
"NEW_MESSAGE_BODY" = "You have %ld new message(s) from %@.";
Agrega traducciones: Crea carpetas .lproj específicas para cada idioma (o agrega localizaciones con un catálogo de cadenas) y traduce las claves.
Francés (fr.lproj/Localizable.strings):
"WELCOME_TITLE" = "Bienvenue, %@!";
"NEW_MESSAGE_BODY" = "Vous avez %ld nouveau(x) message(s) de %@.";
Para obtener más información, consulta la siguiente documentación:
Localization - Apple Developer Documentation (Localización: Documentación para desarrolladores de Apple)
Recursos de cadenas: documentación para desarrolladores de Apple
Paso 2: Construye la carga útil del mensaje de FCM
Cuando envías la notificación con la API de HTTP v1 de FCM, tu servidor crea una sola carga útil que usa las claves de recursos (*_loc_key) y los datos dinámicos (*_loc_args) como un array de cadenas.
Ejemplo de carga útil de FCM HTTP v1
Las claves de localización se colocan dentro de los bloques de anulación específicos de la plataforma (android.notification y apns.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"]
}
}
}
}
}
}
Consideraciones clave para los argumentos de carga útil
El orden es importante: Las cadenas en
*_loc_argsdeben estar en el orden exacto que requieren los marcadores de posición en el archivo de recursos de cadena (p.ej.,%1$s,%2$s).Solo cadenas: Todos los elementos del array
*_loc_argsdeben ser cadenas, incluso si representan números (como"3"en el ejemplo). El formateador de cadenas del SO del cliente controla la conversión de tipo final según el especificador de formato (%ldo%1$d).
Paso 3: Procesamiento y visualización del cliente
Cuando el dispositivo recibe la notificación, se realizan los siguientes pasos automáticamente:
Verificación de idioma: El dispositivo identifica la configuración regional principal del usuario (p.ej., alemán e italiano).
Búsqueda de claves: El SO usa el valor
*_loc_key(welcome_title) para buscar la cadena traducida correspondiente en los archivos de recursos de la app para la configuración regional del dispositivo.Inserción de argumentos: El SO toma el array de
*_loc_args(["Alice"]) y, luego, inserta los valores en la cadena localizada, respetando las reglas de formato de la configuración regional (puntuación, orden de las palabras, etcétera).
| Configuración regional del dispositivo | title_loc_key: welcome_title |
title_loc_args: ["Alice"] |
Pantalla de título final |
|---|---|---|---|
| Inglés | "Welcome, %1$s!" |
Alicia | "Welcome, Alice!" |
| Francés | "Bienvenue, %1$s!" |
Alicia | "Bienvenue, Alice!" |
| Alemán | "Willkommen, %1$s!" |
Alicia | "Willkommen, Alice!" |
Este proceso garantiza que cada usuario reciba un mensaje adaptado a sus preferencias de idioma, con la estructura lingüística correcta y, al mismo tiempo, se mantenga una carga útil estandarizada desde tu servidor.
Ejemplo: Mensaje de notificación con opciones de localización
En el siguiente ejemplo de solicitud de envío, se envía una notificación al tema Tech, incluidas las opciones de localización para que el cliente muestre mensajes localizados.
Este es un ejemplo del efecto visual en el dispositivo de un usuario:
Node.js
var topicName = 'industry-tech';
var message = {
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);
});
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: 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"]
}
}
}
}
}
}'
Para obtener más información, consulta AndroidNotification y ApnsConfig en la documentación de referencia de HTTP v1 para obtener información detallada sobre las claves disponibles en los bloques específicos de la plataforma en el cuerpo del mensaje. Para conocer las claves compatibles con APNs, consulta la referencia de la clave de carga útil de Apple.