@knight-lab/timelinejs 3.8.21 → 3.9.0

package/src/js/core/TimelineConfig.js

@@ -177,7 +177,6 @@ export class TimelineConfig {
             trace("Missing start date, skipping event")
             console.log(data)
             return null
-                // throw new TLError("missing_start_date_err", event_id);
         }
 
         this._processDates(data);

package/src/js/dom/DOMUtil.js

@@ -5,21 +5,21 @@
 ================================================== */
 
 function hasClass(el, name) {
-	return (el.className.length > 0) &&
-			new RegExp("(^|\\s)" + name + "(\\s|$)").test(el.className);
+    return (el.className.length > 0) &&
+        new RegExp("(^|\\s)" + name + "(\\s|$)").test(el.className);
 }
 
 export function addClass(el, name) {
-	if (!hasClass(el, name)) {
-		el.className += (el.className ? ' ' : '') + name;
-	}
+    if (!hasClass(el, name)) {
+        el.className += (el.className ? ' ' : '') + name;
+    }
 }
 
 export function removeClass(el, name) {
-	el.className = el.className.replace(/(\S+)\s*/g, function (w, match) {
-		if (match === name) {
-			return '';
-		}
-		return w;
-	}).replace(/^\s+/, '');
-}
+    el.className = el.className.replace(/(\S+)\s*/g, function(w, match) {
+        if (match === name) {
+            return '';
+        }
+        return w;
+    }).replace(/^\s+/, '');
+}

package/src/js/language/I18NMixins.js

@@ -1,5 +1,5 @@
 /*  I18NMixins
-    assumes that its class has an options object with a Language instance    
+    assumes that its class has an attribute `language` with a Language instance    
 ================================================== */
 import { trace } from "../core/Util"
 import { fallback } from "../language/Language"
@@ -24,8 +24,18 @@ class I18NMixins {
         return fallback;
     }
 
-    _(msg) {
-        return this.getLanguage()._(msg);
+    /**
+     * Look up a localized version of a standard message using the Language instance
+     * that was previously set with {@link setLanguage}.
+     * 
+     * @see {@link Language#_}
+     * @param {string} msg - a message key 
+     * @param {Object} [context] - a dictionary with string keys appropriate to message `k` 
+     *      and string values which will be interpolated into the message.
+     * @returns {string} - a localized string appropriate to the message key
+     */
+    _(msg, context) {
+        return this.getLanguage()._(msg, context);
     }
 }
 

package/src/js/language/Language.js

@@ -1,19 +1,21 @@
 import { mergeData, pad, trace } from "../core/Util"
 import { fetchJSON } from "../net/Net"
 import { BigYear } from "../date/TLDate"
+import TLError from "../core/TLError";
 
