InContext

Korrekte Übersetzungen brauchen oft mehr Kontext. Der beste Kontext ist dort, wo der Inhalt angezeigt wird: Ihre Website. Der InContext-Editor verbindet Ihre laufende Website oder App direkt mit Ihrem Locize-Projekt, sodass Übersetzer Strings in ihrem tatsächlichen Umfeld sehen und bearbeiten können.

Es gibt zwei Ansätze: den Popup-Editor auf Ihrer Website (empfohlen) und die InContext-Ansicht innerhalb von Locize (iframe). Beide benötigen die Integration des locize-Scripts auf Ihrer Seite.

Ein Beispiel-Video finden Sie hier.

Das Locize-Popup auf Ihrer Website (empfohlen)

Der empfohlene Ansatz öffnet den Locize-Editor als verschiebbares, in der Größe veränderbares Popup direkt auf Ihrer Website. Bei aktivem Popup können Sie auf jedes Textelement Ihrer Seite klicken. Der Editor hebt es hervor und zeigt das passende Schlüssel/Wert-Paar zur Bearbeitung.

Um das Popup zu aktivieren, hängen Sie ?incontext=true an Ihre URL an, z. B. http://localhost:8080?incontext=true.

Ein normales Locize-Nutzerkonto wird benötigt. Für SAML-Nutzer loggen Sie sich zuerst in einem separaten Fenster / Tab via SAML ein.

Die InContext-Ansicht in Locize (iframe)

Alternativ können Sie Ihre Website über einen iframe innerhalb der Locize-UI laden. So arbeiten Übersetzer komplett in Locize, sehen aber Ihre Website im Kontext.

Bei korrekter Integration können Sie auf jedes Textelement Ihrer im iframe angezeigten Website klicken. Locize nutzt diese Information, um das passende Schlüssel/Wert-Paar links zu finden.

Wenn Sie auf Ihrer Seite navigieren müssen, können Sie das Klick-Interception über den Button neben Ihrer Website-URL ein- / ausschalten.

Stellen Sie sicher, dass Sie die zu bearbeitende Sprache oben auswählen.

URLs für den iframe-Ansatz konfigurieren

Navigieren Sie zu den Einstellungen Ihres Projekts:

Wählen Sie „Set InContext editor urls" im Menü:

Setzen Sie die gewünschten URLs:

Zurück zur Projekt-Übersicht, navigieren Sie zum InContext-Editor:

Ergebnis:

Setup

Fügen Sie das locize-Script auf Ihrer Seite ein. Dieses Script ist sowohl für das Popup als auch für den iframe-Ansatz erforderlich. Es parst Ihre Seiteninhalte und kommuniziert über die Browser-postMessage-API mit Locize.

Mit i18next

import { locizePlugin } from 'locize'

i18next.use(locizePlugin)

Damit wird das Popup nur angezeigt, wenn ?incontext=true in der URL steht.

So zeigen Sie das Popup immer an:

import { locizeEditorPlugin } from 'locize'

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

Bei Verwendung von react-i18next binden Sie das editorSaved-Event, um nach jedem Speichern im Editor ein Rerender auszulösen:

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

Um die Integration einem bestimmten Locize-Projekt zuzuordnen, konfigurieren Sie entweder i18next-locize-backend oder ergänzen Sie:

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

Mit locizify

Das Locize-Script ist in locizify >= v4.1.0 bereits enthalten. Hängen Sie ?incontext=true an Ihre URL an, um das Popup zu aktivieren.

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

Um es einem bestimmten Projekt zuzuordnen:

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

Wie das Text-Matching funktioniert

Das Script muss Text auf Ihrer Seite mit Übersetzungs-Schlüsseln in Ihrem Locize-Projekt verknüpfen. Es gibt drei Wege:

1. Subliminal (Standard): Bei Verwendung von locizify oder dem locizePlugin enthalten Übersetzungen auf Ihrer Seite automatisch versteckte Metadaten (via i18next-subliminal), die Text dem Namespace und Schlüssel zuordnen. Dies ist die zuverlässigste Methode.

2. Data-Attribute: Annotieren Sie Ihr HTML mit data-i18n- und data-i18n-ns-Attributen, um Schlüssel- und Namespace-Informationen explizit bereitzustellen:

   Copy

   <div data-i18n-ns="myNamespace">
     <p data-i18n="myKey">Some translated text</p>
   </div>
   
   <!-- oder mit ns:key-Syntax -->
   <p data-i18n="ns:key">Some translated text</p>

3. Raw-Text-Lookup: Als Fallback sendet das Script Rohtext an den Editor, der eine exakte Suche durchführt und den Treffer zurückgibt.

Tipps

• Sie können Elemente vom Parsing ausschließen, indem Sie das Attribut data-locize-editor-ignore="true" hinzufügen.
• Das Popup merkt sich Position und Größe über Page-Reloads hinweg (gespeichert in localStorage).
• Das Script erkennt URL-Änderungen automatisch in Single-Page-Anwendungen und aktualisiert den Editor entsprechend.
• Sie können einen eigenen Query-Parameter-Namen statt incontext verwenden mit locizeEditorPlugin({ qsProp: 'myParam' }) und dann ?myParam=true.