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

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"
>

4.0.14

fix typescript types for startStandalone

4.0.13

update i18next-subliminal

4.0.12

locizePlugin: start i18next-subliminal only if popup or in iframe

4.0.11

fix highlighting

4.0.5

fix some typos

4.0.0

support also non-i18next environments

3.3.0

support i18next-subliminal in clickHandler used in locize iframe

3.2.5

fix startStandalone: added handler for committed message

3.2.3

fix startStandalone: added missing functions for implementation

3.2.2

fix startLegacy (should only run if in iframe)

3.2.1

prefer to get resolvedLanguage for getLng if available

3.2.0

using the locizePlugin export should only show the incontext editor if passing ?incontext=true

3.1.1

prevent to append popup multiple times

3.1.0

additional plugin interface that shows incontext only if passing ?incontext=true

3.0.5

fix scrollTop

3.0.4

style: adapt hight

3.0.3

ignore element flag

3.0.2

optimize detection for i18next backend

3.0.1

fix for use cases where body may be invisible first

3.0.0

This module can now be used for both type of incontext editors - as iframe (old) or with iframe (new).
showLocizeLink has been removed, since conflicting with new incontext editor

2.4.6

add basic types

2.4.5

only handle messages containing data.message

2.4.4

check for window

2.4.3

send href changed on load

2.4.2

optimize handling of setEditorLng if called to early

2.4.0

forward href changes
forward lng change (if using i18nextPlugin)
fallback ns detected to defaultNS if locizify

2.3.1

code cosmetics and updated deps

2.3.0

add turnOn, turnOff function for programmatical on/off

2.2.5

check if window exists

2.2.4

if cat not ready, postpone missing keys

2.2.3

check automatically if is in iframe and attach missingKeyHandler conditionally

2.2.2

select partial text for divs

2.2.1

remove window.locizeBoundPostMessageAPI check

2.2.0

add locizePlugin to be used in i18next
add onAddedKey function

2.1.0

add addLocizeSavedHandler

2.0.0

initial version for using with the locize UI in context editor (postMessage API)

pre 2.0.0

locize module was used as a combination of i18next + the locize-backend

包详细信息

自述文件