Multi-Language

eSign provides users with a way to customize the language of the product.

The language of the application can be either specified in a static manner or it can be adapt to the user based on several factors:

  • Client’s browser language

  • Contract specific (passed at contract creation time)

  • Pass in a query parameter

  • Custom behavior

At the moment only eSign Viewer module supports multi-language.
Multi-language applies to user-interfaces and not to the contract clauses.

Language resources

The language resources are held in the esign-home/resources/locale folder. It holds both a client and a server folder to better fine grain the resources available.

The language files are, as one would expect, files with the application’s message values translated to several languages (as a list of name-value pairs). This method allows not only for the change of the language used by eSign’s output but also for the addition of new languages in a fast and easy manner.

Locale folder structure

As a default behavior, eSign checks the browser language to determine which language is most appropriated for a given user. However, a given language can be enforced as a server configuration.

Adding a new language

To add a new language the best approach is to:

  1. Duplicate an existing locale resource
    If no file exists in the esign-home/resources/locale folder (or if the content is empty) it is always possible to download the default locale from: https://<hostname>/eSignServer/resources/locale

  2. Rename the file to match the desired local in the following format: esign.<language>-<region>.properties (example: esign.en-US.properties)

  3. Replace the values of each entry with the translations for the desired new language.

Support for new languages can be added by simply dropping language resources to the locale folder.
No restart is required.

Language files need not translate all available entries. If eSign tries to retrieve a language entry that is not in the language file in use it will retrieve it from default language file.

Specify what language to use

The following methods are shown in fallback order from the least to highest priority.

Using esign.config

It is possible, as said before, to configure in esign.config the default language to be used on eSign. This is done through the property "server.language".

Example of server.language usage
{
    "properties":{

        ...

        "server.language": "en-US"

        ...
    }
}

Seeing as this is the default value, it is possible that it will be overwritten by other methods within eSign. If you wish to force this language, the property "server.language.force" receives a Boolean that states if the server language should be forced or not.

Example of server.language.force usage
{
    "properties":{

        ...

        "server.language.force": true

        ...
    }
}

Inherit browser’s language

One of the ways eSign decides the language to be used is simply by checking the browser locale. Change the browser language to what you need and you will be set.

This behavior is ignored if property "server.language.force" is set to true in esign.config

Using query parameter

It is also possible to specify the language to be used by adding the query parameter "locale" to the url of a document. You may pass a string representing the language you want to use. E.g. https://[hostname]/eSignServer/?session={artifactId}&locale=en-US - this url opens eSign viewer and show us a given document with US English as the UI language.

Artifact variable

During a document creation process it is possible to pass a variable "locale" that specifies the language that the specific document will use.

Example of server.language.force usage
{
    "variables":{

        ...

        "locale": "en-us"

        ...
    }
}

Custom session language

If you have specific business rules or dynamic behavior to determine the language of for a specific user, it is also possible to specify the desired language with any of the following addins:

  • ISessionAuthenticationAddin

  • ISessionInformationAddin

This can be achieved by adding property LOCALE to the parameters of the TokenRequest, with the value of the desired language.

A common use case for using a custom session language is when the developers wish to inherit the language from an external authentication token/mechanism.

Language fallback

If any of the mechanisms listed above specify a language that was not added to eSign locale folder, eSign will try its best to provide the best fit available.

For instance if the language requested is en-UK and non exists in eSign, the application will check if there is other variant of the same language (en-*). In this case if en-US is available eSign will use instead.

If no variant of the provided language is available, eSign will fallback to the value of the property server.language specified in esign.config. And if, for some reason, the language in esign.config is not available eSign falls back to the internal default language (en-US).

At the moment eSign supports the following languages:

  • en-US

  • pt-PT