Merge pull request #877 from Arkkimaagi/better-translations

Improve translation flexibility

CHANGELOG.md

@@ -17,12 +17,15 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Add test of match current week number on clock module with showWeek configuration.
 - Add test default modules present modules/default/defaultmodules.js.
 - Add unit test calendar_modules function capFirst.
+- Add support for writing translation fucntions to support flexible word order
 - Add test for check if exits the directories present in defaults modules.
 - Add ability for `currentweather` module to display indoor temperature via INDOOR_TEMPERATURE notification
 
+
 ### Updated
 - Added missing keys to Polish translation.
 - Added missing key to German translation.
+- Added better translation with flexible word order to Finnish translation
 
 ### Fixed
 - Fix instruction in README for using automatically installer script.

js/module.js

@@ -272,14 +272,18 @@ var Module = Class.extend({
 		}
 	},
 
-	/* translate(key, defaultValue)
-	 * Request the translation for a given key.
+	/* translate(key, defaultValueOrVariables, defaultValue)
+	 * Request the translation for a given key with optional variables and default value.
 	 *
-	 * argument key string - The key of the string to translage
-   * argument defaultValue string - The default value if no translation was found. (Optional)
+	 * argument key string - The key of the string to translate
+   * argument defaultValueOrVariables string/object - The default value or variables for translating. (Optional)
+   * argument defaultValue string - The default value with variables. (Optional)
 	 */
-	translate: function (key, defaultValue) {
-		return Translator.translate(this, key) || defaultValue || "";
+	translate: function (key, defaultValueOrVariables, defaultValue) {
+		if(typeof defaultValueOrVariables === "object") {
+			return Translator.translate(this, key, defaultValueOrVariables) || defaultValue || "";
+		}
+		return Translator.translate(this, key) || defaultValueOrVariables || "";
 	},
 
 	/* updateDom(speed)

js/translator.js

@@ -111,32 +111,47 @@ var Translator = (function() {
 		translations: {},
 		translationsFallback: {},
 
-		/* translate(module, key)
+		/* translate(module, key, variables)
 		 * Load a translation for a given key for a given module.
 		 *
 		 * argument module Module - The module to load the translation for.
 		 * argument key string - The key of the text to translate.
+		 * argument variables - The variables to use within the translation template (optional)
 		 */
-		translate: function(module, key) {
+		translate: function(module, key, variables) {
+			variables = variables || {}; //Empty object by default
+
+			// Combines template and variables like:
+			// template: "Please wait for {timeToWait} before continuing with {work}."
+			// variables: {timeToWait: "2 hours", work: "painting"}
+			// to: "Please wait for 2 hours before continuing with painting."
+			function createStringFromTemplate(template, variables) {
+				if(variables.fallback && !template.match(new RegExp("\{.+\}"))) {
+					template = variables.fallback;
+				}
+				return template.replace(new RegExp("\{([^\}]+)\}", "g"), function(_unused, varName){
+					return variables[varName] || "{"+varName+"}";
+				});
+			}
 
 			if(this.translations[module.name] && key in this.translations[module.name]) {
 				// Log.log("Got translation for " + key + " from module translation: ");
-				return this.translations[module.name][key];
+				return createStringFromTemplate(this.translations[module.name][key], variables);
 			}
 
 			if (key in this.coreTranslations) {
 				// Log.log("Got translation for " + key + " from core translation.");
-				return this.coreTranslations[key];
+				return createStringFromTemplate(this.coreTranslations[key], variables);
 			}
 
 			if (this.translationsFallback[module.name] && key in this.translationsFallback[module.name]) {
 				// Log.log("Got translation for " + key + " from module translation fallback.");
-				return this.translationsFallback[module.name][key];
+				return createStringFromTemplate(this.translationsFallback[module.name][key], variables);
 			}
 
 			if (key in this.coreTranslationsFallback) {
 				// Log.log("Got translation for " + key + " from core translation fallback.");
-				return this.coreTranslationsFallback[key];
+				return createStringFromTemplate(this.coreTranslationsFallback[key], variables);
 			}
 
 			return key;

modules/README.md

@@ -429,6 +429,51 @@ this.translate("INFO") //Will return a translated string for the identifier INFO
 
 **Note:** although comments are officially not supported in JSON files, MagicMirror allows it by stripping the comments before parsing the JSON file. Comments in translation files could help other translators.
 
+#####`this.translate(identifier, variables)`
+***identifier* String** - Identifier of the string that should be translated.
+***variables* Object** - Object of variables to be used in translation.
+
+This improved and backwards compatible way to handle translations behaves like the normal translation function and follows the rules described above. It's recommended to use this new format for translating everywhere. It allows translator to change the word order in the sentence to be translated.
+
+
+**Example:**
+````javascript
+var timeUntilEnd = moment(event.endDate, "x").fromNow(true);
+this.translate("RUNNING", { "timeUntilEnd": timeUntilEnd) }); // Will return a translated string for the identifier RUNNING, replacing `{timeUntilEnd}` with the contents of the variable `timeUntilEnd` in the order that translator intended.
+````
+
+**Example English .json file:**
+````javascript
+{
+	"RUNNING": "Ends in {timeUntilEnd}",
+}
+````
+
+**Example Finnish .json file:**
+````javascript
+{
+	"RUNNING": "Päättyy {timeUntilEnd} päästä",
+}
+````
+
+**Note:** The *variables* Object has an special case called `fallback`. It's used to support old translations in translation files that do not have the variables in them. If you are upgrading an old module that had translations that did not support the word order, it is recommended to have the fallback layout.
+
+**Example:**
+````javascript
+var timeUntilEnd = moment(event.endDate, "x").fromNow(true);
+this.translate("RUNNING", {
+	"fallback": this.translate("RUNNING") + " {timeUntilEnd}"
+	"timeUntilEnd": timeUntilEnd
+)}); // Will return a translated string for the identifier RUNNING, replacing `{timeUntilEnd}` with the contents of the variable `timeUntilEnd` in the order that translator intended. (has a fallback)
+````
+
+**Example swedish .json file that does not have the variable in it:**
+````javascript
+{
+	"RUNNING": "Slutar",
+}
+
+In this case the `translate`-function will not find any variables in the translation, will look for `fallback` variable and use that if possible to create the translation.
 
 ## The Node Helper: node_helper.js
 

modules/default/calendar/calendar.js

@@ -265,7 +265,12 @@ Module.register("calendar", {
 						}
 					}
 				} else {
-					timeWrapper.innerHTML = this.capFirst(this.translate("RUNNING")) + " " + moment(event.endDate, "x").fromNow(true);
+					timeWrapper.innerHTML = this.capFirst(
+						this.translate("RUNNING", {
+							fallback: this.translate("RUNNING") + " {timeUntilEnd}",
+							timeUntilEnd: moment(event.endDate, "x").fromNow(true)
+						})
+					);
 				}
 			}
 			//timeWrapper.innerHTML += ' - '+ moment(event.startDate,'x').format('lll');

translations/fi.json

@@ -4,7 +4,7 @@
 	"TODAY": "Tänään",
 	"TOMORROW": "Huomenna",
 	"DAYAFTERTOMORROW": "Ylihuomenna",
-	"RUNNING": "Meneillään",
+	"RUNNING": "Päättyy {timeUntilEnd} päästä",
 	"EMPTY": "Ei tulevia tapahtumia.",
 
 	"N": "P",