Last updated: 10/9/2024

Configuration

---

Display language (locale)

---

In this section we will describe how to set up alternative languages for the graphical user interface of ShareAspace or for the space templates.

The possible languages that can be displayed or used in a ShareAspace installation are all first defined in the bootstrap_collection.json file and therefore configured when the collection is bootstrapped.

The relevant section in the bootstrap_collection.json is:

{
    //...
    "timeZone":  "Europe/London",
    "languages":  [
                      {
                          "key":  "en",
                          "isDefault":  true,
                          "value":  "English (United States)",
                          "culture":  "en-us"
                      }
                  ]
    //...
}

Note

In this section, there can be as many languages as needed but only one can be set to default and the key will need to be remembered for a consistent usage in the space templates.

The language set in this section will appear as choices in the ShareAspace Web User Interface from the "My Profile" menu at the collection level

and for each user space role from the "My Space Settings" menu in each spaces:

Display language selection logic

The first time a user connects to the ShareAspace Web User Interface (i.e. none of the previous settings have been changed), the displayed language will be the one set by default in the space definition.

If the user changes his settings and save them either at the collection or space level the logic will be as followed:

Collection settings changed	Space settings changed	Displayed language
No	No	default from Space Definition overrides the default from collection
Yes	No	Language set at the collection level if space templates supports that language, otherwise default for the space.
No	Yes	Language set at the space level
Yes	Yes	Language set at the space level

Language backend translation

In the ShareAspace Web User Interface the mechanism for displaying the correct language relies on JSON configuration/translation files located in Web/i18n folder on the Web Server file system.

For instance under:

C:\Program Files\Eurostep\ShareAspace\Web\i18n

Those files are automatically picked up according to the selected language culture value by the logic on behind the web pages.

In the following section we will learn how to create those JSON files which contain, to simplify, key/value pairs setting files.

In the Space template, the presentation language definition for SoftTypes, Queries, Structure has to be provided manually in the ConfigTool.

Important

When adding languages in the ConfigTool the language code needs to be consistent with the key appearing in the bootstrap_collection.json.

PO (Portable Object) translation system

---

Background

• POT – Portable Object Template. This is the file that you get from ShareAspace that contains all the translation definitions. Normally, you send this file to your translators

• PO – Portable Object. This is the file that you receive back from the translators. It is a text file that includes the original texts and the translations

Since PO / POT files are so popular, there are several excellent tools for translating them.

The best known tool for editing POT files is a program called poedit https://poedit.net/, poedit is a tool for translators. It allows merging between new texts in a POT file (compared to the current translation in the JSON file). The free version usually has all the functionality you need for use with ShareAspace.

This poedit tool will only allow the editing of the POT file but, in order to output JSON which we need in ShareAspace described in the section "Translation json file", we must install two more free tools.

1. NPM a package handling tool you can get at https://nodejs.org/ if you don't already have it
2. Po2json a free library that converts PO files to JSON. https://www.npmjs.com/package/po2json

With poedit you get a po file from the pot file. With the tool Po2json you convert the PO file to JSON which ShareAspace uses.

Get the POT file

Get the POT file containing all the translations from ShareAspace by putting /sdk after the ShareAspace URL. It will look like the following:

Download the file that has the .pot ending, whatever the name of that file may be.

Do the translation

1. Use poedit or any other tool to translate the POT file and output a PO file
2. Use Po2json to convert the PO file to JSON. see "Background"
3. Put the newly created JSON file back into ShareAspace according to the section "Translation JSON file"

Setting a new language: step-by-step

---

Collection configuration file

In the bootstrap_collection.json configuration file used for bootstrapping a host collection, fill in the following section with the additional language(s).

{
    //...
    "timeZone":  "Europe/London",
    "languages":  [
                      {
                          "key":  "en",
                          "isDefault":  true,
                          "value":  "English (United States)",
                          "culture":  "en-us"
                      },
                      {
                          "key":  "en",
                          "isDefault":  false,
                          "value":  "English (United Kingdom)",
                          "culture":  "en-gb"
                      },
                      {
                          "key":  "sv",
                          "isDefault":  false,
                          "value":  "Swedish (Sweden)",
                          "culture":  "sv-se"
                      },
                      {
                          "key":  "fr",
                          "isDefault":  false,
                          "value":  "French (France)",
                          "culture":  "fr-fr"
                      }
                  ]
    //...
}

