Translation procedure

This page describes the procedure one has to go through in order to add a new field to the translation sheet and successfully update the translation sheet within ClimApp.

As the procedure is not finalized yet, this page will be updated continuously during the following days

Overview

• Structure of translation sheet
  • Panes
  • Planning sheet content
• How to add new text to ClimApp
  • General procedure
  • Updating the ClimApp JSON translation file for the app

Structure of the translation sheet

This section gives an introduction to the Excel sheet and how to understand and update its content.

Panes

The translation sheet has a total of 6 panes, translation_guide, planning, labels, sentences, toasts, wheels, api, abbreviations, list_options and template. The different panes and their content are described below.

Pane	Description	Needed to update translations?
translation_guide	Page describing how to translate the contents of the translation sheet panes	-
labels	All single-word (and some two-word) strings in ClimApp	✔️
sentences	All sentences used in ClimApp	✔️
toasts	All toast text ClimApp (the text shown in pop-up window at bottom of screen)	✔️
wheels	All text related to wheels in ClimApp	✔️
api	All text that is updated through Sensationmaps API (need a different procedure for translation)	✔️
abbreviations	List of all abbreviations used in the planning sheet (for streamlining purposes)	-
list_options	Options to choose from (used in planning)	-
template	An overview of the content of the translation sheet	-

Available languages

Currently, the languages following languages are available in the app.

• English (en)
• Danish (dk)
• Norwegian (no/nn/nb)

If new languages are added to the translation sheet, they also need to be added to the allowed languages in the codebase!

To do this, the variable availableLanguages in the getLanguage(locale) method need to be updated.

These languages are expected to be:

• Greek (el)
• French (fr)
• Dutch (nl)
• Spanish (es)
• Italian (it)
• German (de)

Planning sheet content

The planning sheet was used to create an overview of all strings in ClimApp when migrating from hard coded values to dynamically set values using the translation sheet. Updating this for each new text in the app might not be needed.

The planning sheet contains all information about the different text used in ClimApp. The text is divided into different section depending on what kind of string it is.

• Most single-word strings and two-word string are labelled as strings and get the prefix str_. These strings are often used as labels, headers in panels or as button texts.
• All text shown in toasts are labelled as toasts and have the prefix toast
• Text used in wheels, (title, description and labels) are labelled wheels and stored in JSON object structures as the one below. This follows the structure as already implemented in ClimApp.

"wheels": {
        "activity": {
            "title": {
                "en": "What is your activity level?",
                "da": "Hvad er dit aktivitetsniveau?"
            },
            "description": {
                "rest": {
                    "en": "Resting, sitting at ease.\\nBreathing not challenged.",
                    "da": "Hviler, sidder i ro. Vejrtr\u00e6kning ikke udfordret"
                },
  ...

Field	Description	Comments
text type	The text type	select by using drop-down
page	The name of the HTML page where the information is used	select by using drop-down
pane reference	The pane in which the translation for the field is located	Select by using drop-down
wheel name	An indication of the wheel that the information is used for	added to make it easier to identify the place in the code that needs to be updated
text	the actual text to be added in the application
hasID?	Values 0 or 1 indicating whether an ID is given in the source code (this ID can be used when setting the text programatically)	This is shown as either red(no) or green (yes) in the spreadsheet.
current_id	the element id of the text (if exist) in the code
suggested_id	the suggested field id to be referenced from the translations.json file
static/API/system	an indication of the type of the and how it is updated within the code	select by using drop-down
concatenated text?	an indication of whether the text in the code is concatenated with other text (might make the implementation a little more complex)
logic dependent on text?	is the text in the field used directly as part of any logic (if so, it is important to also change the dependent text in the code)

How to add new text

Before going through the general procedure, read the contents of the translation_guide pane in the translation sheet

General procedure

• Open the translation sheet
• Go to the pane planning and fill out:
  • text types - (use the drop down menu)
  • page - the page where the information currently exist (use the drop down menu)
  • wheel name (optional) only if the content you are creating is for a new wheel
  • text - the actual text you want to add
  • current_id - the ID (if it exist) used in the code base
  • suggested_id (auto-filled) the suggested ID based on the information you provided
  • static/API/system - and indication of what type of text you are filling out
    • static - text that is not changed
    • API - text field that will be updated by third-party (API)
    • system - a text value only used within the system
  • Concatenated_text? (0/1) - an indication of whether the text will be concatenated with other text (as this might increase the complexity of the implementation)
  • Logic dependent on text? (1/0) - an indication of whether the raw text is used directly in conjunction with any part of the code logic (if so, it is important that, if the text is changed, the dependent code is also changed)
• Add the text to the associated pane strings, toasts or wheels (based on whether your new text is for a wheel, general text or a toast)
• If the translations have not already been approved, get the translations approved by xx

Updating the ClimApp JSON translation file for the app

For developers

• Convert the pane(s) with new information to a .csv-file by clicking File -> Download -> Comma separated values (.csv)
• Save the file in the translations folder as (the automatically suggested title):
  • labels: climapp_translation_sheet - labels.csv
  • sentences: climapp_translation_sheet - sentences.csv
  • wheels: climapp_translation_sheet - wheels.csv
  • toasts: climapp_translation_sheet - toasts.csv
  • api: climapp_translation_sheet - api.csv
  • feedback: climapp_translation_sheet - feedback.csv
  • this is important for the fiels to be able to be read by the python converter
• Run the convertTranslationsCSVToJSON.py file in ClimApp\cordova\climapp\www\translations (it will generate a translations.json file.)
  • The log output from a successful run of the script is shown below
  • Make sure that new languages are updated in all panes, for all values! (see the log to get an overview of the included languages)
  • The script will tell you if something is off, check the log.
• Run the application to test that the new translation have been added as expected.

Backup

When running convertTranslationCSVToJSON.py the old translation file will automatically be backed up in translations/archive folder using the current date.