InContext

Correct translations often need more context. The best context is where the content is shown: your website. The InContext editor connects your running website or app directly to your Locize project, so translators can see and edit strings in their actual environment.

There are two approaches: the popup editor on your website (recommended) and the InContext view inside Locize (iframe). Both require the locize script to be integrated into your page.

An example video can be found here.

The recommended approach opens the Locize editor as a draggable, resizable popup directly on your website. When active, you can click any text element on your page. The editor will highlight it and show the matching key/value for editing.

To activate the popup, add ?incontext=true to your URL, e.g. http://localhost:8080?incontext=true.

A standard Locize user account is required. For SAML users, log in via SAML in a separate window/tab first.

The InContext view in Locize (iframe)

Alternatively, you can load your website via an iframe inside the Locize UI. This lets translators work entirely within Locize while seeing your website in context.

When integrated correctly, you can click any text element on your website shown in the iframe. Locize will use that information to find the matching key/value on the left.

If you need to navigate on your page, you can turn click interception on/off using the button next to your website URL.

Make sure to select the language you want to work on at the top.

Configuring URLs for the iframe approach

Navigate to your project's settings:

Select "Set InContext editor urls" in the menu:

Set the desired url(s):

Back to your project overview, navigate to the InContext Editor:

Result:

Setup

Add the locize script to your page. This script is required for both the popup and the iframe approach. It parses your page content and communicates with Locize using the browser's postMessage API.

With i18next

import { locizePlugin } from 'locize'

i18next.use(locizePlugin)

This will show the popup only when ?incontext=true is in the URL.

To always show the popup:

import { locizeEditorPlugin } from 'locize'

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

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

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

To match the integration to a specific Locize project, either configure i18next-locize-backend, or add:

i18next.init({
  // ...
  editor: {
    projectId: 'your-project-id',
    version: 'latest'
  }
})

With locizify

The locize script is already included in locizify >= v4.1.0. Add ?incontext=true to your URL to activate the popup.

Without i18next (messageformat, fluent, ...)

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

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

// start the editor
startStandalone()

// switch language in the editor
setEditorLng(lng)

To match it to a specific project:

startStandalone({
  projectId: 'your-project-id',
  version: 'latest'
})

Vanilla JavaScript

<script id="locize"
  projectid="your-project-id"
  version="latest"
  src="https://unpkg.com/locize/locize.min.js">
</script>

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

window.locizeStartStandalone()

How text matching works

The script needs to match text on your page to translation keys in your Locize project. There are three ways this can happen:

Subliminal (default) — When using locizify or the locizePlugin, translations on your page automatically contain hidden metadata (via i18next-subliminal) that maps text to its namespace and key. This is the most reliable method.

Data attributes — Annotate your HTML with data-i18n and data-i18n-ns attributes to explicitly provide key and namespace information:

<div data-i18n-ns="myNamespace">
  <p data-i18n="myKey">Some translated text</p>
</div>

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

Raw text lookup — As a fallback, the script sends raw text to the editor, which performs an exact search and returns the match if found.

Tips

You can exclude elements from being parsed by the editor by adding the data-locize-editor-ignore="true" attribute.
The popup remembers its position and size across page reloads (stored in localStorage).
The script automatically detects URL changes in single-page applications and updates the editor accordingly.
You can use a custom query parameter name instead of incontext by using locizeEditorPlugin({ qsProp: 'myParam' }) and then ?myParam=true.