locize 3.0.5 → 3.1.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+### 3.1.0
+
+- additional plugin interface that shows incontext only if passing `?incontext=true``
+
 ### 3.0.5
 
 - fix scrollTop

package/README.md

@@ -16,67 +16,92 @@ npm i locize
 
 **Hint:** This module runs only in browser.
 
-## Using
+### InContext variants
 
-### with a bundler
+For i18next based solutions (i18next, react-i18next, locizify, ...) there are two options to work with locize incontext:
 
-Just init like:
+#### a) Iframe on your page
 
-```js
-import 'locize';
-```
+The solution is best in class and uses [i18next-subliminal](https://github.com/i18next/i18next-subliminal) to add information about key and namespace as hidden text to the output of the `i18next.t` calls. Beside that it scans your website based on mutation observer to look out for those texts.
 
-### by including the script
+You can both click text elements on your website or keys in the locize iframe to edit content. Results will always be exact matches based on the namespace and key.
 
-```html
-<script src="https://unpkg.com/locize/locize.min.js" />
-```
+**Hint:** You can bind the ifame to a specific project by setting `ì18next.options.editor = { projectId, version }` or `ì18next.options.backend = { projectId, verstion }` (backend info might already exist when using i18next-locize-backend)
+
+**Caveats:** You might have elements that rerender too often in short time. This might will give you a warning output in console that that element change was ignored for passing to the iframe. Consider adding the `data-locize-editor-ignore: true` attribute to the element to ignore it completely.
+
+#### b) Opening it on https://locize.app
 
-### with i18next
+Details for setting this up can be found [here](https://docs.locize.com/different-views/incontext)
 
+The solution extracts the text on the clicked element and passes it for a fuzzy search to the parent frame. As the search is fuzzy there is no guarantee for exact results.
+
+**hint** To get exact matches you can add following attributes to the element or it's parent:
+
+`data-i18n` -> will pass exact key
+`data-i18n-ns` -> will pass namespace name
+
+# Using
+
+## with locizify
+
+This plugin is already included in [locizify](https://github.com/locize/locizify) >= v4.1.0
+
+## with i18next
+
+### this will show the locize incontext editor as a popup in your website
 ```js
 import { locizePlugin } from 'locize';
 
 i18next.use(locizePlugin);
 ```
 
+### this will show the locize incontext editor as a popup in your website only if the url contains the incontext=true query paramenter, i.e. http://localhost:8080?incontext=true
+```js
+import { locizeEditorPlugin } from 'locize';
+
+i18next.use(locizeEditorPlugin());
+```
+
 Using react-i18next you might want to bind the editorSaved event to trigger a rerender:
 
 ```js
 i18next.init({
   // ...
   react: {
-    bindI18n: 'languageChanged editorSaved',
-  },
-});
+    bindI18n: 'languageChanged editorSaved'
+  }
+})
 ```
 
-### with locizify
+## without i18next
 
-This plugin is already included in [locizify](https://github.com/locize/locizify) >= v4.1.0
+Not using i18next currently only the option to show your website inside the locize incontext solution (https://locize.app) is available.
 
 ### with other as module
 
 ```js
-import { addLocizeSavedHandler, startStandalone, setEditorLng } from 'locize';
+import { addLocizeSavedHandler, startStandalone, setEditorLng } from 'locize'
 
 addLocizeSavedHandler(res => {
   res.updated.forEach(item => {
-    const { lng, ns, key, data } = item;
+    const { lng, ns, key, data } = item
     // load the translations somewhere...
     // and maybe rerender your UI
-  });
-});
+  })
+})
 
 // start
-startStandalone();
+startStandalone()
 
 // switch lng in locize editor
-setEditorLng(lng);
+setEditorLng(lng)
 ```
 
 ### with other in vanilla javascript
 
+Only relevant when your website is shown inside the locize incontext solution on https://locize.app.
+
 ```html
 <script src="https://unpkg.com/locize/locize.min.js" />
 ```
@@ -84,23 +109,34 @@ setEditorLng(lng);
 ```js
 window.locizeSavedHandler = res => {
   res.updated.forEach(item => {
-    const { lng, ns, key, data } = item;
+    const { lng, ns, key, data } = item
     // load the translations somewhere...
     // and maybe rerender your UI
-  });
-};
+  })
+}
+
+window.locizeStartStandalone()
+```
+
+**Hint** you can fix the integration to a locize project by adding:
 
-window.locizeStartStandalone();
+```js
+<script
+  id="locize"
+  projectid="5e9ed7da-51ab-4b15-888b-27903f06be09"
+  version="latest"
+  src="https://unpkg.com/locize/locize.min.js"
+>
 ```
 
-## turn on/off programmatically
+### turn on/off click interception programmatically
 
 ```js
