Moved all the text translation manipulation into the locale index file

Commented the translation methods

2 files changed, 73 insertions, 14 deletions

diff --git a/app/assets/javascripts/locale/index.js b/app/assets/javascripts/locale/index.js
index c9df5f3723a..7ba676d6d20 100644
--- a/app/assets/javascripts/locale/index.js
+++ b/app/assets/javascripts/locale/index.js
@@ -1,5 +1,9 @@
 import Jed from 'jed';
 
+/**
+  This is required to require all the translation folders in the current directory
+  this saves us having to do this manually & keep up to date with new languages
+**/
 function requireAll(requireContext) { return requireContext.keys().map(requireContext); }
 
 const allLocales = requireAll(require.context('./', true, /^(?!.*(?:index.js$)).*\.js$/));
@@ -16,11 +20,47 @@ let lang = document.querySelector('html').getAttribute('lang') || 'en';
 lang = lang.replace(/-/g, '_');
 
 const locale = new Jed(locales[lang]);
+
+/**
+  Translates `text`
+
+  @param text The text to be translated
+  @returns {String} The translated text
+**/
 const gettext = locale.gettext.bind(locale);
-const ngettext = locale.ngettext.bind(locale);
-const pgettext = (context, key) => {
-  const joinedKey = [context, key].join('|');
-  return gettext(joinedKey).split('|').pop();
+
+/**
+  Translate the text with a number
+  if the number is more than 1 it will use the `pluralText` translation.
+  This method allows for contexts, see below re. contexts
+
+  @param text Singular text to translate (eg. '%d day')
+  @param pluralText Plural text to translate (eg. '%d days')
+  @param count Number to decide which translation to use (eg. 2)
+  @returns {String} Translated text with the number replaced (eg. '2 days')
+**/
+const ngettext = (text, pluralText, count) => {
+  const translated = locale.ngettext(text, pluralText, count).replace(/%d/g, count).split('|');
+
+  return translated[translated.length - 1];
+};
+
+/**
+  Translate context based text
+  Either pass in the context translation like `Context|Text to translate`
+  or allow for dynamic text by doing passing in the context first & then the text to translate
+
+  @param keyOrContext Can be either the key to translate including the context
+                      (eg. 'Context|Text') or just the context for the translation
+                      (eg. 'Context')
+  @param key Is the dynamic variable you want to be translated
+  @returns {String} Translated context based text
+**/
+const pgettext = (keyOrContext, key) => {
+  const normalizedKey = key ? `${keyOrContext}|${key}` : keyOrContext;
+  const translated = gettext(normalizedKey).split('|');
+
+  return translated[translated.length - 1];
 };
 
 export { lang };
diff --git a/app/assets/javascripts/vue_shared/translate.js b/app/assets/javascripts/vue_shared/translate.js
index 07ef00c10d0..ba9656d4e71 100644
--- a/app/assets/javascripts/vue_shared/translate.js
+++ b/app/assets/javascripts/vue_shared/translate.js
@@ -1,23 +1,42 @@
 import {
   __,
   n__,
+  s__,
 } from '../locale';
 
 export default (Vue) => {
   Vue.mixin({
     methods: {
+      /**
+        Translates `text`
+
+        @param text The text to be translated
+        @returns {String} The translated text
+      **/
       __(text) { return __(text); },
-      n__(text, pluralText, count) {
-        const translated = n__(text, pluralText, count).replace(/%d/g, count).split('|');
-        return translated[translated.length - 1];
-      },
-      s__(keyOrContext, key) {
-        const normalizedKey = key ? `${keyOrContext}|${key}` : keyOrContext;
-        // eslint-disable-next-line no-underscore-dangle
-        const translated = this.__(normalizedKey).split('|');
+      /**
+        Translate the text with a number
+        if the number is more than 1 it will use the `pluralText` translation.
+        This method allows for contexts, see below re. contexts
+
+        @param text Singular text to translate (eg. '%d day')
+        @param pluralText Plural text to translate (eg. '%d days')
+        @param count Number to decide which translation to use (eg. 2)
+        @returns {String} Translated text with the number replaced (eg. '2 days')
+      **/
+      n__(text, pluralText, count) { return n__(text, pluralText, count); },
+      /**
+        Translate context based text
+        Either pass in the context translation like `Context|Text to translate`
+        or allow for dynamic text by doing passing in the context first & then the text to translate
 
-        return translated[translated.length - 1];
-      },
+        @param keyOrContext Can be either the key to translate including the context
+                            (eg. 'Context|Text') or just the context for the translation
+                            (eg. 'Context')
+        @param key Is the dynamic variable you want to be translated
+        @returns {String} Translated context based text
+      **/
+      s__(keyOrContext, key) { return s__(keyOrContext, key); },
     },
   });
 };