Aller au contenu
Locize
ConnexionS'inscrire

InContext

Des traductions correctes ont souvent besoin de plus de contexte. Le meilleur contexte se trouve là où le contenu est affiché : votre site. L'éditeur InContext relie votre site ou application en cours d'exécution directement à votre projet Locize, afin que les traducteurs puissent voir et modifier les chaînes dans leur environnement réel.

Il existe deux approches : l'éditeur popup sur votre site (recommandé) et la vue InContext dans Locize (iframe). Les deux nécessitent l'intégration du script locize dans votre page.

Une vidéo d'exemple est disponible ici.

Le popup Locize sur votre site (recommandé)

L'approche recommandée ouvre l'éditeur Locize sous forme de popup déplaçable et redimensionnable directement sur votre site. Avec le popup actif, vous pouvez cliquer sur n'importe quel élément textuel de votre page. L'éditeur le met en évidence et affiche la paire clé/valeur correspondante pour la modification.

Pour activer le popup, ajoutez ?incontext=true à votre URL, par ex. http://localhost:8080?incontext=true.

Un compte utilisateur Locize standard est nécessaire. Pour les utilisateurs SAML, connectez-vous d'abord dans une fenêtre / un onglet séparé via SAML.

La vue InContext dans Locize (iframe)

Vous pouvez également charger votre site via un iframe dans l'interface Locize. Les traducteurs travaillent ainsi entièrement dans Locize tout en voyant votre site en contexte.

Avec une intégration correcte, vous pouvez cliquer sur n'importe quel élément textuel de votre site affiché dans l'iframe. Locize utilise cette information pour trouver la paire clé/valeur correspondante à gauche.

Si vous devez naviguer sur votre page, vous pouvez activer / désactiver l'interception des clics via le bouton à côté de l'URL du site.

Assurez-vous de sélectionner en haut la langue à modifier.

Configurer les URL pour l'approche iframe

Accédez aux paramètres de votre projet :

Sélectionnez «Set InContext editor urls» dans le menu :

Définissez les URL souhaitées :

De retour à la vue d'ensemble du projet, accédez à l'éditeur InContext :

Résultat :

Configuration

Insérez le script locize dans votre page. Ce script est nécessaire à la fois pour le popup et pour l'approche iframe. Il analyse le contenu de votre page et communique avec Locize via l'API postMessage du navigateur.

Avec i18next

import { locizePlugin } from 'locize'

i18next.use(locizePlugin)

Ainsi, le popup ne s'affiche que si ?incontext=true est présent dans l'URL.

Pour afficher toujours le popup :

import { locizeEditorPlugin } from 'locize'

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

Si vous utilisez react-i18next, branchez l'événement editorSaved pour déclencher un rerender après chaque sauvegarde dans l'éditeur :

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

Pour associer l'intégration à un projet Locize spécifique, configurez i18next-locize-backend ou ajoutez :

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

Avec locizify

Le script Locize est déjà inclus dans locizify >= v4.1.0. Ajoutez ?incontext=true à votre URL pour activer le popup.

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

Pour l'associer à un projet spécifique :

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

JavaScript Vanilla

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

Comment fonctionne la correspondance du texte

Le script doit relier le texte de votre page aux clés de traduction de votre projet Locize. Il existe trois méthodes :

  1. Subliminal (par défaut) : en utilisant locizify ou le locizePlugin, les traductions de votre page contiennent automatiquement des métadonnées cachées (via i18next-subliminal) qui associent le texte au namespace et à la clé. C'est la méthode la plus fiable.

  2. Attributs data : annotez votre HTML avec les attributs data-i18n et data-i18n-ns pour fournir explicitement les informations de clé et de namespace :

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

<!-- ou avec la syntaxe ns:key -->
<p data-i18n="ns:key">Some translated text</p>

  3. Lookup du texte brut : en repli, le script envoie le texte brut à l'éditeur, qui effectue une recherche exacte et renvoie la correspondance.

Astuces

  • Vous pouvez exclure des éléments de l'analyse en ajoutant l'attribut data-locize-editor-ignore="true".
  • Le popup mémorise sa position et sa taille entre les rechargements de page (enregistré dans localStorage).
  • Le script détecte automatiquement les changements d'URL dans les single-page applications et met à jour l'éditeur en conséquence.
  • Vous pouvez utiliser un nom de paramètre de requête personnalisé au lieu de incontext avec locizeEditorPlugin({ qsProp: 'myParam' }) puis ?myParam=true.