Internationalization

ActivePivot supports internationalization (abbreviated as i18n).

Depending on internationalization settings, content can be translated before it is sent to the UI (ActiveUI or XMLA clients, such as Excel).

Core Features

The following content can be translated depending on the current locale:

• The captions/descriptions of all elements discoverable from ActivePivot by end users (levels, hierarchies, measures, cubes, KPIs, drillthrough columns, and so on).
• The formatted values of measures and drillthrough columns in CellSets returned by data queries.
• The members in cube levels.

Key Concepts

Lexicons

A lexicon is a locale-specific mapping that provides the translation for each of its keys.

For instance, a localized project may have a French lexicon for measures that contains:

key	value
pnl.SUM	pnl.SOMME
update.TIMESTAMP	Dernière mise à jour
contributors.COUNT	Nombre de faits

The translated content is defined across multiple lexicons, grouped by usage, and for each supported locale. Measure labels have their own lexicon, and so do formatters and miscellaneous terms, for example.

Formatter Factory

Formatter factories are the entry point for creating formatters. They are supplied by a context value, and can as such be specific to the user role and query. The parent interface for formatter factories is ICubeFormatterFactory. There needs to be one formatter factory per locale to support.

Base Implementations

The following base implementations are available:

• CubeFormatterFactory: a basic implementation that stores its translations in the resources folder or the content server (more details below).
• MdxCubeFormatterFactory: the default formatter factory used by the MDX Engine, unless overridden by a context value. It reuses the formatters from the IMdxContext context value as formatters for the cube.
• IdentityCubeFormatterFactory: ignores all captions and formatters, used for testing and debugging purposes.

LocalI18nConfig

The LocalI18nConfig class provides a Spring bean to generate formatter factories from internationalization files in the resource folder of the application.

The internationalization files should each be named after the locale they correspond to. For example, i18n/fr-FR for French, i18n/zh-CN for simplified Chinese, i18n/ja-JP for Japanese...

Custom Formatter Factories

If LocalI18nConfig does not satisfy the use case of your project, a custom formatter factory class can be implemented.

Formatter factories are defined as plugin values. As such, a custom formatter factory can be incorporated in an ActivePivot project by:

1. Implementing an ICubeFormatterFactory plugin, responsible for creating an ICubeFormatter for every query and discovery.
2. Supplying the custom plugin's key to the MDX context by calling .withMdxContext().withCubeFormatter(pluginKey) on the cube builder.

The main benefit of creating a custom formatter factory is the possibility to store the various locales elsewhere than on the resource folder or in content server, and to also potentially use a custom format for localization files.

It is recommended to extend the ACubeFormatterFactory and ACubeFormatter classes when implementing a new formatter factory.

CubeFormatterFactory

CubeFormatterFactory is a basic implementation of formatter factories.

An instance of this class can only support one locale, so it should be extended as many times as different locales are needed, each extension with its own plugin key. The relevant formatter factory for each user can then be provided using context values.

The implementation stores its lexicons using a map of maps. The latter is stored in the resource folder or in content server as a JSON file.

The keys of the top-level map correspond to the different lexicons in use and are listed in ACubeFormatter.Type.

A level-specific formatter can be created using a dedicated lexicon for the level. The lexicon can then be associated with its level in the _FORMATTERS_ lexicon.

{
    "_FORMATTERS_" : {
        "[Bookings].[Status].[Status]" : "_STATUS_"
    },

    "_STATUS_" : {
        "DONE" : "ACCOMPLI",
        "MATCHED" : "APPARIE"
    }
}

When a formatter is requested for a caption:

• If no lexicon for a particular type is given, the _GENERAL_ lexicon will be used.
• If captions and formatters are defined both in the resource folder (or content server) and the MDX context, the factory will merge them, with priority to the former.

Example of a JSON locale file

Click to expand

{
    /** Measure captions lexicon */
    "_MEASURES_" : {
        "pnl.SUM" : "pnl.SOMME",
        "update.TIMESTAMP": "Dernière mise à jour",
        "contributors.COUNT": "Nombre de faits"
    },

   "_FORMATTERS_" : {
        /** Measure formatters */
        "[Measures].[update.TIMESTAMP]": "DATE[HH:mm:ss]",
        "[Measures].[delta.SUM]": "DOUBLE[#,###.0000;-#,###.00]",
        "[Measures].[pnl.SUM]": "DOUBLE[#,###.00;-#,###.00]",

        /** Level member formatters */
        "[Time].[TimeBucket].[Value Date]": "DATE",
        "[Underlyings].[Products].[ProductType]": "_PRODUCT_TYPES_"
    },

    /**  lexicon used for Product types' members */
    "_PRODUCT_TYPES_": {
        "LISTED": "COTE",
        "OTC": "DE GRE A GRE"
    },

    "_DESCRIPTIONS_": {
        "The two elements of underlyings which have the highest value":
          "Les deux éléments sous-jacents de plus grande valeur.",
        "Dimension of underlyings": "Dimension des sous-jacents"
    },

    /**
      * The GENERAL lexicon, used for all other types
      * (dimensions, levels, drill-through...)
      */
    "_GENERAL_": {
        "Time": "Temps",
        "Measures": "Mesures",
        "Bookings": "Enregistrement",
        "Epoch": "Epoque"
    }
}

Example: Sandbox Implementation

The Sandbox uses the LocalI18nConfig class mentioned above to generate its formatter factories from the resource folder.

Changing a User's Locale

If we want to change the locale to French for the admin user, we have to follow these three steps:

• Put the french locale JSON configuration file in the resource folder, with the name: /i18n/fr-FR.

• Change the context for the role ROLE_ADMIN.

  StartBuilding.entitlementsProvider()
    .withEntitlements(b ->
      b.forRole(ROLE_ADMIN)
        .withMdxContext()
          .withCubeFormatter("fr-FR"));