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 an APS package used to deploy the APS application which creates 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 short notification description.

• The fullDetails structure is the full notification 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 arrives at its destination, the user panel finds its translation to the language used by the current person. The translation goes through two steps:

1. As explained in the Source Package section, the user panel translates the whole string except for the key elements, such as __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 located values. An example of such a keys structure is:

   "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 user panel receives a notification, it uses the package ID to search for translated strings in the source package and then looks for the keys in the keys structure inside the notification.

In the following sections, use this sample notification:

The notification carries the following strings:

• Title “VPS Creation”

• Short description “VPS __name__ is provisioned”

• Link name “View or edit VPS”

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 looks 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

When a user logs into the user panel using the German locale, the notification looks as follows:

Example

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

← Internationalization in View-Plugins

Localization →