{"id":28466609,"url":"https://github.com/locize/locize-editor","last_synced_at":"2025-06-30T23:32:45.409Z","repository":{"id":46057189,"uuid":"83302974","full_name":"locize/locize-editor","owner":"locize","description":"editor integration plugin","archived":false,"fork":false,"pushed_at":"2025-02-21T17:34:46.000Z","size":352,"stargazers_count":20,"open_issues_count":3,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-30T08:15:13.492Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/locize.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-27T11:28:58.000Z","updated_at":"2025-02-21T17:34:49.000Z","dependencies_parsed_at":"2023-02-02T02:15:53.504Z","dependency_job_id":null,"html_url":"https://github.com/locize/locize-editor","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/locize/locize-editor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locize%2Flocize-editor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locize%2Flocize-editor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locize%2Flocize-editor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locize%2Flocize-editor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/locize","download_url":"https://codeload.github.com/locize/locize-editor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locize%2Flocize-editor/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262868177,"owners_count":23377207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-07T07:04:51.979Z","updated_at":"2025-06-30T23:32:45.387Z","avatar_url":"https://github.com/locize.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚠️DEPRECATED⚠️\n\n**This library is used for the old locize UI. DO NOT USE IT ANYMORE!**\n\n[Check out this migration guide.](https://docs.locize.com/more/incontext-editor/migrating-from-the-old-incontext-editor)\n\n---\n\n[![npm version](https://img.shields.io/npm/v/locize-editor.svg?style=flat-square)](https://www.npmjs.com/package/locize-editor)\n\n# locize-editor\n\nThe locize-editor enables you to directly connect content from your website / application with your content on your localization project on locize.\n\nEnabling the editor by querystring `?locize=true` you can click any text content on your website to open it on the right side editor window:\n\n![](https://cdn.prod.website-files.com/67a323e323a50df7f24f0a94/67adcc7057a22ffd9bae4e54_678e0d67f23748ba31eff98c_678e0b37ca80ab51a1d72d54_c-thumb-3.webp 'Screen of InContext Editor')\n\nThe linking could be turned on/off using the button on the lower right or by pressing `ctrl-x`.\n\n## Getting started\n\nSource can be loaded via [npm](https://www.npmjs.com/package/locize-editor), bower, [downloaded](https://github.com/locize/locize/blob/master/locize.min.js) from this repo or loaded from the npm CDN [unpkg.com/locize-editor](https://unpkg.com/locize-editor/locize-editor.min.js).\n\nIf not using a bundler the script will be added to `window.locizeEditor`.\n\n**Hint:** This module runs only in browser.\n\n## Using\n\n### standalone\n\nJust init like:\n\n```js\nlocizeEditor.init({\n  lng: 'fr',\n  defaultNS: 'namespaceToUse',\n  projectId: '[yourProjectID]',\n  referenceLng: 'en'\n});\n```\n\nOpen edit mode by appending `?locize=true` to the querystring.\n\nFor additional options see below **Initialize with optional options**\n\n### with locizify\n\nThe editor is built into our [locizify script](https://github.com/locize/locizify). There is no additional step needed.\n\nOpen edit mode by appending `?locize=true` to the querystring.\n\nFor texts using plural or interpolation feature you might need to additionally add `\u0026lng=cimode\u0026useLng=[yourLocal]` to find a key.\n\n### with i18next and i18next-locize-backend\n\n```\nimport locizeEditor from 'locize-editor';\nimport i18next from 'locize';\nimport Backend from 'i18next-locize-backend';\n\ni18next\n  .use(Backend)\n  .use(locizeEditor);\n```\n\n### Initialize with optional options\n\nYou can configure some aspects like layout by adding init options.\n\n```js\n// standalone\nlocizeEditor.init({\n  // enable on init without the need of adding querystring locize=true\n  enabled: false,\n  autoOpen: true, // if set to false you will need to open it via API\n\n  openDashboard: false, // open dashboard instead of the specified project\n\n  // enable by adding querystring locize=true; can be set to another value or turned off by setting to false\n  enableByQS: 'locize',\n\n  // turn on/off by pressing\n  toggleKeyModifier: 'ctrlKey', // metaKey | altKey | shiftKey\n  toggleKeyCode: 24, // x when pressing ctrl (e.which: document.addEventListener('keypress', (e) =\u003e console.warn(e.which, e));\n\n  // use lng in editor taken from query string, eg. if running with lng=cimode (i18next, locize)\n  lngOverrideQS: 'useLng',\n\n  // use lng in editor, eg. if running with lng=cimode (i18next, locize)\n  lngOverride: null,\n\n  // expect keys to have namespace prepend (CIMODE): text clicked is in form ns:key\n  hasNamespacePrefixed: false,\n\n  // default will open a iframe; setting to window will open a new window/tab instead\n  mode: 'iframe', // 'window',\n\n  // styles to adapt layout in iframe mode to your website layout\n  iframeContainerStyle: 'z-index: 1000; position: fixed; top: 0; right: 0; bottom: 0; width: 600px; box-shadow: -3px 0 5px 0 rgba(0,0,0,0.5);',\n  iframeStyle: 'height: 100%; width: 600px; border: none;',\n  bodyStyle: 'margin-right: 605px;',\n\n  // handle when locize saved the edited translations, eg. reload website\n  // You may need to click first one of the text elements in your app first. (https://github.com/locize/locize-editor/issues/17)\n  onEditorSaved: function(lng, ns) { location.reload(); },\n  \n  // custom appendTarget and container classes for the InContext Editor\n  locizeEditorWindow: {\n    appendTarget: document.querySelector('.example-div'), // Element into which the editor window should be appended. Element should be set position: relative as the editor window itself will be set position: absolute;. defaults to false, appending to the body\n    containerClasses: 'custom-class second-custom-class' // defaults to false, resulting in no custom classes set\n  },\n  // custom appendTarget, container classes and title for the \"locize editor\" overlay with the button to toggle click selection of strings.\n  locizeEditorToggle: {\n    appendTarget: document.querySelector('.example-div'), // Element into which the toggle should be appended. Element should be set position: relative as the toggle itself will be set position: absolute;. defaults to false, appending to the body\n    containerClasses: 'custom-class second-custom-class', // defaults to false, resulting in no custom classes set\n    title: `Custom title` // defaults to false, resulting in the default title being displayed\n  }\n})\n\n// i18next, ...\nlocizify|locize|i18next.init({\n  editor: {\n    // all options above\n  }\n});\n```\n\n### update your application when you saved changes in locize editor\n\nuse the onEditorSaved handler\n\n```js\n// reload the full page\nlocizeEditor.init({\n  onEditorSaved: function(lng, ns) {\n    location.reload();\n  }\n});\n\n// reload translations in i18next and trigger a rerender\nlocizeEditor.init({\n  onEditorSaved: function(lng, ns) {\n    i18next.reloadResources(lng, ns, () =\u003e {\n      // trigger rerender on your app if needed\n      // note: reloadResources can take an optional callback in i18next@\u003e=11.9.0\n    });\n  }\n});\n```\n\n### update the locize editor if your site sent new save missings\n\nthe app will reload those namespaces\n\n```js\nlocizeEditor.handleSavedMissing(lng, ns);\n\n// eg. on your i18next-locize-backend bind the onSaved on init\ni18next\n  .use(locizeEditor)\n  .use(locizeBackend)\n  .init({\n    //...\n    backend: {\n      //...\n      onSaved: locizeEditor.handleSavedMissing\n    }\n  });\n```\n\nsee the sample for react.js [i18next/react-i18next sample](https://github.com/i18next/react-i18next/blob/master/example/locize-example/src/i18n.js#L45)\n\n### find the namespace\n\nAs content is structured into multiple translation files we somehow need to detect/find the namespace (file) used for translating the clicked content.\n\nIf locize is not able to detect the right namespace it will fallback for a fuzzy global search - which in most cases should also provide the correct result. But you might like to get more control.\n\n##### by adding attribute containing namespace\n\nThe namespace will be detected from current clicked element or any of its parents.\n\nFollowing attributes are valid to look it up:\n\n```html\n\u003c!-- standalone --\u003e\n\u003cdiv i18n-ns=\"myNamespace\"\u003econtent\u003c/div\u003e\n\u003cdiv data-i18n-ns=\"myNamespace\"\u003econtent\u003c/div\u003e\n\n\u003c!-- i18next: preferred --\u003e\n\u003cdiv i18next-ns=\"myNamespace\"\u003econtent\u003c/div\u003e\n\u003cdiv data-i18next-ns=\"myNamespace\"\u003econtent\u003c/div\u003e\n\n\u003c!-- alternative: json stringified i18next options--\u003e\n\u003cdiv i18next-options=\"{\\\"ns\\\":\\\"myNamespace\\\"}\"\u003econtent\u003c/div\u003e\n\u003cdiv data-i18next-options=\"{\\\"ns\\\":\\\"myNamespace\\\"}\"\u003econtent\u003c/div\u003e\n```\n\n##### by using cimode language\n\nIf there is no possibility to find the used namespace per attribute on parent element you will need to toggle the lng to cimode. Additionally you will need to configure locize to append namespace in cimode by:\n\n```\ni18next.init({\n  appendNamespaceToCIMode: true\n});\n```\n\nopen your website with querystring `?locize=true\u0026lng=cimode\u0026useLng=[yourLocal]`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocize%2Flocize-editor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocize%2Flocize-editor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocize%2Flocize-editor/lists"}