Important

Please note that with the default installation, only English (United State) language is provided and adding languages to bootstrap_collection.json is only valid before the collection is bootstrapped for the first time.

Once the collection is created the languages are available from the User Interface:

Create a new translation for standard ShareAspace

On your ShareAspace server, you need to edit these following installation files

Translation JSON file

On your ShareAspace server, find the file en.json which will be in your Web installation and probably in the directory

C:\Program Files\Eurostep\ShareAspace\Web\i18n

Note

Go to the section "Using PO(Portable Object) to create translations" in order to use more professional tools for translation.

If you choose to edit by hand the [language key].json file, or in our case sv.json file, then the following instructions apply.

In order to make these instructions as simple as possible, copy the en.json file to a new file. In this example we call it sv.json. This sv must agree with the key you gave in the bootstrap_collection.json file for your new language.

Below is a shortened example of the translations file we just copied in the previous step.

{
   "domain": "messages",
   "locale_data": {
      "messages": {
         "": {
            "domain": "messages",
            "plural_forms": "nplurals=2; plural=(n != 1);",
            "lang": "en"
         },
         "add child\u0004Add": [
            "Add"
         ],
         "add child\u0004Close": [
            "Close"
         ],
         "add generic attribute\u0004Quick Select": [
            "Quick Select"
         ],
...		 

You must first change the lang to your language key and in this example it is sv or fr. Secondly, change the objects to a Swedish or French translation.

Note that you only want to change what is in the [] brackets and nothing else. In this example we will change "Add" to "Lägg till", "Close" to "Stäng" and "Quick Select" to "Snabbval" which might be acceptable Swedish translations.

The sv.json will look like the following:

   "domain": "messages",
   "locale_data": {
      "messages": {
         "": {
            "domain": "messages",
            "plural_forms": "nplurals=2; plural=(n != 1);",
            "lang": "sv"
         },
         "add child\u0004Add": [
            "Lägg till"
         ],
         "add child\u0004Close": [
            "Stäng"
         ],
         "add generic attribute\u0004Quick Select": [
            "Snabb val"
         ],
...		 

The fr.json will look like the following:

{
   "domain": "messages",
   "locale_data": {
      "messages": {
         "": {
            "domain": "messages",
            "plural_forms": "nplurals=2; plural=(n != 1);",
            "lang": "fr"
         },
         "add child\u0004Add": [
            "Ajouter"
         ],
         "add child\u0004Close": [
            "Fermer"
         ],
         "add generic attribute\u0004Quick Select": [
            "Selection Rapide"
         ],
...		 

When you are done save your changes to the new JSON file.

Restart IIS (Internet Information Services)

For your changes to become active you must reset IIS. One way to do this is to open a command window on your ShareAspace server as Administrator and enter the command iisreset as in the following example.

Language selection in your Profile

Lastly you need to log into ShareAspace and edit your profile.

In the profile dialog, select the new language you created and "Save".

Enjoy your new display language.

Translations in the Config Tool and templates

Your translations specific to just your installation of ShareAspace are contained in your project template and can therefore be edited with the Config Tool. The examples below show how it looks in the Eurostep ShareAspace Config Tool.

Translation definitions

You will first need to add any languages in the Template General section by hitting the plus button beside "Languages"

Translations in SoftTypes

1. Select the SoftTypes menu
2. Select individually each of the SoftTypes
3. Select the Settings menu
4. In the Settings section create a new Presentation and as an example give it the Language Code sv for Swedish.

Translations in queries

1. Select the Queries menu
2. Select individually each of the Queries
3. In the Display Columns section create a new Presentation and as an example give it the Language Code sv for Swedish.

Translations in structures

1. Select the Structures menu
2. Select individually each of the Structures
3. In the Presentation section create a new Presentation and as an example give it the Language Code sv for Swedish.

Translations in clients

For the Clients there are limited multi-lingual capabilities but you need to be aware that some button texts are defined here.

1. Select the Clients menu and Select individually each of the Clients
2. If there is a title field in the Settings section, you might want to try putting some language neutral text here or @default or @moduleid so that the texts shown will be somewhat multi-lingual.
3. If there is a tabPresentation field in the "Settings" section, you might want to try putting some language neutral text here or @default or @moduleid so that the texts shown will be somewhat multi-lingual.

---