Add translator documentation

front/src/Translator/Translator.ts

@@ -10,6 +10,10 @@ type LanguageObject = {
     [key: string]: string | LanguageObject;
 };
 
+type TranslationParams = {
+    [key: string]: string | number
+};
+
 class Translator {
     public readonly fallbackLanguage: Language = this.getLanguageByString(FALLBACK_LANGUAGE) || {
         language: "en",
@@ -18,7 +22,14 @@ class Translator {
 
     private readonly fallbackLanguageObject: LanguageObject = FALLBACK_LANGUAGE_OBJECT as LanguageObject;
 
+    /**
+     * Current language
+     */
     private currentLanguage: Language;
+
+    /**
+     * Contain all translation keys of current language
+     */
     private currentLanguageObject: LanguageObject;
 
     public constructor() {
@@ -28,6 +39,11 @@ class Translator {
         this.defineCurrentLanguage();
     }
 
+    /**
+     * Get language object from string who respect the RFC 5646
+     * @param {string} languageString RFC 5646 formatted string
+     * @returns {Language|undefined} Language object who represent the languageString
+     */
     public getLanguageByString(languageString: string): Language | undefined {
         const parts = languageString.split("-");
         if (parts.length !== 2 || parts[0].length !== 2 || parts[1].length !== 2) {
@@ -41,10 +57,19 @@ class Translator {
         };
     }
 
+    /**
+     * Get a string who respect the RFC 5646 by a language object
+     * @param {Language} language A language object
+     * @returns {string|undefined} String who represent the language object
+     */
     public getStringByLanguage(language: Language): string | undefined {
         return `${language.language}-${language.country}`;
     }
 
+    /**
+     * Add the current language file loading into Phaser loader queue
+     * @param {Phaser.Loader.LoaderPlugin} pluginLoader Phaser LoaderPLugin
+     */
     public loadCurrentLanguageFile(pluginLoader: Phaser.Loader.LoaderPlugin) {
         const languageString = this.getStringByLanguage(this.currentLanguage);
         pluginLoader.json({
@@ -53,6 +78,11 @@ class Translator {
         });
     }
 
+    /**
+     * Get from the Phase cache the current language object and promise to load it
+     * @param {Phaser.Cache.CacheManager} cacheManager Phaser CacheManager
+     * @returns {Promise<void>} Load current language promise
+     */
     public loadCurrentLanguageObject(cacheManager: Phaser.Cache.CacheManager): Promise<void> {
         return new Promise((resolve, reject) => {
             const languageObject: Object = cacheManager.json.get(
@@ -68,6 +98,11 @@ class Translator {
         });
     }
 
+    /**
+     * Get the language for RFC 5646 2 char string from availables languages
+     * @param {string} languageString Language RFC 5646 string
+     * @returns {Language|undefined} Language object who represent the languageString
+     */
     public getLanguageWithoutCountry(languageString: string): Language | undefined {
         if (languageString.length !== 2) {
             return undefined;
@@ -87,6 +122,9 @@ class Translator {
         return languageFound;
     }
 
+    /**
+     * Define the current language by the navigator or a cookie
+     */
     private defineCurrentLanguage() {
         const navigatorLanguage: string | undefined = navigator.language;
         const cookieLanguage = getCookie("language");
@@ -116,8 +154,14 @@ class Translator {
         this.currentLanguage = currentLanguage;
     }
 
-    private getObjectValueByPath(path: string, object: LanguageObject): string | undefined {
-        const paths = path.split(".");
+    /**
+     * Get value on object by property path
+     * @param {string} key Translation key
+     * @param {LanguageObject} object Language object
+     * @returns {string|undefined} Found translation by path
+     */
+    private getObjectValueByPath(key: string, object: LanguageObject): string | undefined {
+        const paths = key.split(".");
         let currentValue: LanguageObject | string = object;
 
         for (const path of paths) {
@@ -135,7 +179,13 @@ class Translator {
         return currentValue;
     }
 
-    private formatStringWithParams(string: string, params: { [key: string]: string | number }): string {
+    /**
+     * Replace {{ }} tags on a string by the params values
+     * @param {string} string Translation string
+     * @param {{ [key: string]: string | number }} params Tags to replace by value
+     * @returns {string} Formatted string
+     */
+    private formatStringWithParams(string: string, params: TranslationParams): string {
         let formattedString = string;
 
         for (const param in params) {
@@ -146,7 +196,13 @@ class Translator {
         return formattedString;
     }
 
-    public _(key: string, params?: { [key: string]: string | number }): string {
+    /**
+     * Get translation by a key and formatted with params by {{ }} tag
+     * @param {string} key Translation key
+     * @param {{ [key: string]: string | number }} params Tags to replace by value
+     * @returns {string} Translation formatted
+     */
+    public _(key: string, params?: TranslationParams): string {
         const currentLanguageValue = this.getObjectValueByPath(key, this.currentLanguageObject);
 
         if (currentLanguageValue) {