Siti multi-lingua e multi-country

Siti multi-lingua

Il Discovery CMS prevede la possibilità di supportare campi multilingua, in modo da poter alimentare frontend multilingua. Innanzitutto, è necessario selezionare per la propria Property le lingue che si vogliono rendere disponibili, scegliendo per il campo Languages tutte le lingue che si vogliono alimentare. Fatto questo, è possibile creare, o modificare se esistente, il Component o il Content desiderato, selezionando la checkbox Multilanguage presente nella modale di definizione del tipo. Infine, è necessario pubblicare il tipo appena modificato.

Una volta che la Property ed i Components/Contents sono stati predisposti, è possibile andare ad impostare i valori dei campi per le varie lingue. Nel page editor, dove è possibile identificare facilmente i campi che supportano la funzionalità grazie alla lingua apposta accanto alla label dei campi, basta inserire il valore per la lingua mostrata in quel momento e salvare. Per cambiare lingua, semplicemente scegliere un'altra opzione dalla select presente nell'header della colonna.

multilanguage example

Per gli attributi multilingua, il formato dell'oggetto restituito dalla API cambia. Se consideriamo l'esempio mostrato sopra, per un campo non multilingua il payload sarà il seguente:

    {
        "components":[
            {
                "headline":"This is My Title",
                "_type":"Discovery\/Component",
                "_id":"f64e568b-9d9a-42c4-9ef8-b4ba107b8686"
            }
        ],
        "details":{
            "title":"HomePage",
            "slug":"home"
        },
        "_id":"84b676dc-31b0-4a4c-a3e1-d64b1a5bb0c2"
    }

Tuttavia, se il campo headline del componente Component viene configurato come multilingua, il payload diventerà il seguente:

    {
        "components":[
            {
                "_type":"Discovery\/Component",
                "_id":"f64e568b-9d9a-42c4-9ef8-b4ba107b8686",
                "translations": {
                    "en_US": {
                        "headline": "This is My Title"
                    },
                    "it_IT": {
                        "headline": "Questo è il mio titolo"
                    }
                }
            }
        ],
        "details":{
            "title":"HomePage",
            "slug":"home"
        },
        "_id":"84b676dc-31b0-4a4c-a3e1-d64b1a5bb0c2"
    }

È bene decidere qual è la lingua master del progetto, in modo da offrire un fallback sulla lingua master, generalmente l'inglese, in caso di mancanza di una traduzione.

Campo Title

Il campo title è speciale e non può essere reso multilingua. Qualora, ad esempio per un Content, sia necessario un titolo multilingua è possibile aggiungere un field headline (o externalTitle o equivalente) di tipo String multilingua ed è possibile procedere in uno dei seguenti modi:

Nel title verrà sempre inserito il titolo interno (quello che appare nel backend del CMS) e in headline quello esterno visibile sul frontend.
Nel title verrà sempre inserito il titolo nella lingua master (es. inglese) e in headline le eventuali traduzioni nelle altre lingue.

Nel caso 1, il frontend dovrebbe sempre andare in fallback su headline nel master language. Nel caso 2, il frontend dovrebbe sempre andare in fallback su headline nel master language e, se vuoto, sul title.

Si consiglia di impostare headline come Required for publishing nella popup di configurazione del field.

Siti multi-country

Mentre nella sezione precedente abbiamo spiegato come tradurre i testi in base alla lingua, in questa sezione spieghiamo come configurare un sito multi-country in modo da garantire un livello di personalizzazione per area geografica.

IMPORTANTE: in questo contesto, il termine country viene usato come termine più generico per indicare un'area geografica. Qualora il sito non sia specifico per country, ma abbia un'altro tipo di divisione (es. Europa, North America, Asia), è sufficiente sostituire country con l'area geografica di riferimento: i concetti sono esattamente gli stessi.

Ecco alcuni esempi:

si vuole personalizzare un'immagine o video in base alla country
si vuole aggiungere una sezione nella home page solo per una specifica country
si vuole differenziare una certa sezione in base alla country
si vuole creare pagine completamente diverse in base alla country

Questo manuale non entra nel merito di come il frontend determina la country di riferimento. Potrebbe essere una scelta dell'utente, potrebbe essere legata all'IP dell'utente, etc.

