Translating Simulator Into Different Languages

Abstract

The simulator is the core product of CircuitVerse and requires fair attention in the perspective of internationalization.

The general UI interface of the Simulator is written in Rails ERB template files (Views) and can be localised simply using Rails I18n.

The Simulator's core functionality is written in JavaScript (ES6 modules), located at simulator/src and are bundled and served using Webpacker on the frontend.

We cannot use Rails I18n in the Webpacker served JavaScript modules. We provide translations in such modules using JavaScript Internationalization library banana-i18n.

Translation Directory

Translations for the Simulator are stored in JSON file format and can be located at the location simulator/i18n/locale.json

The name of the translation files start with the locale value eg. en.json, hi.json etc and shall be named carefully. For the curated list of the locale names kindly visit Locale Name List.

Add translations for existing supported languages or create a new JSON file in the format of locale.json to add support for new languages.

Localizing Existing String Resource

The simulator is already localized for the English language. Translation file simulator/i18n/en.json can be used as a boilerplate to add support for the new languages.

• Create translation file for the new language eg. zh.json (ignore if the file already exists) and copy the content of the boilerplate into the new translation file.
• Edit metadata as well as replace the translations present in the English language with the new language.
• Support for new language will get added successfully.

Localizing New String Resource

The banana-i18n library offers a translation function that fetches string from the string resource(JSON files ) and displays translations according to the current language.

If a new JavaScript module or an existing module with new strings to be localized -

• Import banana-i18n library into the JavaScript module using import banana from './i18n';

• Use translation function banana.i18n('key_name') in place of string

• Place string into the translation file in the form of key-value pair ```"key_name": "String,"

  Note: Last key-value pair of the translation file must not contain comma , at its end.

Localization Rules for the Simulator

• Start key name with the module name where the strings belong to.

  Eg: For the string present in tutorials.js, the key name should start with "tutorials-<key_suffix>".

• Give suitable suffix to the key name so that purpose of the key is clear.

  Eg: tutorials-bug-guide-title, tutorials-bug-guide-description

• Use interpolation if the variable is used inside strings via template literals

  we can use banana-i18n interpolation syntax $1, $2, $3... as follows -

  Eg:

  Before: In the JavaScript module

  `Are you sure want to delete: ${variable1} and ${variable2}\nThis cannot be undone.`
  
  

  After: In the JavaScript module

  Pass variable/logic into banana.i18n function

   banana.i18n('key-name', variable1, variable2);
  
  

  After: In Translation File

   "key-name": "Are you sure want to delete: $1 and $2\nThis cannot be undone.    
  
  

  Here $1 will be replaced by variable1 and $2 by variable2 in order.

• banana-i18n library renders HTML tag without the need for any explicit configuration. If the string contains HTML without any interpolation of variables, the string can be fully extracted with HTML into a translation file.

  Eg:

  Before: In the JavaScript module

   "<p>Enter Input names separated by commas: <input id='inputNameList' type='text'  placeHolder='eg. In A, In B'></p>"
  

  After: In the JavaScript module

   banana.i18n('key-name')
  
  

  After: In translation File

   "key-name": "<p>Enter Input names separated by commas: <input id='inputNameList' type='text'  placeHolder='eg. In A, In B'></p>"