Resource files of LP are associative arrays, structured like key => value. One key can be equal to different values depending on a locale name. For instance, ui__server/mail__short-title key can be equal to “Mail Server Settings” in US English locale and to “Paramètres du serveur de messagerie” in French locale. To retrieve a key value for a specified locale, use the get-message operation.

Request Packet Structure

A request XML packet retrieving localized messages includes the get-message operation node:

<packet>
<get-message>
   <install>


   </install>
</get-message>
</packet>

The get-message node is presented by type LocaleGetMessageInput (locale.xsd), and its graphical representation is as follows:

image 40806

Note: The interactive schema navigator for all request packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_input.svg.

  • The filter node is required. Specifies the filtering rule. For more information, refer to the Available Filters section. Data type: LocaleGetMessageFilter (locale.xsd) .
  • The key node is required. It specifies the key name. Data type: string.
  • The id node is required. It specifies the language pack name. For details, refer to the LP Names section. Data type: string.

Note: When creating request packets, put nodes and elements in the order they follow in the packet structure.

Response Packet Structure

The get-message node of the output XML packet is presented by type LocaleGetMessageOutput (locale.xsd) and structured as follows:

image 40814

Note: The interactive schema navigator for all response packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_output.svg.

  • The result node is required. It wraps the response retrieved from the server. Data type: LocaleMessageResultType (locale.xsd).
  • The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error.
  • The errcode node is optional. It returns the error code if the operation fails. Data type: unsignedInt.
  • The errtext node is optional. It returns the error message if the operation fails. Data type: string.
  • The filter-id node is optional. It returns a filtering rule parameter. For more information, refer to the Available Filters section. Data type: anySimple.
  • The id node is optional. It holds name of the language pack matched by the filtering rule. Data type: string.
  • The message node is optional. It holds value of the key received from the request packet. Data type: string.

Samples

Retrieving value for a single key

The following request packet retrieves value for the ui__server/mail__short-title key in US English locale:

<packet>
  <locale>
    <get-message>
        <filter>
           <key>ui__server/mail__short-title</key>
        </filter>
        <id>en-US</id>
    </get-message>
  </locale>
</packet>

Response:

<packet version="1.6.7.0">
  <locale>
    <get-message>
      <result>
        <status>ok</status>
        <filter-id>ui__server/mail__short-title</filter-id>
        <id>en-US</id>
        <message>Mail Server Settings</message>
      </result>
    </get-message>
  </locale>
</packet>

If the key was not found, the response is as follows:

<packet version="1.6.7.0">
  <locale>
    <get-message>
      <result>
        <status>error</status>
        <errcode>1013</errcode>
        <errtext>Key does not exist</errtext>
        <filter-id>hst_def__fp_admin_login</filter-id>
        <id>fr-FR</id>
      </result>
    </get-message>
  </locale>
</packet>

Retrieving value for multiple keys

The following request packet retrieves values for the ui__server/mail__short-title and ui__server/mail__description keys in French locale:

<packet>
  <locale>
    <get-message>
        <filter>
           <key>ui__server/mail__short-title</key>
           <key>ui__server/mail__description</key>
        </filter>
        <id>fr-FR</id>
    </get-message>
  </locale>
</packet>

Response:

<packet version="1.6.7.0">
  <locale>
    <get-message>
      <result>
        <status>ok</status>
        <filter-id>ui__server/mail__short-title</filter-id>
        <id>fr-FR</id>
        <message>Paramètres du serveur de messagerie</message>
      </result>
      <result>
        <status>ok</status>
        <filter-id>ui__server/mail__description</filter-id>
        <id>fr-FR</id>
        <message>Configurez votre serveur de messagerie et configurez les paramètres de messagerie valables pour l'ensemble du serveur.</message>
      </result>
    </get-message>
  </locale>
</packet>