Nelle sezioni seguenti assumeremo che sia stata configurata una tassonomia Countries con l'elenco delle countries (o aree geografiche) su cui si vuole permettere una personalizzazione. Inoltre, assumiamo che ci sia una country di riferimento 'master' da utilizzare come fallback qualora manchi la personalizzazione per la specifica country dell'utente.

Personalizzare un'immagine o video in base alla country

Immaginiamo di voler personalizzare una certa immagine, ad esempio con persone di etnia diversa a seconda della country dove viene erogato, in un component CallToAction. Quanto spiegato per l'immagine si applica esattamente allo stesso modo per i video, audio o qualsiasi altro tipo di asset digitale.

Andiamo a definire un componente ImageOverride che contiene l'immagine da usare per override. Il component avrà i seguenti fields:

country di tipo Taxonomy[Countries], single value;
image di tipo Media[Image], single value;

Nel component CallToAction aggiungeremo i seguenti fields:

cover: di tipo Media[Image], che conterrà l'immagine di fallback;
cover_overrides: di tipo Reference[ImageOverride], multivalue.

Una volta che andremo a configurare la CallToAction nel CMS, in cover andiamo ad inserire l'immagine fallback, ovvero quella da usare qualora manchi l'immagine in override per la specifica country. Immaginiamo ora di voler fornire un'immagine diversa per gli Stati Uniti. Andremo ad aggiungere una reference in cover_overrides specificando:

country = "Stati Uniti"
image = (immagine che si vuole usare solo negli Stati Uniti)

Quando il frontend recupera una pagina contenente il componente configurato come sopra, andrà a cercare tra le cover_overrides una che coincide con la country corrente. Se la trova, utilizzerà la relativa immagine, in caso contrario utilizzerà quella di fallback (cover). Resta a carico di chi sviluppa il frontend implementare questa logica, possibilmente incpsulandola in un componente ad hoc ImageWithOverride, in modo da poterla inserire nelle pagine configurate dinamicamente.

Personalizzare una sezione di una pagina

Questo caso è molto simile a quello dell'esempio precedente, solo che si applica all'intero component anziché alla singola immagine. Immaginiamo che il component CallToAction possa essere disattivato per alcune country e personalizzato completamente (testi, immagini, etc.) per altre country. Definiremo un component CallToActionOverride con i seguenti campi:

country di tipo Taxonomy[Countries], single value;
disabled di tipo Boolean;
override di tipo Reference[CallToAction], single value;

Nella pagine aggiungo un component CallToAction con la configurazione di fallback, ovvero quella da utilizzare qualora non venga trovata la versione specifica di country. Immaginiamo di voler disattivare questa call to action per la Germania. Nella pagina andremo ad inserire un component CallToActionOverride con la seguente configurazione:

country = "Germania";
disabled = true;
override = (vuoto)

Immaginiamo, inoltre, di voler configurare una call to action completamente diversa per gli Stati Uniti. Nella pagina andremo ad inserire un component CallToActionOverride con la seguente configurazione:

country = "Stati Uniti";
disabled = false;
override = (componente CallToAction personalizzato per gli Stati Uniti);

Chi implementa la logica del frontend, quando deve visualizzare la call to action, andrà a cercare prima una versione specifica per la country corrente. Se la trova:

se è disabled, non visualizza nulla per la country corrente;
se non è disabled, visualizza la call to action in override;

Se non la trova, visualizza la CallToAction con la configurazione di fallback.

Resta a carico di chi sviluppa il frontend implementare questa logica, possibilmente incpsulandola in un componente ad hoc CallToActionWithOverride, in modo che possa essere anche inserito nelle pagine configurate dinamicamente.

Personalizzare le pagine per country

Immaginiamo di voler personalizzare completamente una pagina per la country Italia, mentre il resto del mondo vedrà una pagina standard. In tal caso definiremo due pagine:

Pagina di fallback, con slug = /home, da utilizzare per tutte le country se non esiste una pagina specifica;
Pagina specifica per la country, con slug = /home-it, da utilizzare per la sola country Italia;

Quando viene fatto il fetch della pagina occorre passare l'opzione fallback, come in questo esempio:

const page = useDiscoveryPage('home-it', {
    fallback: 'home'
})`

In questo modo l'API restituirà la pagina home-it se esiste, altrimenti home.

NOTA: l'opzione fallback verrà rilasciata nella prossima versione del Javascript Connector.

Siti multi-lingua e multi-country