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.

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:

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

Error Codes

eSign also provides translation mechanisms for errors originating from the server side.

Each time the server returns a known error, the error will be accompanied by a unique error code. In turn, it is possible to translate this error code into a localized message.

The translation for error codes is configured in the same place as any other frontend language resource (see: Language Resources).

In the language file, all error codes entries are prefixed with servererror_, and each error code can have a specific title and description.
Meaning that for the developer to configure the translation of the error code signature_too_simple, two entries must be added to the language file:

servererror_signature_too_simple.title=Signature too simple (1)
servererror_signature_too_simple.label=Your signature is too simple, please perform a more complex signature (2)

1	Text to appear on the title of the error popup when `signature_too_simple` error occurs.
2	Text to appear on the description of the error popup when `signature_too_simple` error occurs.

If no translation exists for the title or description of a given error code, it will fallback to a default error message.

Below is a table with all the know error codes:

Name	Motive
signature_too_simple	When the handwritten signature inserted by the user does not have the required complexity.
signature_error	An unexpected error occurred when signing. Usually related to the configured signing certificate or the configured signature provider
signature_c2s_anonymous	When a user non-authenticated user attempts to perform a Click 2 Sign signature.
signature_certificate_not_allowed	The signing certificate selected by the signer is not allowed. Could be due to a number of reasons, the most common one being the selected certificate does not match the criteria configured for that document
signature_certificate_validation	The signing certificate in used has expired or is not yet valid.
signature_cmd_cert	Occurs when signing with a Digital Mobile Key (CMD) provider, and the CMD failed to retrieve the user’s certificate. Could be due to a number of reasons, the most common ones being that the user is not registered in CMD, or the CMD service is not available.
signature_cmd_failure	Occurs when signing with a Digital Mobile Key (CMD) provider, and the 2-Factor validation failed. Could be due to a number of reasons, the most common ones being that the user introduced incorrect credentials, or the CMD service is not available.
tsa_error	When a Time Stamp Authority (TSA) is configured, but eSign was not able to retrieve a TSA from the provider.
invalid_authz_code	When a user introduces incorrect credentials (ex: when trying to access a document, or when using a wrong OTP code).
document_submit_failure	When the submit document process failed (usually due to an error on the custom Submit Addin).
document_signature_method_unauthorized	When the user attempts to perform a signature using a signing method that is not allowed. This situation is not supposed to occur when using the out-of-the-box UI provided by eSign, and usually only occurs when the developers implemented: - Scripting logic to automate the signature method selection - Custom addins to dynamically determine the allow signature methods
document_action_unauthorized	When a user attempts to perform any action over a document or document field that cannot be performed by him\her.
document_readonly	When a user attempts to perform any action over a document that is not in an editable mode.
document_under_signing_session	When a user attempts to perform any action over a document which is being signed at the precise moment.

Name

Motive

signature_too_simple

When the handwritten signature inserted by the user does not have the required complexity.

signature_error

An unexpected error occurred when signing.
Usually related to the configured signing certificate or the configured signature provider

signature_c2s_anonymous

When a user non-authenticated user attempts to perform a Click 2 Sign signature.

signature_certificate_not_allowed

The signing certificate selected by the signer is not allowed.
Could be due to a number of reasons, the most common one being the selected certificate does not match the criteria configured for that document

signature_certificate_validation

The signing certificate in used has expired or is not yet valid.

signature_cmd_cert

Occurs when signing with a Digital Mobile Key (CMD) provider, and the CMD failed to retrieve the user’s certificate.
Could be due to a number of reasons, the most common ones being that the user is not registered in CMD, or the CMD service is not available.

signature_cmd_failure

Occurs when signing with a Digital Mobile Key (CMD) provider, and the 2-Factor validation failed. Could be due to a number of reasons, the most common ones being that the user introduced incorrect credentials, or the CMD service is not available.

tsa_error

When a Time Stamp Authority (TSA) is configured, but eSign was not able to retrieve a TSA from the provider.

invalid_authz_code

When a user introduces incorrect credentials (ex: when trying to access a document, or when using a wrong OTP code).

document_submit_failure

When the submit document process failed (usually due to an error on the custom Submit Addin).

document_signature_method_unauthorized

When the user attempts to perform a signature using a signing method that is not allowed.
This situation is not supposed to occur when using the out-of-the-box UI provided by eSign, and usually only occurs when the developers implemented:
- Scripting logic to automate the signature method selection
- Custom addins to dynamically determine the allow signature methods

document_action_unauthorized

When a user attempts to perform any action over a document or document field that cannot be performed by him\her.

document_readonly

When a user attempts to perform any action over a document that is not in an editable mode.

document_under_signing_session

When a user attempts to perform any action over a document which is being signed at the precise moment.