بومی سازی پیام ها

این مستندات استفاده از فیلدهای محلی سازی FCM ( *_loc_key و *_loc_args ) را برای ارائه اعلان هایی که به طور خودکار با تنظیمات زبان کاربر در Android و iOS سازگار می شوند، تشریح می کند. این به سرور شما اجازه می‌دهد تا یک بار محموله تک زبانه را ارسال کند و ترجمه را به دستگاه مشتری واگذار کند.

نمای کلی محلی سازی FCM

برای بومی سازی برنامه خود، می توانید کلیدی را ارسال کنید که مربوط به ورودی منبع رشته ای در داخل برنامه کاربر است. سیستم عامل دستگاه (OS) جستجو و درج آرگومان های پویا را انجام می دهد.

مرحله 1: منابع رشته محلی را در برنامه های خود تعریف کنید

برای شروع بومی سازی FCM ، مهم است که مطمئن شوید ترجمه های لازم را در پروژه های Android و iOS خود در دسترس دارید.

راه اندازی اندروید

تعریف منابع رشته ای : رشته های زبان پیش فرض خود را در res/values/strings.xml وارد کنید. از مشخص‌کننده‌های قالب ( %1$s ، %2$d ، و غیره) برای هر مقدار پویا که قصد دارید در *_loc_args ارسال کنید، استفاده کنید.

پیش فرض ( 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

راه اندازی 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 %@.";

برای اطلاعات بیشتر، از اسناد زیر استفاده کنید:

• محلی سازی - اسناد توسعه دهنده اپل

• منابع رشته - اسناد توسعه دهنده اپل

مرحله 2: محموله پیام FCM را بسازید

هنگام ارسال اعلان با استفاده از API FCM HTTP v1، سرور شما یک بار تکی ایجاد می کند که از کلیدهای منبع ( *_loc_key ) و داده های پویا ( *_loc_args ) به عنوان آرایه ای از رشته ها استفاده می کند.

مثال FCM HTTP v1 Payload

کلیدهای محلی سازی در بلوک های لغو خاص پلت فرم قرار می گیرند ( 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" در مثال). قالب‌کننده رشته سیستم‌عامل مشتری، تبدیل نوع نهایی را بر اساس مشخص‌کننده قالب ( %ld یا %1$d ) انجام می‌دهد.

مرحله 3: پردازش و نمایش مشتری

هنگامی که دستگاه اعلان را دریافت می کند، مراحل زیر به طور خودکار انجام می شود:

1. بررسی زبان : دستگاه محل اصلی کاربر (به عنوان مثال، آلمانی، ایتالیایی) را شناسایی می کند.

2. جستجوی کلید : سیستم عامل از مقدار *_loc_key ( welcome_title ) برای جستجوی رشته ترجمه شده مربوطه در فایل های منبع برنامه برای مکان دستگاه استفاده می کند.

3. درج آرگومان : سیستم عامل آرایه را از *_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"]
          }
        }
      }
    }
  }
}'

برای کسب اطلاعات بیشتر، AndroidNotification و ApnsConfig در مستندات مرجع HTTP v1 برای جزئیات کامل کلیدهای موجود در بلوک‌های مخصوص پلتفرم در متن پیام ببینید. برای کلیدهای پشتیبانی شده توسط APNS، به مرجع کلید Payload Apple مراجعه کنید.