locize

The locize script enables the incontext editing feature provided by locize.

Getting started

Source can be loaded via npm, downloaded from this repo or loaded from the npm CDN unpkg.com/locize.

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

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

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 or the locizePlugin the translations on your page will contain hidden text containing that information by using 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.:

<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 or title/placeholder 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 >= 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.

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:

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:

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

Hint you can match the integration to a locize project by:

Having i18next-locize-backend configured or adding

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

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

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:

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

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).

<script src="https://unpkg.com/locize/locize.min.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:

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