Translating R Instat

By default, the R-Instat user interface displays English language text. The Options dialog allows the user to change to a different language. Currently, the user can select English, French, Portuguese or Swahili. This page describes how to maintain or improve the current translations. It also describes how to add a new language (e.g. Russian).

The R-Instat translations are generated and managed through the CrowdIn translation system. A guide to using CrowdIn can be found here and a video demonstration can be found here (Danny Parsons, 30 August 2021). This video has more detail than the document.

CrowdIn Manager Notes

The document and video above are aimed at CrowdIn translators. The R-Instat CrowdIn project also has manager roles.

This section contains notes for CrowdIn managers.

Updating the English text in CrowdIn

1. In Visual Studio, open your local R-Instat development project.

2. Ensure the local master is synchronized with remote, and make and checkout a new temporary branch.

3. Open the corresponding JSON file in the translations/en folder.

   

4. Insert, update or delete the corresponding record(s) in the JSON file. Ensure that you follow the correct format.

   

5. Save the updated JSON file. Now you have two options.

• Option 1 (recommended): Commit changes, push to GitHub and make a new PR. When the PR is merged to the master branch, then CrowdIn should detect this, update its repository for all languages and make a PR for all the non-English JSON file changes. You can then jump to step 10 below.
• Option 2: In this option, you do not commit your changes or push to GitHub. Instead you update CrowdIn manually. You may choose this option if you do not want to wait for CrowdIn to detect the English JSON changes in the master branch. For this option, continue with step 6 below.

6. In CrowdIn, open the R-Instat project and select the 'Content' tab.

   

7. For the file you updated, click on the Update button.

   

8. Select the JSON file you just updated. CrowdIn will load the changes and then report the number of inserts/updates/deletes.

9. Your local JSON file is now no longer needed so you can delete the branch.

10. In CrowdIn, add/approve the translations for the newly added English text. If you want a machine pre-translation, then follow the instructions here.

11. Now you need to wait for CrowdIn to open/update a corresponding PR in the R-Instat GitHub repository. When the PR is opened/updated, then you can follow the steps in the section below.

Merging updated translations from CrowdIn to R-Instat

1. When CrowdIn detects changes in either the English or translated text, then it updates the corresponding JSON files and pushes these changes to a PR in the R-Instat GitHub repository.

   

2. Review the changes in the PR. If the PR is OK, then add the label 'skip-releasenotes' and merge the PR. Note that this will only update the JSON files. If you rebuild and run R-Instat, then you will not see the translation changes. We first need to update the translation database (see steps below).

3. In Visual Studio, open your local R-Instat development project. Ensure the local master is synchronized with remote, and make and checkout a new branch.

4. For each updated JSON file, create an equivalent tab-separated file. Each line should have the format <EnglishText><tab><2-letterLanguageCode><tab><TranslatedText>. Note: do not use a comma as a separator because this causes issues with English text that contains a comma.

   

5. You can use a script or an editor to reformat the file from JSON to tab-separated. Tip: If you use VS code, then you can replace characters with tabs by selecting regex mode.

   

6. Save the tab-separated files to a temporary folder.

7. Open DB Browser (or another SQLite client).

8. Open translations/rInstatTranslations.db.

9. Delete all rows in the translations table associated with the languages you are about to import (ensures that any translations no longer needed are removed).

10. Import the tab-separated files.

    

    

11. Write and close the database.

12. In Visual Studio, push the updated database to GitHub.

13. In GitHub, create a PR. Set title to 'Merged CrowdIn changes from PR #xxxx into translations table in database' and assign label 'skip-releasenotes'.

Suggested process when there are multiple translation issues to resolve

If R-Instat UI text is changed/added, then the changed/added text will probably no longer translate. To resolve this, follow the steps above.

Typically, PRs are merged without their associated translation changes. Over a period of months, the translation issues build up. At one point we decide to fix all these translation issues in one go (often prior to creating an R-Instat release for a non-English customer). In this situation, rather than working on each issue individually, it is more efficient to tackle the translations through mass production with different phases:

