메시지 현지화

이 문서에서는 FCM 현지화 필드(*_loc_key 및 *_loc_args)를 사용하여 Android 및 iOS에서 사용자의 언어 설정에 자동으로 적응하는 알림을 전송하는 방법을 설명합니다. 이렇게 하면 서버가 언어에 구애받지 않는 단일 페이로드를 전송하여 번역을 클라이언트 기기에 위임할 수 있습니다.

FCM 현지화 개요

앱을 현지화하려면 사용자의 애플리케이션 내에 있는 문자열 리소스 항목에 해당하는 키를 전송하면 됩니다. 기기의 운영체제 (OS)는 동적 인수의 조회 및 삽입을 처리합니다.

1단계: 앱에서 현지화된 문자열 리소스 정의

FCM 현지화를 시작하려면 Android 및 iOS 프로젝트에서 필요한 번역을 사용할 수 있는지 확인해야 합니다.

Android 설정

문자열 리소스 정의: res/values/strings.xml에 기본 언어 문자열을 입력합니다. *_loc_args에 전달할 동적 값에는 형식 지정자 (%1$s, %2$d 등)를 사용합니다.

기본값 (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>

번역 추가: ISO 언어 코드를 사용하여 언어별 디렉터리를 만듭니다 (예: values-fr(프랑스어의 경우), values-es(스페인어의 경우))를 사용하여 키를 번역합니다.

프랑스어 (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>

자세한 내용은 다음 문서를 참고하세요.

• 문자열 리소스 - Android 개발자

• 앱 현지화 - Android 개발자

iOS 설정

문자열 리소스 정의: Localizable.strings 파일 (일반적으로 Base.lproj 폴더 또는 문자열 카탈로그)에 기본 문자열을 정의합니다. 동적 값에는 형식 지정자 (%@, %ld 등)를 사용합니다. 키는 관례에 따라 모두 대문자로 정의되는 경우가 많습니다.

기본값 (영어 Localizable.strings):

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

번역 추가: 언어별 .lproj 폴더를 만들거나 문자열 카탈로그를 사용하여 현지화를 추가하고 키를 번역합니다.

프랑스어 (fr.lproj/Localizable.strings):

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

자세한 내용은 다음 문서를 참고하세요.

• 현지화 - Apple 개발자 문서

• 문자열 리소스 - Apple 개발자 문서

2단계: FCM 메시지 페이로드 구성

FCM HTTP v1 API를 사용하여 알림을 전송할 때 서버는 리소스 키 (*_loc_key)와 동적 데이터 (*_loc_args)를 문자열 배열로 사용하는 단일 페이로드를 구성합니다.

FCM HTTP v1 페이로드 예

현지화 키는 플랫폼별 재정의 블록(android.notification 및 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"]
          }
        }
      }
    }
  }
}

페이로드 인수의 주요 고려사항

• 순서가 중요함: *_loc_args의 문자열은 문자열 리소스 파일의 자리표시자가 요구하는 정확한 순서여야 합니다 (예: %1$s, %2$s)에만 라벨을 지정할 수 있습니다.

• 문자열만: *_loc_args 배열의 모든 요소는 숫자 (예의 "3")를 나타내는 경우에도 문자열이어야 합니다. 클라이언트 OS의 문자열 포맷터는 형식 지정자(%ld 또는 %1$d)에 따라 최종 유형 변환을 처리합니다.

3단계: 클라이언트 처리 및 표시

기기가 알림을 수신하면 다음 단계가 자동으로 실행됩니다.

1. 언어 확인: 기기에서 사용자의 기본 언어를 식별합니다 (예: 독일어, 이탈리아어)

2. 키 조회: OS는 *_loc_key 값 (welcome_title)을 사용하여 기기 언어에 맞는 앱의 리소스 파일에서 해당하는 번역된 문자열을 조회합니다.

3. 인수 삽입: OS는 *_loc_args (["Alice"])에서 배열을 가져와 로케일의 서식 규칙 (구두점, 단어 순서 등)을 준수하여 현지화된 문자열에 값을 삽입합니다.

이 프로세스를 통해 모든 사용자가 언어 환경설정에 맞게 맞춤설정된 메시지를 올바른 언어 구조를 사용하여 수신할 수 있으며, 서버에서 표준화된 페이로드를 유지할 수 있습니다.

예시: 현지화 옵션이 있는 알림 메시지

다음 전송 요청 예시는 현지화된 메시지를 표시하도록 클라이언트에 현지화 옵션을 포함하여 Tech 주제에 알림을 보냅니다. 다음은 사용자 기기에 표시되는 시각 효과의 예시입니다.

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);
  });

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"]
          }
        }
      }
    }
  }
}'

자세한 내용은 HTTP v1 참조 문서의 AndroidNotification 및 ApnsConfig을 참고하세요. 메시지 본문의 플랫폼별 블록에서 제공하는 키에 관한 자세한 내용을 확인할 수 있습니다. APNS에서 지원하는 키는 Apple의 페이로드 키 참조를 참고하세요.