# locize

> This package adds the incontext editor to your i18next setup.

Latest version **4.4.0** (published 2026-08-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install locize
pnpm add locize
yarn add locize
bun add locize
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.4.0 |
| Published | 2026-08-21 |
| First published | 2016-02-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 978.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | adrai, jamuhl |
| Keywords | i18next, i18next-plugin, locize, i18next-service, translation, localization as a service |

## Links

- npm: https://www.npmjs.com/package/locize
- Repository: https://github.com/locize/locize
- Issues: https://github.com/locize/locize/issues
- npm.io page: https://npm.io/package/locize

## Dependencies (3)

- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.29.2
- [@floating-ui/dom](https://npm.io/package/@floating-ui/dom.md) ^1.7.6
- [i18next-subliminal](https://npm.io/package/i18next-subliminal.md) ^1.0.1

## Alternatives

- [messageformat](https://npm.io/package/messageformat.md) — 329.7K weekly downloads
- [@mintlify/scraping](https://npm.io/package/@mintlify/scraping.md) — 294.8K weekly downloads
- [@mintlify/previewing](https://npm.io/package/@mintlify/previewing.md) — 209.5K weekly downloads
- [@mintlify/prebuild](https://npm.io/package/@mintlify/prebuild.md) — 209.5K weekly downloads
- [@mintlify/link-rot](https://npm.io/package/@mintlify/link-rot.md) — 206.3K weekly downloads

## Recent versions

- 4.4.0 (latest) — 2026-08-21
- 4.3.1 — 2026-08-20
- 4.3.0 — 2026-07-06
- 4.2.2 — 2026-07-06
- 4.2.1 — 2026-07-06
- 4.2.0 — 2026-07-06
- 4.1.0 — 2026-05-20
- 4.0.24 — 2026-05-19
- 4.0.23 — 2026-05-19
- 4.0.22 — 2026-04-23
- 4.0.21 — 2026-04-18
- 4.0.20 — 2026-04-16
- 4.0.19 — 2026-04-15
- 4.0.18 — 2026-04-15
- 4.0.17 — 2026-04-14
- … 60 more at https://npm.io/package/locize/versions

## README

[![npm version](https://img.shields.io/npm/v/locize.svg?style=flat-square)](https://www.npmjs.com/package/locize)

# locize

The locize script enables the [incontext editing](https://www.locize.com/docs/context#incontext) feature provided by [Locize](https://www.locize.com).

## Getting started

Source can be loaded via [npm](https://www.npmjs.com/package/locize), [downloaded](https://github.com/locize/locize/blob/master/locize.min.js) from this repo or loaded from the npm CDN [unpkg.com/locize](https://unpkg.com/locize/locize.min.js).

```html
<script src="https://unpkg.com/locize/locize.min.js"></script>
```

Using a module bundler simplest will be adding the script using npm (or yarn).

```bash
npm i locize
```

**Hint:** This module works only in the browser environment.

# How it works

The script will parse the page content and pass found segments to Locize using the browsers postMessage API. To work a text on your page has to be exactly matched to a segment in the editor by determing the matching namespace and key.

There are three ways to get the namespace and key:

## 1) Using subliminal

By default using [locizify](https://github.com/locize/locizify) or the `locizePlugin` the translations on your page will contain hidden text containing that information by using [subliminal](https://github.com/i18next/i18next-subliminal)

## 2) Using data-attributes

Extend your html to contain that information

`data-i18n` -> will pass exact key

`data-i18n-ns` -> will pass namespace name

eg.:

```html
<div data-i18n-ns="usedNamespace">
  <p data-i18n="usedKey">Some translated text</p>
</div>

// or using ns:key
<p data-i18n="ns:key">Some translated text</p>
```

Specifing content as [html](https://github.com/i18next/jquery-i18next?tab=readme-ov-file#set-innerhtml-attributes) or [title/placeholder attribute](https://github.com/i18next/jquery-i18next?tab=readme-ov-file#set-different-attribute) is also supported like used in `jquery-i18next`

## 3) Lookup in Locize

If not using recommended 1) or 2) the script will send the raw texts to the editor which will try an exact search for that text and send the found exact match back (only one result with 100% exact match).

# Setup

## with locizify

This plugin is already included in [locizify](https://github.com/locize/locizify) >= v4.1.0

**Hint:** show the incontext editor popup by adding incontext=true query paramenter, i.e. http://localhost:8080?incontext=true

## with i18next

For i18next we provide a plugin to be used.

```js
import { locizePlugin } from 'locize'

i18next.use(locizePlugin)
```

**Hint:** 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

Open as default:

```js
import { locizeEditorPlugin } from 'locize'

i18next.use(locizeEditorPlugin({ show: true }))
```

Using `react-i18next` you might want to bind the editorSaved event to trigger a rerender each time you save changes in the editor:

```js
i18next.init({
  // ...
  react: {
    bindI18n: 'languageChanged editorSaved'
  }
})
```

**Hint** you can match the integration to a Locize project by:

Having [i18next-locize-backend](https://github.com/locize/i18next-locize-backend) configured or adding

```js
i18next.init({
  // ...
  editor: {
    projectId: "5e9ed7da-51ab-4b15-888b-27903f06be09"
    version: "latest"
  }
})
```

## customizing the minimized button

The minimized editor button (bottom-right circle) can be moved to the left via option:

```js
i18next.use(locizeEditorPlugin({ ribbonPosition: 'bottom-left' }))
// or startStandalone({ ribbonPosition: 'bottom-left' })
// or <script id="locize" ribbonposition="bottom-left" ...>
```

For full control, target the stable CSS class:

```css
.locize-incontext-ribbon { bottom: 80px; right: 10px; }
```

## shadow DOM

If your translated content lives inside an **open shadow root**, the editor does
not see it by default: a shadow boundary stops DOM traversal *and* mutation
records, so neither the parser nor the `MutationObserver` on `document.body`
reaches into it.

Turn it on with the `shadowDOM` option:

```js
i18next.use(locizeEditorPlugin({ shadowDOM: true }))
// or startStandalone({ shadowDOM: true })
// or <script id="locize" shadowdom="true" ...>
```

With the option on, the editor walks into open shadow roots, observes each of
them individually (nested ones included), and hooks
`Element.prototype.attachShadow` so shadow roots created *after* the editor
started are picked up as well - the usual case, since the editor script usually
runs before the content is rendered into its shadow root. Closed shadow roots
(`{ mode: 'closed' }`) are only reachable if they are attached after the editor
started.

It is off by default because it widens what the editor touches, which is
unnecessary for pages that do not use shadow DOM.

## troubleshooting

If the editor popup stays blank or "could not connect" is shown:

- Make sure you are logged in at https://www.locize.app (open it in another tab, log in, reload your page).
- Your page's Content-Security-Policy must allow `frame-src https://incontext.locize.app`.
- An adblocker may block the editor iframe.
- Enable verbose diagnostics with `localStorage.setItem('locize-debug', 'true')` (or `?locizeDebug=true`) and check the browser console.

## not using i18next (messageformat, fluent, ...)

Not using i18next currently only the option to show your website inside the Locize incontext view (https://www.locize.com/docs/incontext).

### using import

```js
import { addLocizeSavedHandler, startStandalone, setEditorLng } from 'locize'

// optional
addLocizeSavedHandler(res => {
  res.updated.forEach(item => {
    const { lng, ns, key, data } = item
    // load the translations somewhere...
    // and maybe rerender your UI
  })
})

// start
startStandalone()

// switch lng in locize editor
setEditorLng(lng)
```

**Hint** you can match the integration to a Locize project by adding:

```js
startStandalone({
  projectId: "5e9ed7da-51ab-4b15-888b-27903f06be09",
  version: "latest"
})
```

**Hint:** show the incontext editor popup by adding incontext=true query paramenter, i.e. http://localhost:8080?incontext=true

or

```js
startStandalone({
  show: true
})
```

### vanilla javascript

Only relevant when your website is shown inside the Locize incontext solution via incontext view (https://www.locize.com/docs/incontext).

```html
<script src="https://unpkg.com/locize/locize.min.js" />
```

```js
window.locizeSavedHandler = res => {
  res.updated.forEach(item => {
    const { lng, ns, key, data } = item
    // load the translations somewhere...
    // and maybe rerender your UI
  })
}

window.locizeStartStandalone()
```

**Hint** you can match the integration to a Locize project by adding:

```js
<script
  id="locize"
  projectid="5e9ed7da-51ab-4b15-888b-27903f06be09"
  version="latest"
  src="https://unpkg.com/locize/locize.min.js"
>
```

---
_Source: https://npm.io/package/locize · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._