Esta página foi traduzida pela API Cloud Translation.

Localizar mensagens

Esta documentação descreve o uso dos campos de localização FCM (*_loc_key e *_loc_args) para enviar notificações que se adaptam automaticamente às configurações de idioma de um usuário no Android e no iOS. Isso permite que o servidor envie um payload único e independente de idioma, delegando a tradução ao dispositivo cliente.

FCM Visão geral da localização

Para localizar seu app, envie uma chave que corresponda a uma entrada de recurso de string no aplicativo do usuário. O sistema operacional (SO) do dispositivo processa a pesquisa e a inserção de argumentos dinâmicos.

Campo do FCM	Descrição	Ação do cliente
`title_loc_key`	A chave da string de título nos recursos de string do app cliente.	O SO encontra a string correspondente nos arquivos localizados do app.
`body_loc_key`	A chave da string de corpo nos recursos de string do app cliente.	O SO encontra a string correspondente nos arquivos localizados do app.
`title_loc_args`	Uma matriz de valores de string dinâmicos a serem substituídos na string `title_loc_key`.	O SO insere esses argumentos nos especificadores de formato da string localizada.
`body_loc_args`	Uma matriz de valores de string dinâmicos a serem substituídos na string `body_loc_key`.	O SO insere esses argumentos nos especificadores de formato da string localizada.

Etapa 1: definir recursos de string localizados nos seus apps

Para começar a localização do FCM, é importante verificar se você tem as traduções necessárias disponíveis nos seus projetos para Android e iOS.

Configuração do Android

Definir recursos de string: insira as strings do idioma padrão em res/values/strings.xml. Use especificadores de formato (%1$s, %2$d etc.) para valores dinâmicos que você planeja transmitir no *_loc_args.

Padrão (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>

Adicionar traduções: crie diretórios específicos para cada idioma usando os códigos ISO (por exemplo, values-fr para francês, values-es para espanhol) e traduza as chaves.

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 mais informações, consulte a seguinte documentação:

Configuração do iOS

Defina recursos de string: defina as strings básicas no arquivo Localizable.strings (normalmente na pasta Base.lproj ou em um catálogo de strings). Use especificadores de formato (%@, %ld etc.) para valores dinâmicos. As chaves geralmente são definidas em letras maiúsculas por convenção.

Padrão (inglês Localizable.strings):

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

Adicionar traduções: crie pastas .lproj específicas do idioma (ou adicione localizações usando um catálogo de strings) e traduza as chaves.

Francês (fr.lproj/Localizable.strings):

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

Para mais informações, consulte a seguinte documentação:

Etapa 2: criar o payload da mensagem FCM

Ao enviar a notificação usando a API HTTP v1 FCM, seu servidor cria um único payload que usa as chaves de recursos (*_loc_key) e os dados dinâmicos (*_loc_args) como uma matriz de strings.

Exemplo de payload HTTP v1 FCM

As chaves de localização são colocadas nos blocos de substituição específicos da plataforma (android.notification e 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"]
          }
        }
      }
    }
  }
}

Principais considerações sobre argumentos de payload

A ordem é importante: as strings em *_loc_args precisam estar na ordem exata exigida pelos marcadores de posição no arquivo de recursos de string (por exemplo, %1$s, %2$s).
Somente strings: todos os elementos na matriz *_loc_args precisam ser strings, mesmo que representem números (como "3" no exemplo). O formatador de strings do SO do cliente processa a conversão final de tipo com base no especificador de formato (%ld ou %1$d).

Etapa 3: processamento e exibição do cliente

Quando o dispositivo recebe a notificação, as seguintes etapas ocorrem automaticamente:

Verificação de idioma: o dispositivo identifica a localidade principal do usuário (por exemplo, alemão e italiano.
Pesquisa de chave: o SO usa o valor *_loc_key (welcome_title) para pesquisar a string traduzida correspondente nos arquivos de recursos do app para a localidade do dispositivo.
Inserção de argumentos: o SO extrai a matriz de *_loc_args (["Alice"]) e insere os valores na string localizada, respeitando as regras de formatação da localidade (pontuação, ordem das palavras etc.).

Local do dispositivo	`title_loc_key`: welcome_title	`title_loc_args`: ["Alice"]	Exibição do título final
Inglês	`"Welcome, %1$s!"`	Alice	`"Welcome, Alice!"`
Francês	`"Bienvenue, %1$s!"`	Alice	`"Bienvenue, Alice!"`
Alemão	`"Willkommen, %1$s!"`	Alice	`"Willkommen, Alice!"`

Esse processo garante que cada usuário receba uma mensagem adaptada às preferências de idioma, usando a estrutura linguística correta, mantendo uma carga padronizada do seu servidor.

Exemplo: mensagem de notificação com opções de localização

O exemplo de solicitação de envio a seguir envia uma notificação para o tópico Tech, incluindo opções de localização para o cliente exibir mensagens localizadas. Este é um exemplo do efeito visual no dispositivo de um usuário:

Desenho simples de dois dispositivos exibindo texto em inglês e espanhol

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 saber mais, consulte AndroidNotification e ApnsConfig na documentação de referência HTTP v1 para mais detalhes sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem. Para ver as chaves compatíveis com o APNS, consulte a Referência da chave de payload da Apple.