1. In each issue, for each text string not translated, check if the English text string is in the English JSON file. If not, then add it to to the JSON file. If it was already in the JSON file, then make a note (include the dialog/menu where the problem occurred). When this has been done for all the issues, create a PR for the changed JSON file.

   • Note: Some parts of R-Instat have no translation mechanism implemented (e.g. message boxes and drop-down lists). Please see list in issue #3721 . You don't need to mention these types of issues on the list.

2. Upload to CrowdIn.

3. In CrowdIn, translate new strings to French

4. Merge new translations into database

5. For each text string added to the JSON file, check if the translation now works. If yes (and no other problems), then close the issue. If not, then make a note.

6. For each text string on the lists from phase 1 and phase 5, check that the associated control is correctly listed in the 'form_controls' table in the database. If not, then add to table and retest. Check if the translation now works. If yes (and no other problems), then close the issue. If not, then make a note.

7. Resolve any remaining missing translations and close issues where possible (hopefully the above steps will resolve the vast majority of problems)

8. Fix any positional problems (e.g. French text too long) and close issues where possible

Adding a new language to CrowdIn

1. In CrowdIn, open the RInstat project and go to the 'Home' tab.

2. Click 'Languages', select the language you wish to add (e.g. 'Russian') and click 'Update'.

   

3. On the 'Home' tab, click 'Pre-translation' and select 'via MT'.

   

4. CrowdIn should report how many machine translations it made.

   

5. You now need to approve the machine translations. On the 'Home' tab, click on the language you just added.

   

6. Select the file to approve.

   

7. Click on the 'hamburger' button in the top-left corner to open the main menu. Select 'View' and 'Side-by-Side'.

   

8. Click on the checkbox in the top-left corner; click on ‘Select all x items matching the current filter’ and then click on the tick in middle to approve all translations.

   

9. Repeat the above steps for each of the files you wish to approve.

10. When you've approved all the machine translations, then you need to wait for CrowdIn to open/update a corresponding PR in the R-Instat GitHub repository. You may need to wait a number of hours for this. When the PR is opened/updated, then you can follow the normal steps to merge the new translations into the database (see section above).

11. You also need to add the new language to the R-Instat Options dialog. First find the <language>-<country/region> code (e.g. 'ru-RU'). A list of valid codes is here.

    

12. Update the R-Instat dlgOptions.vb file. PR #7764 gives an example of the changes needed.

Technical Notes

This section contains additional technical notes.

Comments below are taken from Issue #6696, 26 August 2021

As you discovered, at runtime, R-Instat does not always use the label that you specify in Visual Studio Designer. Instead, R-Instat goes to the translation database, finds the control in the form_controls table, and then uses the text in the form_controls.id_text column (see below).

That is why, at runtime, R-Instat still displays 'Missing Options'.

The solution is to update the database with the required text. This should happen automatically when I regenerate the database for the next release. If you would like to see/test the changes inside your PR, then you can update the database manually (let me know if you'd like to do this, and I can show you how).

@Patowhiz - when we discussed this morning, we considered changing R-Instat so that if the display language is English, then R-Instat should not use the translation database, and just use the text specified in the Visual Studio designer. However I thought more about this. I think we always have to use the translation database, even when the display language is English. This is because we cannot assume that the control's text is the display text. This is because the control's text is actually used to populate form_controls.id_text, which in turn is used as a key in the translations table. Normally, the English text works fine as the key but there are occasions when we need to specify context information. For example if we want to translate the English word 'data' to 2 different French words in 2 dialogs, then we need to specify form_controls.id_text as 'data1' and 'data2' to allow 2 different French translations. I'm not sure if I explained that clearly, I'm hapy to discuss if needed.

Notes taken from Rachel Kirk-Gushowaty email, 24 August 2021

There are definitely some newer terms which were not in the ISI glossary. I have searched online to the best of my ability (Reverso.com is a really useful site for this) and sometimes just opted for what sounds logical. If there were an opportunity to go through some of the remaining questions with a french speaking statistician that would be a great final step. I worked to standardise terms in Crowdin so that we have consistency throughout the program.

Something to note for the Swahili team checking is that due to the concise nature of our English, Crowdin frequently assumes our verbs are nouns (e.g: Group Data, it assumes is A Group of Data but we mean To Group the Data). This changes the meaning significantly and is good to have in mind when reviewing

Resources

• ISI produced translations of statistical terms into 31 languages (link). Please see issue #6504 for further details.