Traduzioni

Questo endpoint consente di inviare le traduzioni relative ad alcuni campi del prodotto verso ChannelEngine.
Le traduzioni non sovrascrivono i campi nativi, ma vengono salvate negli Extra Data del prodotto e delle varianti, seguendo una nomenclatura standardizzata.

Il riferimento utilizzato per applicare le traduzioni è sempre lo SKU, che deve essere sempre presente e univoco sia per il prodotto principale (grandparent) sia per eventuali varianti (child).

Applicazione delle traduzioni

Ogni richiesta di traduzione viene applicata automaticamente sia al grandparent che ai child collegati. Nel caso di prodotti semplici, ovvero senza varianti, è possibile fornire indifferentemente lo SKU del child o quello del grandparent: il sistema provvederà comunque ad applicare la traduzione correttamente al prodotto.

In entrambi i casi, la traduzione verrà applicata correttamente al prodotto.

Gestione delle lingue

Le lingue sono validate utilizzando i codici ISO a due lettere. Codici come it, en, fr o de sono quindi supportati, indipendentemente dal maiuscolo o minuscolo utilizzato.

Questo meccanismo garantisce che le traduzioni vengano associate esclusivamente a lingue standard riconosciute, evitando l’inserimento di codici personalizzati o non conformi.

Salvataggio delle traduzioni negli Extra Data

Tutte le traduzioni vengono inserite negli Extra Data seguendo una nomenclatura standardizzata:

<nome_campo>|CE:<iso>

Dove <nome_campo> rappresenta il nome del campo tradotto e <iso> il codice lingua a due lettere.
Ad esempio, la traduzione italiana del titolo verrà salvata con chiave Title|CE:it, mentre un metafield denominato testMetafield tradotto in francese verrà salvato come testMetafield|CE:fr.

Questo approccio consente a ChannelEngine di gestire più lingue senza interferire con i campi originali del prodotto.

Campi traducibili del prodotto

Per il prodotto principale (grandparent) è possibile fornire le traduzioni dei principali campi informativi. Tra i campi traducibili troviamo:

• title: il titolo del prodotto;
• description: la descrizione principale;
• handle: identificativo leggibile del prodotto nei link;
• notFoundHandle: handle alternativo utilizzato in caso di URL non trovata;
• type: la tipologia del prodotto;
• optionKeys: le chiavi delle opzioni del prodotto (ad esempio color, size).

Sono inoltre supportate le traduzioni dei campi SEO, come metaTitle e metaDescription, che vengono salvate negli Extra Data senza sostituire i valori nativi.

I metafields del prodotto sono completamente traducibili. Per ciascun metafield è possibile fornire una o più traduzioni, che vengono salvate negli Extra Data utilizzando la chiave nel formato:

<nome_metafield>|CE:<iso>

Lo stesso meccanismo viene applicato ai file, che seguono esattamente la stessa logica dei metafield per quanto riguarda la chiave di salvataggio.

Campi traducibili delle varianti

Ogni variante (child) del prodotto può avere traduzioni proprie, applicabili a specifici campi. Questo permette di gestire correttamente le differenze linguistiche anche a livello di singola variante.

Le parti traducibili di una variante comprendono:

• optionValues: le opzioni della variante, come color o size. Ogni opzione viene salvata negli Extra Data con la chiave corrispondente seguita dal suffisso di lingua, ad esempio color|CE:it.
• campi base: alcuni campi informativi della variante, come title e description, possono essere tradotti in modo analogo a quelli del prodotto principale.
• metafields: i metafields specifici della variante sono completamente traducibili, seguendo la stessa logica dei metafields del prodotto principale.
• files: anche i file associati alla variante possono avere versioni tradotte, salvate negli Extra Data con chiave corrispondente al nome del file seguito dal suffisso di lingua.

Alcuni campi (es. barcode, sku, ecc.) non sono traducibili per natura.

Esempio di payload

Nell’esempio seguente la lingua principale è l’italiano e vengono fornite traduzioni in inglese e francese. Le traduzioni vengono applicate sia al prodotto che alla sua variante.

{
  "data": [
    {
      "sku": "TEST",
      "title": {
        "en": "Product title TEST",
        "fr": "Titre du produit TEST"
      },
      "description": {
        "en": "Product description TEST",
        "fr": "Description du produit TEST"
      },
      "handle": {
        "en": "product-handle-test",
        "fr": "produit-handle-test"
      },
      "type": {
        "en": "Product type TEST",
        "fr": "Type de produit TEST"
      },
      "metaTitle": {
        "en": "SEO Product Meta Title",
        "fr": "Méta-titre du produit SEO"
      },
      "metaDescription": {
        "en": "A detailed meta description for SEO.",
        "fr": "Une méta description détaillée pour le référencement."
      },
      "files": {
        "manual": {
          "en": "https://www.orimi.com/pdf-test.pdf",
          "fr": "https://www.orimi.com/pdf-test.pdf"
        }
      },
      "metafields": {
        "addition_features": {
          "en": "Translated metafield",
          "fr": "Métachamp traduit"
        }
      },
      "optionKeys": {
        "color": {
          "en": "color",
          "fr": "couleur"
        }
      },
      "variants": [
        {
          "sku": "TEST-1",
          "optionValues": {
            "color": {
              "en": "Pink",
              "fr": "Rose"
            }
          },
          "files": {
            "variantManual": {
              "en": "https://www.orimi.com/pdf-test.pdf",
              "fr": "https://www.orimi.com/pdf-test.pdf"
            }
          },
          "metafields": {
            "variant_addition_features": {
              "en": "Translated metafield",
              "fr": "Métachamp traduit"
            }
          }
        }
      ]
    }
  ]
}

Configurazioni flusso traduzioni

Oltre alle configurazioni base del flusso dati aggiungere le seguenti impostazioni sui Settings Override:

Campo	Valore	Note
Base Url	https://adapt.flowlyze.com	url degli adapter
Resource Path	/api/adp/channel-engine/egress/sync-translations-to-ce	path dell'adapter per le traduzioni
Headers :: x-api-key	**********	api key di verifica interazione endpoint
Headers :: x-ce-url	https://CEURL.channelengine.net/api	url del Channel Engine con cui connettersi
Headers :: x-ce-token	CODICEALFANUMERICO	token per l'integrazione