-/**
- * Instantiate a Language object to manage I18N. 
- * WARNING: In general, this should not be called directly, because it doesn't block while
- * the language file is loaded, which can lead to race conditions in some cases. In most
- * cases, language objects other than the fallback should be gotten by calling the 
- * async function loadLanguage defined elsewhere in this file.
- * 
- * @param {String} [language=en] - a language code or a URL to a 
- *     translation file
- * @param {string} [script_path] - if `language` is not a URL, this is used
- *     to construct a fully-qualified URL to load a translation file.
- */
+const MESSAGE_VARIABLE_PATTERN = new RegExp(/\$\{(.+?)\}/g)
+    /**
+     * Instantiate a Language object to manage I18N. 
+     * WARNING: In general, this should not be called directly, because it doesn't block while
+     * the language file is loaded, which can lead to race conditions in some cases. In most
+     * cases, language objects other than the fallback should be gotten by calling the 
+     * async function loadLanguage defined elsewhere in this file.
+     * 
+     * @param {String} [language=en] - a language code or a URL to a 
+     *     translation file
+     * @param {string} [script_path] - if `language` is not a URL, this is used
+     *     to construct a fully-qualified URL to load a translation file.
+     */
 class Language {
     constructor(language, script_path) {
         // borrowed from http://stackoverflow.com/a/14446414/102476
@@ -73,8 +75,28 @@ class Language {
         }
     }
 
-    _(k) {
-        return this.messages[k] || Language.fallback.messages[k] || k;
+    /**
+     * Look up a localized version of a standard message. While using `_` for the
+     * method name is not exactly idiomatic javascript, it was inspired by Python's
+     * {@link https://docs.python.org/3/library/gettext.html|gettext} module, with
+     * the intention of reducing clutter in places where, in a non-I18N'd app, you'd 
+     * simply have a quoted string.
+     * 
+     * @param {string} k - a message key 
+     * @param {Object} [context] - a dictionary with string keys appropriate to message `k` 
+     *      and string values which will be interpolated into the message.
+     * @returns {string} - a localized string appropriate to the message key
+     */
+    _(k, context) {
+        let msg = this.messages[k] || Language.fallback.messages[k] || k;
+        if (msg.match(MESSAGE_VARIABLE_PATTERN)) {
+            if (!context) throw new TLError("template_message_without_context")
+            for (let match of msg.matchAll(MESSAGE_VARIABLE_PATTERN)) {
+                if (!(match[1] in context)) throw new TLError("template_message_without_context")
+                msg = msg.replace(match[0], context[match[1]])
+            }
+        }
+        return msg
     }
 
     formatDate(date, format_name) {
@@ -267,19 +289,17 @@ var LANGUAGES = {
             loading: "Loading",
             wikipedia: "From Wikipedia, the free encyclopedia",
             error: "Error",
-            contract_timeline: "Contract Timeline",
             return_to_title: "Return to Title",
+            go_to_end: "Go to the last slide",
             loading_content: "Loading Content",
-            expand_timeline: "Expand Timeline",
             loading_timeline: "Loading Timeline... ",
             swipe_to_navigate: "Swipe to Navigate<br><span class='tl-button'>OK</span>",
+            zoom_in: "Zoom in",
+            zoom_out: "Zoom out",
             unknown_read_err: "An unexpected error occurred trying to read your spreadsheet data",
             invalid_url_err: "Unable to read Timeline data. Make sure your URL is for a Google Spreadsheet or a Timeline JSON file.",
-            invalid_url_share_required: "Because of unexpected changes to Google's data access API, the creator of this timeline must enable 'anyone with the url can read' access for this spreadsheet. See timeline.knightlab.com for more information.",
             network_err: "Unable to read your Google Spreadsheet. Make sure you have published it to the web.",
-            empty_feed_err: "No data entries found",
             missing_start_date_err: "Missing start_date",
-            invalid_data_format_err: "Header row has been modified.",
             invalid_start_time_without_date: "Invalid configuration: time cannot be used without date.",
             invalid_end_time_without_date: "Invalid configuration: end time cannot be used without end date.",
             date_compare_err: "Can't compare timeline date objects on different scales",
@@ -295,19 +315,26 @@ var LANGUAGES = {
             flickr_notfound_err: "Photo not found or private",
             flickr_invalidurl_err: "Invalid Flickr URL",
             imgur_invalidurl_err: "Invalid Imgur URL",
-            twitter_invalidurl_err: "Invalid Twitter URL",
             twitter_load_err: "Unable to load Tweet",
             twitterembed_invalidurl_err: "Invalid Twitter Embed url",
             wikipedia_load_err: "Unable to load Wikipedia entry",
-            youtube_invalidurl_err: "Invalid YouTube URL",
             spotify_invalid_url: "Invalid Spotify URL",
-            template_value_err: "No value provided for variable",
             invalid_rgb_err: "Invalid RGB argument",
             time_scale_scale_err: "Don't know how to get date from time for scale",
             axis_helper_no_options_err: "Axis helper must be configured with options",
             axis_helper_scale_err: "No AxisHelper available for scale",
             invalid_integer_option: "Invalid option value—must be a whole number.",
-            instagram_bad_request: "Invalid or private Instagram URL"
+            instagram_bad_request: "Invalid or private Instagram URL",
+            template_message_without_context: "Required variables not provided for template translation message",
+            aria_label_timeline: "Timeline",
+            aria_label_timeline_navigation: "Timeline navigation",
+            aria_label_timeline_content: "Timeline content",
+            // The following message keys are pseudo-template literal. 
+            // Do not surround with backticks (`) since evaluation is deferred 
+            // (and backticks wouldn't be allowed in JSON localization files)
+            // for each, document typical values for variable components
+            aria_label_zoomin: "Show less than ${start} to ${end}", // 'start' and 'end' should be numeric years 
+            aria_label_zoomout: "Show more than ${start} to ${end}" // 'start' and 'end' should be numeric years 
         },
         date: {
             month: [

package/src/js/language/__tests__/Language.test.js

@@ -0,0 +1,32 @@
+import { fallback } from "../Language"
+import { classMixin } from "../../core/Util"
+import { I18NMixins } from "../I18NMixins"
+class MixinTest {
+
+}
+
+classMixin(MixinTest, I18NMixins)
+
+test("Test variable interpolation", () => {
+    let msg = fallback._("aria_label_zoomin", { start: 1900, end: 2000 })
+    expect(msg).toBe('Show less than 1900 to 2000')
+})
+
+test("Test variable interpolation error checking with no context", () => {
+    expect(() => {
+        let msg = fallback._("aria_label_zoomin")
+    }).toThrow()
+})
+
+test("Test variable interpolation error checking with partial context", () => {
+    expect(() => {
+        let msg = fallback._("aria_label_zoomin", { start: 1900 })
+    }).toThrow()
+})
+
+test("Test interpolation through a mixin", () => {
+    let mixin = new MixinTest()
+    mixin.setLanguage(fallback)
+    let msg = mixin._("aria_label_zoomin", { start: 1900, end: 2000 })
+    expect(msg).toBe('Show less than 1900 to 2000')
+})

package/src/js/language/locale/af.json

@@ -1,75 +1,73 @@
 {
-    "lang": "af", 
+    "lang": "af",
     "date": {
         "month_abbr": [
-            "Jan.", 
-            "Feb.", 
-            "Maart", 
-            "April", 
-            "Mei", 
-            "Junei", 
-            "Julie", 
-            "Aug.", 
-            "Sept.", 
-            "Okt.", 
-            "Nov.", 
+            "Jan.",
+            "Feb.",
+            "Maart",
+            "April",
+            "Mei",
+            "Junei",
+            "Julie",
+            "Aug.",
+            "Sept.",
+            "Okt.",
+            "Nov.",
             "Des."
-        ], 
+        ],
         "day_abbr": [
-            "Son.", 
-            "Maan.", 
-            "Dins.", 
-            "Woen.", 
-            "Don.", 
-            "Vry.", 
+            "Son.",
+            "Maan.",
+            "Dins.",
+            "Woen.",
+            "Don.",
+            "Vry.",
             "Sat."
-        ], 
+        ],
         "day": [
-            "Sondag", 
-            "Maandag", 
-            "Dinsdag", 
-            "Woensdag", 
-            "Donderdag", 
-            "Vrydag", 
+            "Sondag",
+            "Maandag",
+            "Dinsdag",
+            "Woensdag",
+            "Donderdag",
+            "Vrydag",
             "Saterdag"
-        ], 
+        ],
         "month": [
-            "Januarie", 
-            "Februarie", 
-            "Maart", 
-            "April", 
-            "Mei", 
-            "Junie", 
-            "Julie", 
-            "Augustus", 
-            "September", 
-            "Oktober", 
-            "November", 
+            "Januarie",
+            "Februarie",
+            "Maart",
+            "April",
+            "Mei",
+            "Junie",
+            "Julie",
+            "Augustus",
+            "September",
+            "Oktober",
+            "November",
             "Desember"
         ]
-    }, 
+    },
     "api": {
         "wikipedia": "af"
-    }, 
+    },
     "messages": {
-        "loading": "Aan't laai", 
-        "contract_timeline": "Krimp die tydlyn", 
-        "return_to_title": "Begin voor", 
-        "wikipedia": "Van Wikipedia, die gratis ensiklopedie", 
-        "loading_content": "Die inhoud laai", 
-        "expand_timeline": "Rek die tydlyn", 
+        "loading": "Aan't laai",
+        "return_to_title": "Begin voor",
+        "wikipedia": "Van Wikipedia, die gratis ensiklopedie",
+        "loading_content": "Die inhoud laai",
         "loading_timeline": "Die tydlyn laai... "
-    }, 
+    },
     "dateformats": {
-        "full_long": "d mmm',' yyyy 'om' HH:MM", 
-        "full_short": "d mmm", 
-        "full": "d mmmm yyyy", 
-        "month_short": "mmm", 
-        "time_no_seconds_small_date": "HH:MM'<br/><small>'d mmmm yyyy'</small>'", 
-        "month": "mmmm yyyy", 
-        "time_no_seconds_short": "HH:MM", 
-        "time_short": "HH:MM:ss", 
-        "year": "yyyy", 
+        "full_long": "d mmm',' yyyy 'om' HH:MM",
+        "full_short": "d mmm",
+        "full": "d mmmm yyyy",
+        "month_short": "mmm",
+        "time_no_seconds_small_date": "HH:MM'<br/><small>'d mmmm yyyy'</small>'",
+        "month": "mmmm yyyy",
+        "time_no_seconds_short": "HH:MM",
+        "time_short": "HH:MM:ss",
+        "year": "yyyy",
         "full_long_small_date": "HH:MM'<br/><small>d mmm yyyy'</small>'"
     }
 }

