Multilingual support

The Framework completely separates language-dependent texts from the application code. It is naturally multi-lingual framework

• The multilingual concept
  • Translations for application and back-end
  • Texts used by application
• File with text in the supported language
  • Function name and hint
  • View name and hint
• Hierarchical structure of the translation files
• Translation of counters
• Customer-related texts
  • Client-specific counter values
• How to add a new language
  • How to translate

The multilingual concept

Translations for application and back-end

The translations are separate for back-end functionality and the application. Nevertheless, back-end functions could use the translation string for client application but it rarely makes sense.

Texts used by application

All texts used by application are stored in the .json files that are once loaded by application and stored locally in the persistent cache. The texts contain:

• Names of records (objects)
• Names of views
• Names of fields in records
• Hints
• Tooltip
• Information and warning messages
• Names of operations and buttons
• Translation of the fields from counters

The help files that are opened in an independent window are not part of the translation text. They are stored independently as a markdown files loaded on request.

File with text in the supported language

The translation file has the structure:

{  
   "about": {   "version": "1",  "language": "en"  }, 
   "data": {
      "tskTaskID": "Task",
      "tskTask": "Task",
      "setContinue": "Run",
      "setContinue_hint":"<h3>Run suspended task</h3><p>The task will return ...",
"tskDefUserTask.clipList.beforeDTasks": "Preceding",
"changeResponsible":"Responsible user",
"changeResponsible_tooltip":"Change person resposible for task(s)",
"replanTasks":"Plan",
"replanTasks_tooltip":"Plan entire project",
"replanTasks_hint":"=g.isMobile?false:'<h3>Reschedule project / area</h3><p>Reschedule all tasks that have not yet started and have relationships to other objects.</p>'",

   }
}

Function name and hint

Function that is callable by button or from the menu should have its name translated. The example presents method replanTask.

There are three strings related with method:

// User-readable name of the function
"replanTasks":"Plan",
// Tooltip that is visible when user moves cursor over the function button 
"replanTasks_tooltip":"Plan entire project",
// Hint opens in the bottom-right corner. Hint could be longer and formatted
"replanTasks_hint":"=g.isMobile?false:'<h3>Reschedule project / area</h3><p>Reschedule all tasks....</p>'",

The texts are related with function by its name. Definition of the function in the tskAbstractTask jsonc file:

"replanTask":{  "icon":"calendar__link",  ...  },

Icon on the function button is the same for all languages and that's defined by the .jsonc definition file.

View name and hint

The view name is defined by the full view name:

// Name of view
"tskTask.clipList.beforeBATasks": "Previous tasks",
// Hint visible under the name
"tskTask.clipList.beforeBATasks_hint": "Tasks processed before this task",
// Text visible in the on the   icon
"tskTask.clipList.beforeBATasks.hint": "Tasks ",

Hierarchical structure of the translation files

Texts are used from files defined for each object separately. Nevertheless, several objects could use the same file or more files. Texts with translation is defined in the about section of the object definition in the “.jsonc”.

The example is from the task-definition object:

{ 
   "about": {"version":1,"module":"tsk","name":"tskAbstractTask"},  
   "data": {
      "about": {
         "name":"tskAbstractTask", "classID":"aat",
         ...
         "langModules": ["tsk/langs/@/tskCommon", "tsk/langs/@/task" ],
      }
   }
}

• Each text used by the task view is searched in the "tsk/langs/@/task" (symbol @ is replaced by used language shortcut, e.g. en )
• If text is not found there, then it is searched in the "tsk/langs/@/tskCommon" that contains translation used by most of the objects from the tsk modle
• If text is not even there, then the global translation /frm/langs/@/global is searched. The global translations are always used as the last attempts.

Recommendations:

• User the hierarchy of translations to simplify the structure and size of all translations
• Don't use file with language strings from single module in another module. It often created confusing situations

Translation of counters

Counters have translation in the separate file. Their structure is the same as the structure for other texts used by application.

The counter translations are used both by back-end and front-end. Back-end uses them for report generation

The text file with translation is defined in the counter file for each module.

The example from the tsk module:

{  
   "about": {  "version": 1, "module":"tsk" },   
   "data": {
      "langModules": [ "tsk/langs/@/enums" ],c
      "enumerators": [
         {"name":"tskOptions",  "fields": [
            {"name":"taskTeams", "short":"TTE"},
            {"name":"regulation", "short":"REG"},
            {"name":"analysis", "short":"ANA"},
            {"name":"sabre", "short":"SAB"},
            {"name":"workReports", "short":"WRE"}
         ]  },     
         ...
      ]
   }
}

The translations for tsk counters are stored in the "tsk/langs/@/enums".

Each field is translated separatelly:

{  
   "about": { "version": "1", "language": "en" },   
   "data": {
      "tskOptions:taskTeams":"Use teams with tasks",
      "tskOptions:regulation":"Regulations and standards",
      "tskOptions:analysis":"Use formal analysis",
      "tskOptions:sabre":"Task and calendar synchronisation",
      "tskOptions:workReports":"Use work reports in activities",
      ...
      "defTaskSystemTags:VerVal":"V&V",
      "defTaskSystemTags:VerVal_hint":"<h3>Verification & Validation</h3><p>Tasks related ...</p>",
      "defTaskSystemTags:qualControl":"QA",
      "defTaskSystemTags:qualControl_hint":"<h3>Quality Assurance</h3><p>Process audits task ...</p>",

   }
}

Customer-related texts

The hierarchy of the files with texts supports using separate names of all application items for each particular client

Client-specific counter values

Counter translations can also use the hierarchically defined files. It is not recommended to use that and it really makes no sense. However, it supports using client-specific translation that overrides counter value name using the client-specific names. In that case the language file is defined:

"langModules": [ "<module>/langs/@/enums", "<module>/#/langs/@/<fileName> ],

The translations of the counters could contain also the hint files that are available via the .
Warning: Don't use the hints for radio-type counters used in the modal dialogs. Actually, they don't behave correctly.

How to add a new language

Create a support for a new language requires:

• Translate all documents from the source language
• Translate files with the back-end strings
• Add language to the counter sys/sysLanguages. The language supported by the application user interface should have counter mark "systemTranslations": true
• Translate the system documentation in the md files
• Translate templates for reports
• Import the module to the system. The Import operation reloads texts and loads also new text for newly created language

How to translate

The AI-based translation engines work quite good with the translation string. However, correct js structure of the generated file should always be checked. Recommendations:

• Carefully verify translation of the hint lines with html marks
• Put spaces between field and the quotation mark after the double-dot: name": "
• For links to the documentation check translation of the language directory or set it correctly