Internationalization in Notifications

Translation Strings

The On-Screen Notifications mechanism allows applications to subscribe to events triggered by other applications.

In this document, the source package is the APS package that was used to deploy the APS application creating notifications.

A notification can carry strings in the following elements:

• The message structure creates the notification title on the screen
• The details structure is the notification short description
• The fullDetails structure is the notification full description
• The linkMoreText structure is the text of the link displayed on the notification tile

All of the above elements are based on the same LocalizedMessage structure:

"LocalizedMessage": {
   "type": "object",
   "properties": {
     "message": {
       "type": "string"
     },
     "keys": {
       "type": "object"
     },
     "multilangKeys": {
       "type": "object"
     }
   }
}

A message string generally looks as follows:

"message": "String part one __keyOne__ string part two __keyTwo__ final string part"

Once this string comes to its destination, the control panel finds its translation to the language used by the current person. The translation goes through the two steps:

1. The method explained later translates the whole string except for the key elements, like __keyOne__ and __keyTwo__. For example, in German, the translated string may look as follows:

   "Der erste Teil der Zeile __keyOne__ der zweite Teil der Zeile __keyTwo__ der letzte Teil der Zeile"
   

2. Once this is translated, the control panel looks up for the keys in the keys structure and then substitutes them with the found values. The keys structure may look as follows:

   "keys": {
      "keyOne": "Value-1",
      "keyTwo": "Value-2"
   }
   

Finally, the string translated into German will appear on the screen as follows:

"Der erste Teil der Zeile Value-1 der zweite Teil der Zeile Value-2 der letzte Teil der Zeile"

Source Package

The necessary strings are translated in the PO files inside the source package. The Message structure in the notification schema contains the packageId property that the source application uses to send the APS ID of its package. Once the control panel receives a notification, it uses the package ID to search for translated strings in the source package and then looks up for the keys in the keys structure inside the notification.

In the following sections, let us consider this sample notification as an example:

The notification carries the following strings:

• Title “VPS Creation”
• Short description “VPS __name__ is provisioned”
• Link name “View or edit VPS”

Let us assume, the notification strings must be translated into two languages, German and Russian.

Translation

Make sure the package contains the en_US.po, de_DE.po, and ru_RU.po files created as explained in the Development Workflow section.

Add all required translation strings in the PO files. For example, in the de_DE.po file, they may look as follows:

msgid "VPS Creation"
msgstr "Die Bildung des Servers"

msgid "VPS __name__ is provisioned"
msgstr "Der VPS __name__  ist geschaffen"

msgid "View or edit VPS"
msgstr "Die Übersicht oder die Editierung des Servers"

Notification Structure

The notification must contain all three required structures and the package ID:

{
   "type":"activity",
   "status":"ready",
   "message":{
      "message":"VPS Creation",
      "keys":{}
   },
   "details":{
      "message":"VPS __name__ is provisioned",
      "keys":{"name":"vps104"}
   },
   "link":"/v/aps/samples/async1pnl/servers/",
   "linkMore":"/v/aps/samples/async1pnl/server.edit/r/aff612cc-8199-4293-87e3-a838edd3feed",
   "linkMoreText":{
      "message":"View or edit VPS",
      "keys":{}
   },
   "packageId":"0d9ceaa1-21bd-4b21-9a88-c78be060fdfd",
   ...
}

PHP Code

The respective PHP code generating such a notification will look as follows:

// Establish connection with the APS controller:
$apsc = \APS\Request::getController();

// Get JSON representation of the Notification Manager:
$notificator = $apsc2->getResources(
   'implementing(http://www.parallels.com/pa/pa-core-services/notification-manager/1.0)'
);

// Create Notification structure
$notification = array(
   "message" => array("message" => "VPS Creation"),
   "details" => array(
      "message" => "VPS __name__ is provisioned",
      "keys" => array("name" => $this->name)
   ),
   "type" => "activity",
   "accountId" => $accountId,
   "userId" => $_SERVER['HTTP_APS_IDENTITY_ID'],
   "status"=> "ready",
   "packageId" => $this->aps->package->id,
   "link" => "/v/aps/samples/async1pn/servers/",
   "linkMore" => "/v/aps/samples/async1pn/server.edit/r/".$this->aps->id,
   "linkMoreText" => array("message" => "View or edit VPS")
);

// If Notification Manager is available, then send the notification
if(isset($notificator[0]->aps->id)) {
   $json_notification = json_encode($notification);
   $notificationResponse=json_decode($apsc2->getIo()->sendRequest(\APS\Proto::POST,
         "/aps/2/resources/".$notificator[0]->aps->id."/notifications", $json_notification));
}

Localized Notification

Once a user logs in the control panel using the German locale, the notification will look as follows:

Example

For detailed demonstration, refer to the Internationalization (optional) section in the Notification Management demo project.

← Internationalization in View-Plugins

Localization →