package/src/js/language/locale/ar.json

@@ -1,76 +1,74 @@
 {
-    "lang": "ar", 
+    "lang": "ar",
     "direction": "rtl",
     "messages": {
-        "loading": "تحميل", 
-        "contract_timeline": "الاتفاقية", 
-        "return_to_title": "العودة", 
-        "wikipedia": "من ويكيبيديا, الموسوعة الحرة", 
-        "loading_content": "تحميل المحتوى", 
-        "expand_timeline": "تكبير العرض", 
+        "loading": "تحميل",
+        "return_to_title": "العودة",
+        "wikipedia": "من ويكيبيديا, الموسوعة الحرة",
+        "loading_content": "تحميل المحتوى",
         "loading_timeline": "جاري التحميل... "
-    }, 
+    },
     "api": {
         "wikipedia": "ar"
-    }, 
+    },
     "date": {
         "month_abbr": [
-            "كانون الثاني", 
-            "شباط", 
-            "آذار", 
-            "نيسان", 
-            "أيار", 
-            "حزيران", 
-            "تموز", 
-            "آب", 
-            "أيلول", 
-            "تشرين الأول", 
-            "تشرين الثاني", 
+            "كانون الثاني",
+            "شباط",
+            "آذار",
+            "نيسان",
+            "أيار",
+            "حزيران",
+            "تموز",
+            "آب",
+            "أيلول",
+            "تشرين الأول",
+            "تشرين الثاني",
             "كانون الأول"
-        ], 
+        ],
         "day_abbr": [
-            "الأحد", 
-            "الإثنين", 
-            "الثلاثاء", 
-            "الأربعاء", 
-            "الخميس", 
-            "الجمعة", 
+            "الأحد",
+            "الإثنين",
+            "الثلاثاء",
+            "الأربعاء",
+            "الخميس",
+            "الجمعة",
             "السبت"
-        ], 
+        ],
         "day": [
-            "الأحد", 
-            "الإثنين", 
-            "الثلاثاء", 
-            "الأربعاء", 
-            "الخميس", 
-            "الجمعة", 
+            "الأحد",
+            "الإثنين",
+            "الثلاثاء",
+            "الأربعاء",
+            "الخميس",
+            "الجمعة",
             "السبت"
-        ], 
+        ],
         "month": [
-            "كانون الثاني", 
-            "شباط", 
-            "آذار", 
-            "نيسان", 
-            "أيار", 
-            "حزيران", 
-            "تموز", 
-            "آب", 
-            "أيلول", 
-            "تشرين الأول", 
-            "تشرين الثاني", 
+            "كانون الثاني",
+            "شباط",
+            "آذار",
+            "نيسان",
+            "أيار",
+            "حزيران",
+            "تموز",
+            "آب",
+            "أيلول",
+            "تشرين الأول",
+            "تشرين الثاني",
             "كانون الأول"
         ]
