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

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

FCM نمای کلی بومی‌سازی

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

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

برای شروع بومی‌سازی 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

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

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

نمونه بار داده HTTP v1 FCM

کلیدهای بومی‌سازی در بلوک‌های لغو مختص پلاتفرم قرار می‌گیرند (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 v1 مراجعه کنید تا جزئیات کامل کلیدهای دردسترس در بلوک‌های مختص پلاتفرم در بدنه پیام را ببینید. برای کلیدهای پشتیبانی‌شده توسط APNS، به مرجع کلید بار داده Apple مراجعه کنید.