Feature/interface clarifications

.editorconfig

@@ -12,3 +12,6 @@ indent_size = 4
 charset = utf-8
 insert_final_newline = true
 trim_trailing_whitespace = true
+
+[**/package.json]
+indent_size = 2

README.md

@@ -182,6 +182,12 @@ $ yarn gulp [SUBCOMMAND ...] [OPTIONS]
 
 [12]: frontend/README.md#gulp-tasks-and-options
 
+Extract translation strings in the frontend:
+
+```console
+$ yarn localize
+```
+
 
 ### Notes on Python package dependencies
 

frontend/README.md

@@ -165,6 +165,38 @@ Each `browserLibs` item may have the following properties.
 [17]: https://www.npmjs.com/package/gulp-cdnizer#optionsfilescdn
 
 
+### Translations management
+
+In principle, all strings that are shown to users should be translatable. In TypeScript files, the localized strings are obtained from a call to `i18next.t()`. In Handlebars templates, the `{{i18n}}` helper serves the same purpose. It is more often found in the block notation `{{#i18n}}...{{/i18n}}`, where the `...` part defines the default.
+
+
+#### Extracting translation strings
+
+The JSON files in `src/i18n` can be compiled automatically from the TypeScript and Handlebars sources using the following command:
+
+```
+yarn i18next -c i18next-parser.config.mjs
+```
+
+The files thus produced can be sent to the translators in order to fill out the actual translations.
+
+Defaults sometimes start or end with spaces. `i18next` will strip them, but in some cases they need to be retained. The following trick will preserve those spaces and prevent `i18next` from stripping them again in the future:
+
+1. Manually edit `src/i18n/en/translation.json` to put the spaces back and commit.
+2. Run `i18next` to autogenerate the translation files. This will strip the spaces from the `translation.json` that you just hand-edited in. However, a copy of your hand-edited strings is retained in `src/i18n/en/translation_old.json`.
+3. Run `git checkout HEAD src/i18n/en/translation.json` to restore your hand-edited strings in the main `translation.json` as well.
+4. Commit the `translation_old.json`.  Because both the `translation.json` and the `translation_old.json` contain your hand-edited version of the string, `i18next` will remember not to strip the spaces again in the future.
+
+The above trick can also be used in other situations where you want to prevent `i18next` from overriding what is in the `translation.json`, for example if you decide to remove a default value from the source files altogether.
+
+
+#### Adding new languages
+
+1. Extend the list of `locales` in `i18next-parser.config.mjs`.
+2. Follow the steps in the previous section to obtain the corresponding JSON file(s).
+3. Edit `src/global/i18n.ts` to ensure that the new language(s) is/are taken into account.
+
+
 ### Proxy configuration
 
 Suppose you have a backend application running on `localhost:8000` and you want to forward all requests for `/api` to this backend application. Create a JSON file with the following content:

frontend/i18next-parser.config.mjs

@@ -0,0 +1,15 @@
+import HbsI18nLexer from 'handlebars-i18next-parser';
+
+const sourceDir = 'src';
+const i18nDir = `${sourceDir}/i18n`;
+
+export default {
+    input: [`${sourceDir}/**/*.{t,hb}s`, `!${sourceDir}/**/*-te{mplate,st}.ts`],
+    output: `${i18nDir}/$LOCALE/$NAMESPACE.json`,
+    locales: ['en', 'fr'],
+    resetDefaultValueLocale: 'en',
+    indentation: 4,
+    lexers: {
+        hbs: [HbsI18nLexer],
+    },
+};

frontend/package.json

@@ -78,8 +78,9 @@
         "gulp-sass": "^5.0.0",
         "gulp-sourcemaps": "^2.6.4",
         "gulp-uglify": "^3.0.1",
-        "handlebars": "^4.7.7",
+        "handlebars-i18next-parser": "^1.0.2",
         "http-proxy-middleware": "^0.19.0",
