Localization Add-ons

An application integrator, ISV, or the platform owner (the provider) is able to add or change the localization capabilities of an integrated application without rebuilding its APS package.

Operations

To update localization of an APS application, the platform allows the following:

• Create and upload localization add-on APS packages, each changing or adding translation of the application strings to one or more languages.
• Upload PO files that the platform uses to create add-on APS packages, one for each uploaded PO file.

The upload and download operations are available on the Add-ons tab of an APS application.

The provider will find the uploaded add-on packages and can perform the following operations.

• Import Package imports an add-on package containing one or more *.po files.
• Import locale imports a PO file that the platform converts to an add-on package.
• Export locale exports the en_US.po file.
• Delete removes the selected add-on packages.

Note

1. Every add-on package is bound to its own APS package, that is the master package for the add-on.
2. The main list of APS applications at Services > Applications does not show add-on packages.

To operate PO files as explained in the following sections, use a special editor to avoid mistakes in the file format. For example, you can download and install Poedit.

Importing PO Files

The simplest and reliable way is to have one add-on APS package for each locale to be supported by an APS application. The method consists of the following steps.

1. On the application Add-ons tab, click Export locale to have a PO file with a list of msgid and msgstr strings.
2. Using your PO editor, convert the PO file to the required locale. During this conversion, the file name must correspond to the locale name.
3. Using your PO editor, update the translation strings msgstr. If necessary, add more msgid and msgstr pairs.
4. On the application Add-ons tab, click Import locale and import the updated PO file.

On completion of the above process, a new add-on package will appear in the list. If such a package exists already, the platform will create a new package version.

For example, there was the Notification_Management_Demo-localization_de_DE-1.0-1.app.zip version of the add-on package containing a de_DE.po file. After importing another de_DE.po file, the platform creates the Notification_Management_Demo-localization_de_DE-1.0-2.app.zip version of the add-on package. The list of add-ons presents only the latest version of an add-on package.

However, on the management node, you will find all versions of the add-on package, for example:

Importing Packages

To create a localization add-on package with a PO file in it, you should have the master APS package and the PO file. Then, use the aps utility to create the add-on package as follows:

$ aps localize <master-package> <locale-po> [--release <rel>]

In the above command:

• <master-package> is the master APS package, for example Notification_Management_Demo-1.0-0.app.zip.
• <locale-po> is the PO file for the required locale, for example es_ES.po.
• <rel> is a number you want to assign to the package release. For example, if the master package version is 1.0-0 and you assign 3 for the add-on release, the add-on package version will be 1.0-3.

For example, the following command creates a localization add-on for the es_ES locale:

$ aps localize Notification_Management_Demo-1.0-0.app.zip es_ES.po

If it is necessary to have a set of locales in an add-on package, follow these steps.

1. Create PO files for the required locales as explained in the Importing PO Files.

2. Create a localized add-on package using the aps localize command for all the locales. For example, if the current folder contains the master APS package and the new PO files, es_ES.po and ru_RU.po, run:

   $ aps localize Notification_Management_Demo-1.0-0.app.zip es_ES.po ru_RU.po
   

   or

   $ aps localize Notification_Management_Demo-1.0-0.app.zip *.po
   

Package Contents

There are some specifics of an add-on package structure as compared with a regular APS package.

Metadata

An add-on package must have the following sections in the APP-META.xml file:

• The <master-package> section indicates the id of the master APS application, for example:

  <master-package>
     <package id="http://aps-standard.org/samples/async1pn"/>
  </master-package>
  

• The category is Customization/Localization, that is:

  <categories>
      <category>Customization/Localization</category>
  </categories>
  

• The <languages> section contains a list of the languages supported by the package, for example:

  <languages>
      <language>es_ES</language>
      <language>ru_RU</language>
  </languages>
  

Structure

The only folder that is required inside an add-on package is the i18n/ folder containing all *.po files and the *.json files compiled from the *.po files.

Limitations and Rules

The localization solutions implemented by means of localization add-on packages (or, simply, add-ons) must comply with the following rules:

• A locale defined in an add-on overrides the same locale defined in the master package.
• A locale defined in an add-on cannot be defined by another add-on. In other words, a set of locales in an add-on cannot overlap with a set of locales defined in another add-on.
• To update a locale defined in a certain version of an add-on, update the respective PO file and import it inside the higher version of the same add-on. If a translation string exists in the older version but does not exist in the newer version, then its value from the older version will be used.

← Localization

Security →