Vai al contenuto
Locize
AccediRegistrati

InContext

Traduzioni corrette richiedono spesso più contesto. Il contesto migliore è dove il contenuto viene mostrato: il vostro sito. L'editor InContext collega il vostro sito o app in esecuzione direttamente al vostro progetto Locize, così i traduttori possono vedere e modificare le stringhe nel loro ambiente reale.

Ci sono due approcci: l'editor popup sul vostro sito (consigliato) e la vista InContext dentro Locize (iframe). Entrambi richiedono l'integrazione dello script locize sulla vostra pagina.

Un video di esempio è disponibile qui.

Il popup di Locize sul vostro sito (consigliato)

L'approccio consigliato apre l'editor di Locize come popup spostabile e ridimensionabile direttamente sul vostro sito. Con il popup attivo, potete cliccare su qualsiasi elemento di testo della pagina. L'editor lo evidenzia e mostra la coppia chiave/valore corrispondente per la modifica.

Per attivare il popup, aggiungete ?incontext=true all'URL, es. http://localhost:8080?incontext=true.

È necessario un normale account utente Locize. Per gli utenti SAML, effettuate prima il login in una finestra / scheda separata via SAML.

La vista InContext dentro Locize (iframe)

In alternativa potete caricare il vostro sito tramite un iframe dentro la UI di Locize. Così i traduttori lavorano completamente in Locize, ma vedono il vostro sito nel contesto.

Con l'integrazione corretta, potete cliccare su qualsiasi elemento di testo del vostro sito mostrato nell'iframe. Locize usa questa informazione per trovare la coppia chiave/valore corrispondente sulla sinistra.

Se dovete navigare sulla vostra pagina, potete attivare / disattivare l'intercettazione dei click tramite il pulsante accanto all'URL del sito.

Assicuratevi di selezionare in alto la lingua da modificare.

Configurare gli URL per l'approccio iframe

Andate alle impostazioni del vostro progetto:

Selezionate «Set InContext editor urls» nel menu:

Impostate gli URL desiderati:

Tornati alla panoramica del progetto, andate all'editor InContext:

Risultato:

Setup

Inserite lo script locize nella vostra pagina. Questo script è necessario sia per il popup sia per l'approccio iframe. Analizza i contenuti della pagina e comunica con Locize tramite l'API browser postMessage.

Con i18next

import { locizePlugin } from 'locize'

i18next.use(locizePlugin)

Così il popup viene mostrato solo se ?incontext=true è presente nell'URL.

Per mostrare sempre il popup:

import { locizeEditorPlugin } from 'locize'

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

Se usate react-i18next, agganciate l'evento editorSaved per attivare un rerender dopo ogni salvataggio nell'editor:

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

Per associare l'integrazione a uno specifico progetto Locize, configurate i18next-locize-backend oppure aggiungete:

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

Con locizify

Lo script Locize è già incluso in locizify >= v4.1.0. Aggiungete ?incontext=true all'URL per attivare il popup.

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

Per associarlo a uno specifico progetto:

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

Come funziona il matching del testo

Lo script deve collegare il testo della pagina alle chiavi di traduzione del vostro progetto Locize. Ci sono tre modi:

  1. Subliminal (default): usando locizify o il locizePlugin, le traduzioni della pagina contengono automaticamente metadati nascosti (via i18next-subliminal) che associano il testo al namespace e alla chiave. È il metodo più affidabile.

  2. Attributi data: annotate il vostro HTML con gli attributi data-i18n e data-i18n-ns per fornire esplicitamente le informazioni di chiave e namespace:

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

<!-- oppure con la sintassi ns:key -->
<p data-i18n="ns:key">Some translated text</p>

  3. Lookup del testo grezzo: come fallback, lo script invia il testo grezzo all'editor, che esegue una ricerca esatta e restituisce il match.

Suggerimenti

  • Potete escludere elementi dal parsing aggiungendo l'attributo data-locize-editor-ignore="true".
  • Il popup ricorda posizione e dimensione tra i ricaricamenti di pagina (salvato in localStorage).
  • Lo script rileva automaticamente i cambi di URL nelle single-page application e aggiorna l'editor di conseguenza.
  • Potete usare un nome di query parameter personalizzato invece di incontext con locizeEditorPlugin({ qsProp: 'myParam' }) e poi ?myParam=true.