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

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

بررسی اجمالی محلی‌سازی FCM

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

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

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

تنظیمات اندروید

تعریف منابع رشته‌ای : رشته‌های زبان پیش‌فرض خود را در 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>

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

• منابع رشته‌ای - توسعه‌دهندگان اندروید

• بومی‌سازی اپلیکیشن - توسعه‌دهندگان اندروید

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

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

• بومی‌سازی - مستندات توسعه‌دهندگان اپل

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

مرحله ۲: ساخت محموله پیام FCM

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

مثالی از بار داده FCM HTTP نسخه ۱

کلیدهای محلی‌سازی درون بلوک‌های override مختص پلتفرم ( 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 ) مدیریت می‌کند.

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

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

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 نسخه ۱ مراجعه کنید. برای کلیدهای پشتیبانی شده توسط APNS، به مرجع کلید Payload اپل مراجعه کنید.