-    }, 
+    },
     "dateformats": {
-        "full_long": "mmm d',' yyyy 'at' hh:MM TT", 
-        "full_short": "mmm d", 
-        "full": "mmmm d',' yyyy", 
-        "month_short": "mmm", 
-        "time_no_seconds_small_date": "h:MM TT'<br/><small>'mmmm d',' yyyy'</small>'", 
-        "month": "mmmm yyyy", 
-        "time_no_seconds_short": "h:MM TT", 
-        "time_short": "h:MM:ss TT", 
-        "year": "yyyy", 
+        "full_long": "mmm d',' yyyy 'at' hh:MM TT",
+        "full_short": "mmm d",
+        "full": "mmmm d',' yyyy",
+        "month_short": "mmm",
+        "time_no_seconds_small_date": "h:MM TT'<br/><small>'mmmm d',' yyyy'</small>'",
+        "month": "mmmm yyyy",
+        "time_no_seconds_short": "h:MM TT",
+        "time_short": "h:MM:ss TT",
+        "year": "yyyy",
         "full_long_small_date": "hh:MM TT'<br/><small>mmm d',' yyyy'</small>'"
     }
 }

package/src/js/language/locale/be.json

@@ -1,75 +1,73 @@
 {
-  "lang": "be", 
-  "date": {
-    "month_abbr": [
-      "стд", 
-      "лют", 
-      "скв", 
-      "крс", 
-      "май", 
-      "чрв", 
-      "лпн", 
-      "жнв", 
-      "врс", 
-      "кст", 
-      "лст", 
-      "снж"
-    ], 
-    "day_abbr": [
-      "Нд.", 
-      "Пн.", 
-      "Аўт.", 
-      "Ср.", 
-      "Чц.", 
-      "Пт.", 
-      "Сб."
-    ], 
-    "day": [
-      "нядзеля", 
-      "панядзелак", 
-      "аўторак", 
-      "серада", 
-      "чацвер", 
-      "пятніца", 
-      "субота"
-    ], 
-    "month": [
-      "студзень", 
-      "люты", 
-      "сакавік", 
-      "красавік", 
-      "май", 
-      "чэрвень", 
-      "ліпень", 
-      "жнівень", 
-      "верасень", 
-      "кастрычнік", 
-      "лістапад", 
-      "снежань"
-    ]
-  }, 
-  "api": {
-    "wikipedia": "be"
-  }, 
-  "messages": {
-    "loading": "Загрузка", 
-    "contract_timeline": "Аддаліць лінію часу", 
-    "return_to_title": "Вярнуцца ў пачатак", 
-    "wikipedia": "З Вікіпедыі, свабоднай энцыклапедыі", 
-    "loading_content": "Загрузка зместу", 
-    "expand_timeline": "Наблізіць лінію часу", 
-    "loading_timeline": "Загрузка лініі часу... "
-  }, 
-  "dateformats": {
-    "full_long": "d mmm yyyy 'at' h:MM TT", 
-    "full_short": "d mmm", 
-    "full": "d mmmm yyyy", 
-    "time_short": "h:MM:ss TT", 
-    "year": "yyyy", 
-    "time_no_seconds_short": "h:MM TT", 
-    "month_short": "mmm", 
-    "full_long_small_date": "h:MM TT'<br/><small>d mmm yyyy'</small>'", 
-    "time_no_seconds_small_date": "h:MM TT'<br/><small>'d mmmm yyyy'</small>'", 
-    "month": "mmmm yyyy"
-  }
+    "lang": "be",
+    "date": {
+        "month_abbr": [
+            "стд",
+            "лют",
+            "скв",
+            "крс",
+            "май",
+            "чрв",
+            "лпн",
+            "жнв",
+            "врс",
+            "кст",
+            "лст",
+            "снж"
+        ],
+        "day_abbr": [
+            "Нд.",
+            "Пн.",
+            "Аўт.",
+            "Ср.",
+            "Чц.",
+            "Пт.",
+            "Сб."
+        ],
+        "day": [
+            "нядзеля",
+            "панядзелак",
+            "аўторак",
+            "серада",
+            "чацвер",
+            "пятніца",
+            "субота"
+        ],
+        "month": [
+            "студзень",
+            "люты",
+            "сакавік",
+            "красавік",
+            "май",
+            "чэрвень",
+            "ліпень",
+            "жнівень",
+            "верасень",
+            "кастрычнік",
+            "лістапад",
+            "снежань"
+        ]
+    },
+    "api": {
+        "wikipedia": "be"
+    },
+    "messages": {
+        "loading": "Загрузка",
+        "return_to_title": "Вярнуцца ў пачатак",
+        "wikipedia": "З Вікіпедыі, свабоднай энцыклапедыі",
+        "loading_content": "Загрузка зместу",
+        "loading_timeline": "Загрузка лініі часу... "
+    },
+    "dateformats": {
+        "full_long": "d mmm yyyy 'at' h:MM TT",
+        "full_short": "d mmm",
+        "full": "d mmmm yyyy",
+        "time_short": "h:MM:ss TT",
+        "year": "yyyy",
+        "time_no_seconds_short": "h:MM TT",
+        "month_short": "mmm",
+        "full_long_small_date": "h:MM TT'<br/><small>d mmm yyyy'</small>'",
+        "time_no_seconds_small_date": "h:MM TT'<br/><small>'d mmmm yyyy'</small>'",
+        "month": "mmmm yyyy"
+    }
 }