+        "i18next-parser": "^6.0.1",
         "jasmine-ajax": "^4.0.0",
         "jasmine-core": "~3.5.0",
         "jasmine-terminal-reporter": "^1.0.3",

frontend/src/explorer/explorer-event-controller.ts

@@ -172,7 +172,7 @@ class ExplorerEventController {
         const flatItems = new FlatItemCollection(items);
         const filteredItems = new FilteredCollection(flatItems, 'annotation');
         const resultView = new SearchResultListPanel({
-            title:i18next.t('heading.annotations', 'Annotations'),
+            title:i18next.t('annotation.list-title', 'Annotations'),
             model: item,
             collection: filteredItems,
             selectable: false,
@@ -311,10 +311,15 @@ class ExplorerEventController {
             landing = false;
         }
         const title = `${landing ? 'My' : 'Sample'} ${queryMode}`;
+        const i18nKey = `button.${title.toLowerCase().replace(' ', '-')}`;
         const endpoint = `${queryMode}:${landing ? 'user' : 'sample'}`;
         const collection = new FlatItemCollection(ldChannel.request(endpoint));
         const browsePanel = new SearchResultListPanel({
-            title,
+            // i18next.t('button.my-sources', 'My sources');
+            // i18next.t('button.sample-sources', 'Sample sources');
+            // i18next.t('button.my-items', 'My items');
+            // i18next.t('button.sample-items', 'Sample items');
+            title: i18next.t(i18nKey, title),
             collection,
             selectable: false,
         });

frontend/src/feedback/feedback-template.hbs

@@ -3,53 +3,70 @@
     <form class="box register-form is-narrow-modal-form">
         {{#if wasSentSuccessfully}}
         <header>
-            <h3 class="title is-3 page-header">Feedback submitted</h3>
+            <h3 class="title is-3 page-header">
+                {{#i18n 'feedback.success-heading'
+                }}Feedback submitted{{/i18n}}
+            </h3>
         </header>
         <div class="field">
-            <p>Thank you very much for your feedback, it is highly appreciated!</p>
+            <p>{{#i18n 'feedback.thanks'}}Thank you very much for your feedback, it is highly appreciated!{{/i18n}}</p>
         </div>
         <div class="field is-grouped">
             <div class="control">
-                <button class="button btn-close" type=button>Close</button>
+                <button class="button btn-close" type=button>{{#i18n 'button.close'}}Close{{/i18n}}</button>
             </div>
         </div>
         {{else}}
         <header>
-            <h3 class="title is-3 page-header">Feedback</h3>
+            <h3 class="title is-3 page-header">{{#i18n 'feedback.form-heading'}}Feedback{{/i18n}}</h3>
         </header>
         <div class="field">
-            <label class="label">Subject</label>
+            <label class="label">{{#i18n 'label.subject'}}Subject{{/i18n}}</label>
             <div class="control">
-                <input name="subject" class="input" type="text" name="title" placeholder="About READ-IT">
+                <input
+                    name="subject"
+                    class="input"
+                    type="text"
+                    name="title"
+                    placeholder="{{#i18n 'placeholder.feedback-subject'}}About READ-IT{{/i18n}}"
+                >
             </div>
         </div>
 
         <div class="field">
             <div class="control">
-                <label class="label">Feedback</label>
-                <textarea name="feedback" class="textarea" placeholder="e.g. I love READ-IT!"></textarea>
+                <label class="label">{{#i18n 'label.feedback'}}Feedback{{/i18n}}</label>
+                <textarea
+                    name="feedback"
+                    class="textarea"
+                    placeholder="{{#i18n 'placeholder.feedback-content'}}e.g. I love READ-IT!{{/i18n}}"
+                ></textarea>
             </div>
         </div>
 
         {{#if hasError}}
         <div class="field form-feedback-bar has-background-danger has-text-white">
-            <p class="help">Feedback submission failed. Please try again and if this error keeps occuring, contact the
-                site administrator.</p>
+            <p class="help">{{#i18n 'feedback.failed'}}Feedback submission failed. Please try again and if this error keeps occuring, contact the
+                site administrator.{{/i18n}}</p>
         </div>
         {{/if}}
 
         <div class="field is-grouped">
             <div class="control">
-                <button class="button is-link btn-submit" type=submit>Submit</button>
+                <button class="button is-link btn-submit" type=submit>{{#i18n 'button.submit'}}Submit{{/i18n}}</button>
             </div>
 
             <div class="control">
-                <button class="button btn-close" type=button>Close</button>
+                <button class="button btn-close" type=button>{{#i18n 'button.close'}}Close{{/i18n}}</button>
             </div>
         </div>
         {{/if}}
 
     </form>
 
 </div>
-<button type=button modal-close is-large" aria-label="close"></button>
+<button
+    type=button
+    class="modal-close is-large"
+    aria-label="{{#i18n 'button.close'}}Close{{/i18n}}"
+></button>

frontend/src/footer/footer-template.hbs

@@ -1,5 +1,5 @@
 <figure class="footer-dh">
-    <p>Developed by</p>
+    <p>{{#i18n 'footer.developed-by'}}Developed by{{/i18n}}</p>
     <a href="https://dig.hum.uu.nl" target="_blank"><img class="dhlab"
             src="{{static 'image/dighum-logo-blue.svg'}}"></a>
     <div class="footer-project is-pulled-right">

frontend/src/forms/add-button-template.hbs

@@ -1,4 +1,4 @@
 <button type=button class="button is-success">
-    <span>Add</span>
+    <span>{{#i18n 'button.add'}}Add{{/i18n}}</span>
     <span class="icon is-small"><i class="fas fa-plus"></i></span>
 </button>

frontend/src/forms/ontology-class-picker-children-view.ts

@@ -4,6 +4,7 @@ import FlatItemCollection from '../common-adapters/flat-item-collection';
 import FlatItem from '../common-adapters/flat-item-model';
 import { CollectionView } from '../core/view';
 import attachTooltip from '../tooltip/tooltip-view';
+import toTooltip from '../tooltip/tooltip-model';
 import { animatedScroll, getScrollTop } from '../utilities/scrolling-utilities';
 import OntologyClassPickerItemView from './ontology-class-picker-item-view';
 
@@ -26,7 +27,7 @@ export default class OntologyClassPickerChildrenView extends CollectionView<
         const item = new OntologyClassPickerItemView({ model }).on({
             click: this.onItemClicked,
         }, this);
-        attachTooltip(item, { model });
+        attachTooltip(item, { model: toTooltip(model) });
         return item;
     }
 

frontend/src/forms/ontology-class-picker-template.hbs

@@ -1,7 +1,7 @@
 <div class="dropdown">
     <div class="dropdown-trigger">
         <button type=button class="button" aria-haspopup="true" aria-controls="dropdown-menu">
-            <span class="dropdown-label">This is a
+            <span class="dropdown-label">{{#i18n 'annotation.define-category'}}This is a{{/i18n}}
                 <span class="dropdown-label-tag">...</span>
             </span>
             <span class="icon is-small">

frontend/src/forms/ontology-class-picker-view.ts

@@ -6,6 +6,8 @@ import { skos } from '../common-rdf/ns';
 import { CollectionView } from '../core/view';
 import LabelView from '../label/label-view';
 import attachTooltip from '../tooltip/tooltip-view';
+import toTooltip from '../tooltip/tooltip-model';
+
 import OntologyClassPickerChildrenView from './ontology-class-picker-children-view';
 import OntologyClassPickerItemView from './ontology-class-picker-item-view';
 import ontologyClassPickerTemplate from './ontology-class-picker-template';
@@ -34,7 +36,7 @@ export default class OntologyClassPickerView extends CollectionView<
             click: this.onItemClicked,
             hover: this.isNonLeaf(model) ? this.onSuperclassHovered : undefined,
         }, this);
-        attachTooltip(item, { model, direction: 'left' });
+        attachTooltip(item, { model: toTooltip(model), direction: 'left' });
         return item;
     }
 

frontend/src/forms/remove-button-template.hbs

@@ -1,4 +1,4 @@
 <button type=button class="button is-danger">
-    <span>Remove</span>
+    <span>{{#i18n 'button.remove'}}Remove{{/i18n}}</span>
     <span class="icon is-small"><i class="fas fa-times"></i></span>
 </button>

frontend/src/global/annotation-hierarchy.ts

@@ -31,27 +31,27 @@ const hierarchyPromise = i18nPromise.then(() => {
         collection: new Collection([{
             model: new Model({
                 id: 'mine',
-                label: i18next.t('filterHierarchy.mine', 'by me'),
+                label: i18next.t('annotation.filters.mine', 'by me'),
                 cssClass: 'rit-self-made',
             }),
         }, {
             model: new Model({
                 id: 'others',
-                label: i18next.t('filterHierarchy.others', 'by others'),
+                label: i18next.t('annotation.filters.others', 'by others'),
                 cssClass: 'rit-other-made',
             }),
         }]),
     }, {
         collection: new Collection([{
             model: new Model({
                 id: 'verified',
-                label: i18next.t('filterHierarchy.verified', 'verified'),
+                label: i18next.t('annotation.filters.verified', 'verified'),
                 cssClass: 'rit-verified',
             }),
         }, {
             model: new Model({
                 id: 'unverified',
-                label: i18next.t('filterHierarchy.unverified', 'unverified'),
+                label: i18next.t('annotation.filters.unverified', 'unverified'),
                 cssClass: 'rit-unverified',
             }),
         }]),
@@ -60,14 +60,14 @@ const hierarchyPromise = i18nPromise.then(() => {
     fullHierarchy.add([{
         model: new Model({
             id: 'semantic',
-            label: i18next.t('filterHierarchy.semantic', 'human'),
+            label: i18next.t('annotation.filters.semantic', 'human'),
             cssClass: 'rit-is-semantic',
         }),
         collection: semanticHierarchy,
     }, {
         model: new Model({
             id: 'nlp',
-            label: i18next.t('filterHierarchy.nlp', 'automated'),
+            label: i18next.t('annotation.filters.nlp', 'automated'),
             cssClass: 'rit-is-nlp',
         }),
         collection: nlpHierarchy,

frontend/src/global/i18n.ts

@@ -1,27 +1,33 @@
-import { Deferred } from 'jquery';
+import { constant } from 'lodash';
 import * as i18next from 'i18next';
 import * as languageDetector from 'i18next-browser-languagedetector';
 
-import * as french from '../i18n/fr.json';
+import * as english from '../i18n/en/translation.json';
+import * as french from '../i18n/fr/translation.json';
+import channel from '../i18n/radio';
 
-const deferred = Deferred();
-const i18nPromise = deferred.promise();
-
-i18next.use(
-    languageDetector
-).init({
-    fallbackLng: ['en', 'dev'],
-    resources: {
-        fr: {
-            translation: french,
+const i18nPromise = new Promise(function(resolve, reject) {
+    i18next.use(
+        languageDetector
+    ).init({
+        fallbackLng: ['en', 'dev'],
+        resources: {
+            en: {
+                translation: english,
+            },
+            fr: {
+                translation: french,
+            },
         },
-    },
-}, function(error, t) {
-    if (error) {
-        deferred.reject(error);
-    } else {
-        deferred.resolve(i18next);
-    }
+    }, function(error, t) {
+        if (error) {
+            reject(error);
+        } else {
+            resolve(i18next);
+        }
+    });
 });
 
+channel.reply('i18next', constant(i18nPromise));
+
 export { i18nPromise, i18next };