Introduction

JOC Cockpit ships with Language Files that include translations for the following languages:

The JS7 JOC Cockpit user interface ships for the following languages:

Hint:

• Interface Language is applied to the JOC Cockpit GUI.
• Context Help is available for offline documentation.

Additional languages can be added for new releases. SOS accepts community contributions for Language Files provided that the contributor:

• will provide quality assurance for a correct translation,
• will commit to on-going language support in subsequent releases for a minimum of one year,
• will not claim intellectual property rights for Language Files.

Language Files

Language File Location

Language Files are included with JOC Cockpit's <jetty-base>/webapps/joc/assets/i18n directory:

Language Files are available from the public Git repository at https://github.com/sos-berlin/joc-cockpit/tree/master/src/main/angular/client/src/assets/i18n

Language File Development

Adding new Language Files

• Open the locales.js file to find a single array to which you add a new language by specifying country code, language code, country name and language name. Ordering follows ascending order of language codes:
  • locales.json file

    {
      "de": {
        "lang": "de",
        "country": "DE",
        "name": "Deutsch"
      },
      "en": {
        "lang": "en",
        "country": "US",
        "name": "English"
      },
      "es": {
        "lang": "es",
        "country": "ES",
        "name": "Español"
      },
      "fr": {
        "lang": "fr",
        "country": "FR",
        "name": "Français"
      },
      "ja": {
        "lang": "ja",
        "country": "JP",
        "name": "日本語"
      },
      "ru": {
        "lang": "ru",
        "country": "RU",
        "name": "Русский"
      }
    }

• Create a new Language File - preferably by starting from a copy of the en.json English Language File and the naming convention <language code>.json.
  • Translate assignments for each line in the Language File.
• Create a new Editor Language File - preferably by starting from a copy of the json-editor-text_en.json English Editor Language File and the naming convention json-editor-text_<language code>.json.
  • Translate assignments for each line of the Editor Language File.

Editing Language Files

• Language Files use a JSON format and can be modified using any text editor. Files must be stored with UTF-8 encoding.
• Be careful when it comes to use of quotes and commas that have to be in place as shown in the examples. A missing quote or comma invalidates a Language File.
• Validate your Language File with a JSON validator utility - a number of online resources are available.

Glossary Files

FEATURE AVAILABILITY STARTING FROM RELEASE 2.9.0

A glossary is introduced to better support self-learning of users.

Glossary File Location

Glossary Files are included with JOC Cockpit's <jetty-base>/webapps/joc/assets/i18n/glossary directory:

Glossary Files are available from the public Git repository at https://github.com/sos-berlin/joc-cockpit/tree/master/src/main/angular/client/src/assets/glossary

Referencing Glossary Items

Glossary items can be referenced from Language Files, from Glossary Files and from Context Help Files using the ^glossary-item^ syntax. For example, the term ^Order^ translates to the "order": "..." glossary item. Glossary item references can be added from

• tooltips in Language Files indentified by holding tooltip in their object hierarchy or property name,
• items in Glossary Files,
• text in Context Help Files.

Glossary items can be referenced in the following ways:

Formatting Options

Context Help Files are created in markdown and support the related rendering.

For both Language Files and Glossary Files a number of formatting options are available:

Best Practices

The purpose of translation is to allow users learning the JS7 from their native language. Hardly anybody has a problem in reading labels from a screen in English language. However, when it comes to explanation of functionality, of operations and of relationships between objects, then users frequently are more comfortable in their native language.

The JS7 help system is intended to empower users by self-learning. It makes use of the following tiered building blocks:

• Interface language from Language Files.
  • Tooltips from Language Files
    • Explanations from Context Help Files
    • Explanations from Context Videos (English language)
• Product Knowledge Base (English language)

General Recommendations

• Consistent wording is key: the same term and spelling should be used whenever the same thing is in question. This applies to Language Files, Context Help Files and Glossary Files.
• Glossary items are focused on objects, not on proceedings. Language File tooltips are focused on proceedings, they explain the user which options are available and what will be the impact when using them.
• Tooltips from Language Files and Context Help Files tend to implement a certain level of redundancy. This can be leveraged by use of glossary items that are referenced by both sources.
• Use of external links should be limited to essential terms, for example, regular expressions or a directed graph, and must make use of a neutral source such as Wikipedia..

Language Files

• Formatting in Language Files is applicable to tooltips.
• Formatting options should be used for the indicated purpose and should be focused on improving readbility, 

Glossary Files 

• Glossry items can recursively reference further glossary items.
• Glossary items should be referenced just once per tooltip or Context Help File. Repeated occurrences of referenced terms can make it with a capitalized first letter if supported by the respective language.

Testing Language Files and Glossary Files

Development Cycle

• Language Files are read by JOC Cockpit on first use. Any changes to a Language File after this point in time are not considered.
• Therefore the following development cycle applies:
  1. Store the working copy of your Language File and Editor Language File in a folder outside of the JOC Cockpit installation.
  2. Start the JOC Cockpit service/daemon.
  3. Copy the your Language File and the locales.json file to the target folder as indicated with the section above.
  4. Log in to JOC Cockpit and optionally modify your user profile to use the newly added language. Any new language added to locales.json should become available with your profile.
  5. Test your changes to the Language File.
  6. Any modifications to a Language File are not immediately considered but require a restart of JOC Cockpit as in step 2).

Language File Build Integration

• For integration in the build procedure please send your Language File to sales@sos-berlin.com or request commit permissions for the GitHub repository https://github.com/sos-berlin/joc-cockpit
• SOS will add your Language File to the build process and will provide nightly builds for download.