-import { turnOn, turnOff } from 'locize';
+import { turnOn, turnOff } from 'locize'
 
-let isOff;
+let isOff
 
 // or use window.locize.turnOn
-isOff = turnOff(); // -> true
-isOff = turnOn(); // -> false
+isOff = turnOff() // -> true
+isOff = turnOn() // -> false
 ```

package/dist/cjs/api/handleConfirmInitialized.js

@@ -5,6 +5,7 @@ var postMessage = require('./postMessage.js');
 function handler(payload) {
   postMessage.api.initialized = true;
   clearInterval(postMessage.api.initInterval);
+  delete postMessage.api.initInterval;
   postMessage.api.sendCurrentParsedContent();
   postMessage.api.sendCurrentTargetLanguage();
 }

package/dist/cjs/index.d.ts

@@ -1,15 +1,45 @@
 export * from 'i18next-subliminal'
 
+/**
+ * The i18next plugin for the locize incontext editor.
+ */
 export interface LocizePlugin {
   type: '3rdParty';
   init(i18next: any): () => void;
 }
 
+/**
+ * Returns an i18next plugin that will show the incontext editor.
+ */
 export const locizePlugin: LocizePlugin
 
+/**
+ * Returns an i18next plugin that will only show the incontext editor if the qsProp in your url is set to true.
+ * @param opt defaults to: { qsProp: 'incontext' }
+ */
+export function locizeEditorPlugin(opt?: { qsProp?: string }): LocizePlugin
+
+/**
+ * Turn on programmatically.
+ */
 export function turnOn(): void;
+
+/**
+ * Turn off programmatically.
+ */
 export function turnOff(): void;
+
+/**
+ * Set the language for the editor.
+ */
 export function setEditorLng(lng: string): void;
+
+/**
+ * To load the translations somewhere.
+ */
 export function addLocizeSavedHandler(fn: (data: any) => void): void;
 
+/**
+ * If used without i18next.
+ */
 export function startStandalone(): void;

package/dist/cjs/index.js

@@ -24,12 +24,14 @@ var index = {
   PostProcessor: i18nextSubliminal.PostProcessor,
   addLocizeSavedHandler: postMessage.addLocizeSavedHandler,
   locizePlugin: locizePlugin.locizePlugin,
+  locizeEditorPlugin: locizePlugin.locizeEditorPlugin,
   turnOn: postMessage.turnOn,
   turnOff: postMessage.turnOff,
   setEditorLng: postMessage.setEditorLng,
   startStandalone: startStandalone.startStandalone
 };
 
+exports.locizeEditorPlugin = locizePlugin.locizeEditorPlugin;
 exports.locizePlugin = locizePlugin.locizePlugin;
 exports.startStandalone = startStandalone.startStandalone;
 exports.addLocizeSavedHandler = postMessage.addLocizeSavedHandler;

package/dist/cjs/locizePlugin.js

@@ -6,6 +6,7 @@ var _defineProperty = require('@babel/runtime/helpers/defineProperty');
 var i18nextSubliminal = require('i18next-subliminal');
 var process = require('./process.js');
 var processLegacy = require('./processLegacy.js');
+var utils = require('./utils.js');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -17,89 +18,94 @@ var isInIframe = typeof window !== 'undefined';
 try {
   isInIframe = self !== top;
 } catch (e) {}
+function configurePostProcessor(i18next, options) {
+  i18next.use(i18nextSubliminal.PostProcessor);
+  if (typeof options.postProcess === 'string') {
+    options.postProcess = [options.postProcess, 'subliminal'];
+  } else if (Array.isArray(options.postProcess)) {
+    options.postProcess.push('subliminal');
+  } else {
+    options.postProcess = 'subliminal';
+  }
+  options.postProcessPassResolved = true;
+}
+function getImplementation(i18n) {
+  var impl = {
+    getResource: function getResource(lng, ns, key) {
+      return i18n.getResource(lng, ns, key);
+    },
+    setResource: function setResource(lng, ns, key, value) {
+      return i18n.addResource(lng, ns, key, value, {
+        silent: true
+      });
+    },
+    getResourceBundle: function getResourceBundle(lng, ns, cb) {
+      i18n.loadNamespaces(ns, function () {
+        cb(i18n.getResourceBundle(lng, ns));
+      });
+    },
+    getLng: function getLng() {
+      return i18n.languages[0];
+    },
+    getSourceLng: function getSourceLng() {
+      var fallback = i18n.options.fallbackLng;
+      if (typeof fallback === 'string') return fallback;
+      if (Array.isArray(fallback)) return fallback[fallback.length - 1];
+      if (fallback && fallback["default"]) {
+        if (typeof fallback["default"] === 'string') return fallback;
+        if (Array.isArray(fallback["default"])) return fallback["default"][fallback["default"].length - 1];
+      }
+      if (typeof fallback === 'function') {
+        var res = fallback(i18n.resolvedLanguage);
+        if (typeof res === 'string') return res;
+        if (Array.isArray(res)) return res[res.length - 1];
+      }
+      return 'dev';
+    },
+    getLocizeDetails: function getLocizeDetails() {
+      var backendName;
+      if (i18n.services.backendConnector.backend && i18n.services.backendConnector.backend.options && i18n.services.backendConnector.backend.options.loadPath && i18n.services.backendConnector.backend.options.loadPath.indexOf('.locize.') > 0) {
+        backendName = 'I18NextLocizeBackend';
+      } else {
+        backendName = i18n.services.backendConnector.backend ? i18n.services.backendConnector.backend.constructor.name : 'options.resources';
+      }
+      var opts = {
+        backendName: backendName,
+        sourceLng: impl.getSourceLng(),
+        i18nFormat: i18n.options.compatibilityJSON === 'v3' ? 'i18next_v3' : 'i18next_v4',
+        i18nFramework: 'i18next',
+        isLocizify: i18n.options.isLocizify,
+        defaultNS: i18n.options.defaultNS
+      };
+      if (!i18n.options.backend && !i18n.options.editor) return opts;
+      var pickFrom = i18n.options.backend || i18n.options.editor;
+      return _objectSpread(_objectSpread({}, opts), {}, {
+        projectId: pickFrom.projectId,
+        version: pickFrom.version
+      });
+    },
+    bindLanguageChange: function bindLanguageChange(cb) {
+      i18n.on('languageChanged', cb);
+    },
+    bindMissingKeyHandler: function bindMissingKeyHandler(cb) {
+      i18n.options.missingKeyHandler = function (lng, ns, k, val, isUpdate, opts) {
+        if (!isUpdate) cb(lng, ns, k, val);
+      };
+    },
+    triggerRerender: function triggerRerender() {
+      i18n.emit('editorSaved');
+    }
+  };
+  return impl;
+}
 var i18next;
 var locizePlugin = {
   type: '3rdParty',
   init: function init(i18n) {
     var options = i18n.options;
     i18next = i18n;
-    if (!isInIframe) {
-      i18next.use(i18nextSubliminal.PostProcessor);
-      if (typeof options.postProcess === 'string') {
-        options.postProcess = [options.postProcess, 'subliminal'];
-      } else if (Array.isArray(options.postProcess)) {
-        options.postProcess.push('subliminal');
-      } else {
-        options.postProcess = 'subliminal';
-      }
-      options.postProcessPassResolved = true;
-    }
-    var impl = {
-      getResource: function getResource(lng, ns, key) {
-        return i18n.getResource(lng, ns, key);
-      },
-      setResource: function setResource(lng, ns, key, value) {
-        return i18n.addResource(lng, ns, key, value, {
-          silent: true
-        });
-      },
-      getResourceBundle: function getResourceBundle(lng, ns, cb) {
-        i18n.loadNamespaces(ns, function () {
-          cb(i18n.getResourceBundle(lng, ns));
-        });
-      },
-      getLng: function getLng() {
-        return i18n.languages[0];
-      },
-      getSourceLng: function getSourceLng() {
-        var fallback = i18n.options.fallbackLng;
-        if (typeof fallback === 'string') return fallback;
-        if (Array.isArray(fallback)) return fallback[fallback.length - 1];
-        if (fallback && fallback["default"]) {
-          if (typeof fallback["default"] === 'string') return fallback;
-          if (Array.isArray(fallback["default"])) return fallback["default"][fallback["default"].length - 1];
-        }
-        if (typeof fallback === 'function') {
-          var res = fallback(i18n.resolvedLanguage);
-          if (typeof res === 'string') return res;
-          if (Array.isArray(res)) return res[res.length - 1];
-        }
-        return 'dev';
-      },
-      getLocizeDetails: function getLocizeDetails() {
-        var backendName;
-        if (i18n.services.backendConnector.backend && i18n.services.backendConnector.backend.options && i18n.services.backendConnector.backend.options.loadPath && i18n.services.backendConnector.backend.options.loadPath.indexOf('.locize.') > 0) {
-          backendName = 'I18NextLocizeBackend';
-        } else {
-          backendName = i18n.services.backendConnector.backend ? i18n.services.backendConnector.backend.constructor.name : 'options.resources';
-        }
-        var opts = {
-          backendName: backendName,
-          sourceLng: impl.getSourceLng(),
-          i18nFormat: i18n.options.compatibilityJSON === 'v3' ? 'i18next_v3' : 'i18next_v4',
-          i18nFramework: 'i18next',
-          isLocizify: i18n.options.isLocizify,
-          defaultNS: i18n.options.defaultNS
-        };
-        if (!i18n.options.backend && !i18n.options.editor) return opts;
-        var pickFrom = i18n.options.backend || i18n.options.editor;
-        return _objectSpread(_objectSpread({}, opts), {}, {
-          projectId: pickFrom.projectId,
-          version: pickFrom.version
-        });
-      },
-      bindLanguageChange: function bindLanguageChange(cb) {
-        i18n.on('languageChanged', cb);
-      },
-      bindMissingKeyHandler: function bindMissingKeyHandler(cb) {
-        i18n.options.missingKeyHandler = function (lng, ns, k, val, isUpdate, opts) {
-          if (!isUpdate) cb(lng, ns, k, val);
-        };
-      },
-      triggerRerender: function triggerRerender() {
-        i18n.emit('editorSaved');
-      }
-    };
+    if (!isInIframe) configurePostProcessor(i18next, options);
+    var impl = getImplementation(i18n);
     if (!isInIframe) {
       process.start(impl);
     } else {
@@ -107,9 +113,29 @@ var locizePlugin = {
     }
   }
 };
+var locizeEditorPlugin = function locizeEditorPlugin() {
+  var opt = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  opt.qsProp = opt.qsProp || 'incontext';
+  return {
+    type: '3rdParty',
+    init: function init(i18n) {
+      var options = i18n.options;
+      i18next = i18n;
+      var showInContext = utils.getQsParameterByName(opt.qsProp) === 'true';
+      if (!isInIframe && showInContext) configurePostProcessor(i18next, options);
+      var impl = getImplementation(i18n);
+      if (!isInIframe && showInContext) {
+        process.start(impl);
+      } else {
+        processLegacy.startLegacy(impl);
+      }
+    }
+  };
+};
 
 Object.defineProperty(exports, 'unwrap', {
   enumerable: true,
   get: function () { return i18nextSubliminal.unwrap; }
 });
+exports.locizeEditorPlugin = locizeEditorPlugin;
 exports.locizePlugin = locizePlugin;

package/dist/cjs/observer.js

@@ -5,7 +5,18 @@ Object.defineProperty(exports, '__esModule', { value: true });
 var utils = require('./utils.js');
 var vars = require('./vars.js');
 
+var mutationTriggeringElements = {};
 function ignoreMutation(ele) {
+  if (ele.uniqueID) {
+    var info = mutationTriggeringElements[ele.uniqueID];
+    if (info && info.triggered > 10 && info.lastTriggerDate + 500 < Date.now()) {
+      if (!info.warned && console) {
+        console.warn('locize ::: ignoring element change - an element is rerendering too often in short interval', '\n', 'consider adding the "data-locize-editor-ignore:" attribute to the element:', ele);
+        info.warned = true;
+      }
+      return true;
+    }
+  }
   var ret = ele.dataset && (ele.dataset.i18nextEditorElement === 'true' || ele.dataset.locizeEditorIgnore === 'true');
   if (!ret && ele.parentElement) return ignoreMutation(ele.parentElement);
   return ret;
@@ -34,6 +45,12 @@ function createObserver(ele, handle) {
       if (mutation.type === 'attributes' && !vars.validAttributes.includes(mutation.attributeName)) {
         return;
       }
+      Object.keys(mutationTriggeringElements).forEach(function (k) {
+        var info = mutationTriggeringElements[k];
+        if (info.lastTriggerDate + 60000 < Date.now()) {
+          delete mutationTriggeringElements[k];
+        }
+      });
       if (mutation.type === 'childList') {
         var notOurs = 0;
         if (!ignoreMutation(mutation.target)) {
@@ -49,8 +66,18 @@ function createObserver(ele, handle) {
         if (notOurs === 0) return;
       }
       triggerMutation = true;
+      if (mutation.target && mutation.target.uniqueID) {
+        var info = mutationTriggeringElements[mutation.target.uniqueID] || {
+          triggered: 0
+        };
+        info.triggered = info.triggered + 1;
+        info.lastTriggerDate = Date.now();
+        mutationTriggeringElements[mutation.target.uniqueID] = info;
+      }
       var includedAlready = targetEles.reduce(function (mem, element) {
-        if (mem || element.contains(mutation.target) || !mutation.target.parentElement) return true;
+        if (mem || element.contains(mutation.target) || !mutation.target.parentElement) {
+          return true;
+        }
         return false;
       }, false);
       if (!includedAlready) {

package/dist/cjs/utils.js

@@ -127,12 +127,23 @@ function getElementNamespace(el) {
   find(el);
   return found;
 }
+function getQsParameterByName(name, url) {
+  if (typeof window === 'undefined') return null;
+  if (!url) url = window.location.href.toLowerCase();
+  name = name.replace(/[\[\]]/g, '\\$&');
+  var regex = new RegExp('[?&]' + name + '(=([^&#]*)|&|#|$)');
+  var results = regex.exec(url);
+  if (!results) return null;
+  if (!results[2]) return '';
+  return decodeURIComponent(results[2].replace(/\+/g, ' '));
+}
 
 exports.debounce = debounce;
 exports.getClickedElement = getClickedElement;
 exports.getElementI18nKey = getElementI18nKey;
 exports.getElementNamespace = getElementNamespace;
 exports.getElementText = getElementText;
+exports.getQsParameterByName = getQsParameterByName;
 exports.getWindow = getWindow;
 exports.isWindow = isWindow;
 exports.offset = offset;

package/dist/esm/api/handleConfirmInitialized.js

@@ -3,6 +3,7 @@ import { api } from './postMessage.js';
 function handler(payload) {
   api.initialized = true;
   clearInterval(api.initInterval);
+  delete api.initInterval;
   api.sendCurrentParsedContent();
   api.sendCurrentTargetLanguage();
 }

package/dist/esm/index.d.ts

@@ -1,15 +1,45 @@
 export * from 'i18next-subliminal'
 
+/**
+ * The i18next plugin for the locize incontext editor.
+ */
 export interface LocizePlugin {
   type: '3rdParty';
   init(i18next: any): () => void;
 }
 
+/**
+ * Returns an i18next plugin that will show the incontext editor.
+ */
 export const locizePlugin: LocizePlugin
 
+/**
+ * Returns an i18next plugin that will only show the incontext editor if the qsProp in your url is set to true.
+ * @param opt defaults to: { qsProp: 'incontext' }
+ */
+export function locizeEditorPlugin(opt?: { qsProp?: string }): LocizePlugin
+
+/**
+ * Turn on programmatically.
+ */
 export function turnOn(): void;
+
+/**
+ * Turn off programmatically.
+ */
 export function turnOff(): void;
+
+/**
+ * Set the language for the editor.
+ */
 export function setEditorLng(lng: string): void;
+
+/**
+ * To load the translations somewhere.
+ */
 export function addLocizeSavedHandler(fn: (data: any) => void): void;
 
+/**
+ * If used without i18next.
+ */
 export function startStandalone(): void;

package/dist/esm/index.js

@@ -1,5 +1,5 @@
-import { locizePlugin } from './locizePlugin.js';
-export { locizePlugin } from './locizePlugin.js';
+import { locizePlugin, locizeEditorPlugin } from './locizePlugin.js';
+export { locizeEditorPlugin, locizePlugin } from './locizePlugin.js';
 import { startStandalone } from './startStandalone.js';
 export { startStandalone } from './startStandalone.js';
 import './api/handleEditKey.js';
@@ -24,6 +24,7 @@ var index = {
   PostProcessor: PostProcessor,
   addLocizeSavedHandler: addLocizeSavedHandler,
   locizePlugin: locizePlugin,
+  locizeEditorPlugin: locizeEditorPlugin,
   turnOn: turnOn,
   turnOff: turnOff,
   setEditorLng: setEditorLng,