{"elements":[{"id":7009,"title":"Multilingua","body":"\n
\n
\n

Priorità di Rilevamento della Lingua<\/h2>\n
\"Gestione<\/div>\n

DressAPI offre un sistema di internazionalizzazione completo che gestisce automaticamente la traduzione sia delle etichette dell’interfaccia utente che dei contenuti strutturati nel database. Il framework rileva la lingua del visitatore, seleziona i testi appropriati e supporta un numero illimitato di lingue, senza duplicare tabelle o complicare la struttura dei dati.<\/p>\n \n \n \n
Priorità<\/th>Sorgente<\/th>Descrizione<\/th><\/tr>\n <\/thead>\n
1<\/td>DEFAULT_LANGUAGE<\/code><\/td>Se impostato su un codice specifico (es. 'IT'<\/code>), quella lingua viene sempre usata indipendentemente dal browser.<\/td><\/tr>\n
2<\/td>HTTP_ACCEPT_LANGUAGE<\/code><\/td>Se DEFAULT_LANGUAGE<\/code> è 'AUTO'<\/code>, i primi 2 caratteri dell'header del browser vengono estratti e convertiti in maiuscolo (es. it-IT,it;q=0.9<\/code> → IT<\/code>).<\/td><\/tr>\n
3<\/td>LANGUAGES[0]<\/code><\/td>Se nessun header è presente (es. chiamate API senza header del browser), viene usato il primo elemento dell'array LANGUAGES<\/code> (o 'EN'<\/code> se non definito).<\/td><\/tr>\n <\/tbody>\n <\/table>\n
define('DEFAULT_LANGUAGE', 'AUTO'); \/\/ Rileva dal browser\ndefine('LANGUAGES', ['IT', 'EN', 'DE', 'ES']); \/\/ IT è il fallback<\/div>\n

Se il browser invia un codice lingua non presente nell'array LANGUAGES<\/code> (es. JA<\/code> per giapponese quando sono supportati solo ['IT','EN']<\/code>), il sistema ricade sulla prima lingua configurata.<\/p>\n <\/div>\n<\/section>\n\n\n

\n
\n

Due Meccanismi di Traduzione<\/h2>\n

DressAPI offre due approcci complementari per l'internazionalizzazione:<\/p>\n\n

1. Etichette UI tramite _T()<\/code> e la tabella _translation<\/code><\/h3>\n

Per stringhe brevi dell'interfaccia utente (pulsanti, voci di menu, etichette). La funzione globale _T()<\/code> cerca la stringa nella mappa delle traduzioni della lingua corrente.<\/p>\n

\/\/ Nel codice PHP\n$etichetta = _T('Read more');\n\n\/\/ In un template PHP\n<h1><?= _T('Welcome') ?><\/h1>\n<button><?= _T('Search') ?><\/button><\/div>\n

Quando viene chiamata _T('Search')<\/code>:<\/p>\n

    \n
  1. Il testo viene trimmato dagli spazi.<\/li>\n
  2. CTranslator::GetTextTranslated()<\/code> cerca il testo nell'array delle traduzioni della lingua corrente.<\/li>\n
  3. Se trovato: restituisce la stringa tradotta.<\/li>\n
  4. Se il testo contiene tag @@<\/code>: chiama GetTextTranslatedContent()<\/code> per estrarre la variante della lingua corrente.<\/li>\n
  5. Se non trovato e LANGUAGE_LEARN<\/code> è true<\/code>: inserisce il testo nella tabella _translation<\/code>.<\/li>\n
  6. Se non trovato e LANGUAGE_LEARN<\/code> è false<\/code>: restituisce il testo originale con gli underscore sostituiti da spazi.<\/li>\n <\/ol>\n\n

    2. Contenuti tramite tag @@XX<\/code> inline e LANGUAGE_MULTI_CONTENTS<\/code><\/h3>\n

    Per contenuti lunghi (corpi di pagina, descrizioni). Quando LANGUAGE_MULTI_CONTENTS<\/code> è true<\/code>, DressAPI elabora automaticamente i tag @@XX<\/code> in tutti<\/strong> i valori dei campi del database durante le operazioni di lettura.<\/p>\n

    \/\/ Nel campo body del database:\n@@IT\n<h2>Chi siamo<\/h2>\n<p>Siamo un'azienda italiana.<\/p>\n@@EN\n<h2>About Us<\/h2>\n<p>We are an Italian company.<\/p><\/div>\n\n \n \n \n
    Meccanismo<\/th>Usato Per<\/th>Storage<\/th>Controllato Da<\/th><\/tr>\n <\/thead>\n
    Tabella _translation<\/code> + _T()<\/code><\/td>Etichette UI, testo pulsanti, voci menu<\/td>Tabella DB _translation<\/code><\/td>Sempre attivo quando CTranslator::Init()<\/code> viene chiamato<\/td><\/tr>\n
    Tag @@XX<\/code> inline nei contenuti<\/td>Contenuti lunghi, corpi pagina, descrizioni<\/td>Direttamente in qualsiasi campo DB<\/td>Costante LANGUAGE_MULTI_CONTENTS<\/code><\/td><\/tr>\n <\/tbody>\n <\/table>\n <\/div>\n<\/section>\n\n\n
    \n
    \n

    Limitazione Critica: Tag @@XX con HTML<\/h2>\n
    Attenzione:<\/strong> Questa limitazione può distruggere silenziosamente il tuo output HTML.<\/div>\n

    La regex @@XX<\/code> usa un match non-greedy che si ferma al successivo pattern @@[A-Z]{2}<\/code>. Questo significa che tutte le varianti linguistiche per un singolo blocco traducibile devono essere contigue<\/strong> — non ci deve essere HTML o altro contenuto tra di esse.<\/p>\n\n

    SBAGLIATO — Questo si romperà<\/h4>\n
    <h2>@@EN About Us @@IT Chi siamo<\/h2>\n<p>@@EN We are a company. @@IT Siamo un'azienda.<\/p><\/div>\n

    Estraendo per EN<\/code>, la regex cerca di rimuovere i blocchi @@IT<\/code>. Partendo da @@IT Chi siamo<\/code>, il .*?<\/code> non-greedy cerca il successivo @@[A-Z]{2}<\/code> e trova @@EN<\/code> nel tag <p><\/code>. Tutto tra i due viene rimosso, compresi i tag HTML <\/h2><p><\/code>.<\/p>\n\n

    CORRETTO — Mantieni le varianti insieme<\/h4>\n
    @@EN\n<h2>About Us<\/h2>\n<p>We are a company.<\/p>\n@@IT\n<h2>Chi siamo<\/h2>\n<p>Siamo un'azienda.<\/p><\/div>\n

    Regola:<\/strong> Non intercalare mai i tag @@XX<\/code> con la struttura HTML. Ogni blocco @@XX<\/code> deve contenere HTML auto-consistente e completo.<\/p>\n <\/div>\n<\/section>\n\n\n

    \n
    \n

    Traduzione nei Template<\/h2>\n

    Il motore di template DressAPI (CHtmlRender<\/code>) si integra automaticamente con il sistema di traduzione. Il testo tra {{ 'testo' }}<\/code> viene tradotto automaticamente tramite _T()<\/code>.<\/p>\n\n \n \n \n
    Espressione<\/th>Comportamento<\/th>Esempio<\/th><\/tr>\n <\/thead>\n
    {{ 'testo' }}<\/code><\/td>Stringa letterale — sempre tradotta tramite _T()<\/code><\/td>{{ 'Search' }}<\/code><\/td><\/tr>\n
    {{ variabile }}<\/code><\/td>Valore variabile — sempre tradotto tramite _T()<\/code><\/td>{{ user::name }}<\/code><\/td><\/tr>\n
    {{ x ?? 'default' }}<\/code><\/td>Valore predefinito — anch'esso tradotto<\/td>{{ page::title ?? 'Untitled' }}<\/code><\/td><\/tr>\n <\/tbody>\n <\/table>\n

    Il testo con spazi tra apici singoli attiva la traduzione _T()<\/code>. Questo permette di usare stringhe leggibili direttamente nei template.<\/p>\n <\/div>\n<\/section>\n\n\n

    \n
    \n

    Modificatori per Controllare la Traduzione<\/h2>\n \n \n \n
    Modificatore<\/th>Traduzione<\/th>Escaping HTML<\/th>Caso d'uso<\/th><\/tr>\n <\/thead>\n
    | raw<\/code><\/td>No<\/td>No<\/td>Contenuto HTML dal DB (già elaborato da LANGUAGE_MULTI_CONTENTS<\/code>)<\/td><\/tr>\n
    | nt<\/code><\/td>No<\/td>Sì<\/td>Codici prodotto, URL, identificatori tecnici<\/td><\/tr>\n
    | t<\/code><\/td>Sì (forzata)<\/td>Sì<\/td>Forza la traduzione su variabili speciali<\/td><\/tr>\n
    (nessuno)<\/em><\/td>Sì<\/td>Sì<\/td>Comportamento predefinito per etichette UI<\/td><\/tr>\n <\/tbody>\n <\/table>\n
    <!-- Contenuto HTML: usa raw per saltare traduzione E escaping -->\n<div class=\"content\">{{ page::body | raw }}<\/div>\n\n<!-- Codici prodotto: salta traduzione ma mantieni escaping -->\n<span class=\"sku\">{{ product::sku | nt }}<\/span>\n\n<!-- Forza traduzione su una variabile locale -->\n<span>{{ locals::label | t }}<\/span><\/div>\n <\/div>\n<\/section>\n\n\n
    \n
    \n

    Struttura della Tabella _translation<\/h2>\n \n \n \n
    Colonna<\/th>Tipo<\/th>Descrizione<\/th><\/tr>\n <\/thead>\n
    id<\/code><\/td>INT UNSIGNED AUTO_INCREMENT<\/td>Chiave primaria auto-incremento.<\/td><\/tr>\n
    origin<\/code><\/td>TEXT (utf8mb3_bin)<\/td>La chiave di testo originale. La stringa passata a _T()<\/code> o scritta in {{ 'testo' }}<\/code>. Ha vincolo UNIQUE.<\/td><\/tr>\n
    translation<\/code><\/td>TEXT (utf8mb3_bin)<\/td>Le versioni tradotte, codificate con i tag @@XX<\/code>. Se vuoto, viene usato il valore di origin<\/code>.<\/td><\/tr>\n <\/tbody>\n <\/table>\n

    Il campo translation<\/code> usa il formato tag @@XX<\/code> per memorizzare tutte le varianti linguistiche in un singolo campo:<\/p>\n

    -- Formato del campo translation:\n@@IT Testo italiano @@EN English text @@DE Deutscher Text\n\n-- Esempio di dati:\nINSERT INTO _translation VALUES\n(1, 'Go to', '@@IT Vai a @@EN Go to'),\n(2, 'Search', '@@IT Cerca @@EN Search'),\n(3, 'Read more', '@@IT Leggi tutto @@EN Read more');<\/div>\n

    Durante CTranslator::Init()<\/code>, il servizio carica l'intera tabella, divide il campo translation<\/code> per @@<\/code> e costruisce una mappa associativa in memoria per lingua.<\/p>\n <\/div>\n<\/section>\n\n\n

    \n
    \n

    Elaborazione LANGUAGE_MULTI_CONTENTS<\/h2>\n

    Quando LANGUAGE_MULTI_CONTENTS<\/code> è true<\/code>, il metodo CTranslator::GetTextTranslatedContent()<\/code> viene applicato ricorsivamente a tutti i valori stringa dei dati letti dal database.<\/p>\n

    \/\/ In CBaseModel::GetViewData():\nif ($on_read && defined('LANGUAGE_MULTI_CONTENTS') && LANGUAGE_MULTI_CONTENTS)\n array_walk_recursive($data,\n fn(&$text) => is_string($text) &&\n CTranslator::GetTextTranslatedContent($text, 'EN'));<\/div>\n

    La funzione GetTextTranslatedContent()<\/code> usa una regex in due passaggi:<\/p>\n

      \n
    1. Rimuove le lingue non corrispondenti:<\/strong> la regex \/@@(?!EN)w+.*?(?=@@[A-Z]{2}|z)\/s<\/code> rimuove ogni blocco @@XX<\/code> il cui codice non corrisponde alla lingua corrente.<\/li>\n
    2. Rimuove il marcatore della lingua corrente:<\/strong> la seconda regex \/@@EN\/<\/code> rimuove il prefisso @@EN<\/code> stesso, lasciando solo il testo tradotto.<\/li>\n <\/ol>\n

      Questo elabora tutti i campi di tutte le tabelle<\/strong>, non solo tabelle specifiche. L'elaborazione avviene solo sulle operazioni di lettura (GET<\/code>).<\/p>\n <\/div>\n<\/section>\n\n\n

      \n
      \n

      Best Practices<\/h2>\n
        \n
      1. Mantieni i blocchi @@XX<\/code> auto-consistenti.<\/strong> Non intercalare mai i tag @@XX<\/code> con la struttura HTML. Raggruppa l'intero contenuto di ogni lingua come un singolo blocco.<\/li>\n
      2. Usa LANGUAGE_LEARN<\/code> solo in sviluppo.<\/strong> Non abilitarlo mai in produzione: ogni stringa non tradotta genera un INSERT nel database e un ricaricamento completo della cache.<\/li>\n
      3. Usa {{ 'testo' }}<\/code> nei template<\/strong> per tutte le etichette visibili all'utente.<\/li>\n
      4. Usa | raw<\/code> per i contenuti HTML<\/strong> dal database, specialmente se già elaborati da LANGUAGE_MULTI_CONTENTS<\/code>.<\/li>\n
      5. Usa | nt<\/code> per i valori tecnici<\/strong> come codici prodotto, URL o identificatori.<\/li>\n
      6. Metti la lingua più comune per prima<\/strong> nell'array LANGUAGES<\/code>: serve come fallback.<\/li>\n
      7. Usa DEFAULT_LANGUAGE = 'AUTO'<\/code><\/strong> per i siti pubblici, un codice fisso per i pannelli di amministrazione.<\/li>\n
      8. Svuota la cache dopo aver modificato le traduzioni.<\/strong> Le traduzioni sono cachate per lingua.<\/li>\n <\/ol>\n <\/div>\n<\/section>\n\n\n
        \n
        \n

        Traduzioni Specifiche per Sezione (@#)<\/h2>\n

        Quando un sito DressAPI gestisce più sezioni tematiche (es. giochi diversi, categorie di prodotti), è possibile avere traduzioni diverse per la stessa etichetta a seconda della sezione attiva. Questo meccanismo usa i tag @#nome_sezione<\/code> all'interno della tabella _translation<\/code>.<\/p>\n\n

        Come funziona<\/h3>\n

        Le rotte nel database possono impostare una sezione tramite il prefisso s\/<\/code> nel percorso di destinazione:<\/p>\n

        -- Nella tabella _route:\n-- origin_path destination_path\n-- lotto\/patterns\/([a-z0-9_-]+) s\/lotto\/pages\/3012\/read-patterns\n-- superenalotto\/patterns\/([a-z0-9_-]+) s\/superenalotto\/pages\/4012\/read-patterns<\/div>\n

        Quando l'URL corrisponde a una rotta con prefisso s\/nome_sezione<\/code>, il framework (CRequest<\/code>) estrae il nome della sezione e lo comunica al traduttore tramite CTranslator::SetSection()<\/code>. Da quel momento, tutte le traduzioni cercano prima una versione specifica per quella sezione.<\/p>\n\n

        Formato nella tabella _translation<\/h3>\n

        Nel campo translation<\/code>, dopo il testo generico di ogni lingua, si aggiungono i tag @#nome_sezione<\/code> seguiti dal testo specifico:<\/p>\n

        -- origin: \"About odds and prizes\"\n-- translation:\n@@IT Informazioni su quote e premi @#lotto Informazioni su quote e premi del Lotto @#superenalotto Informazioni su quote e premi del SuperEnalotto\n@@EN About odds and prizes @#lotto About Lotto odds and prizes @#superenalotto About SuperEnalotto odds and prizes<\/div>\n\n

        Ordine di priorità<\/h3>\n

        Quando CTranslator::GetTextTranslated()<\/code> cerca la traduzione per un testo, applica questo ordine:<\/p>\n \n \n \n
        Priorità<\/th>Sorgente<\/th>Esempio<\/th><\/tr>\n <\/thead>\n
        1<\/td>Traduzione specifica per sezione e lingua<\/td>@#lotto Informazioni su quote e premi del Lotto<\/code><\/td><\/tr>\n
        2<\/td>Traduzione generica per lingua<\/td>@@IT Informazioni su quote e premi<\/code><\/td><\/tr>\n
        3<\/td>Fallback: il testo originale con underscore sostituiti da spazi<\/td>About odds and prizes<\/code><\/td><\/tr>\n <\/tbody>\n <\/table>\n\n

        Esempio reale<\/h3>\n

        In un sito che gestisce diversi giochi (Lotto, SuperEnalotto, MillionDay, ecc.), la stessa etichetta \"About odds and prizes\" nel template viene tradotta in modo diverso a seconda della sezione attiva:<\/p>\n \n \n \n
        Sezione attiva<\/th>Testo visualizzato (IT)<\/th><\/tr>\n <\/thead>\n
        lotto<\/code><\/td>Informazioni su quote e premi del Lotto<\/td><\/tr>\n
        superenalotto<\/code><\/td>Informazioni su quote e premi del SuperEnalotto<\/td><\/tr>\n
        (nessuna)<\/em><\/td>Informazioni su quote e premi<\/td><\/tr>\n <\/tbody>\n <\/table>\n\n

        Configurazione<\/h3>\n

        Per usare le sezioni, assicurarsi che:<\/p>\n

          \n
        1. Le rotte nella tabella _route<\/code> usino il prefisso s\/nome_sezione\/<\/code> nel campo destination_path<\/code>.<\/li>\n
        2. Le traduzioni nella tabella _translation<\/code> contengano i tag @#nome_sezione<\/code> con i testi specifici.<\/li>\n
        3. La sezione viene impostata automaticamente dal framework durante il parsing della rotta — non serve codice aggiuntivo.<\/li>\n <\/ol>\n <\/div>\n<\/section>\n

          ← Torna ai Tutorial<\/a><\/p>","description":"Traduzioni automatiche e contenuti multilingua","meta_keywords":"","visible":"yes","status":"public","creation_date":"0000-00-00","id__user":1,"priority":0,"groupname":"TUTORIAL"}],"module":"pages","permissions":{"can_read":true},"main_item_title":"title","related_tables":[{"name":"Newsonpage","module":"newsonpage","FK":"id_cmspage","permissions":[]}],"page_info":{"table":"","key":"id","url":"\/pages","url_list":"\/pages","filters":{"id":["=","7009"]},"pagination":{"total_items":23,"page":1,"total_pages":2,"step":1,"items_per_page":20,"url_prev":"\/pages","url_next":"\/pages\/p\/2","url_tmpl":"\/pages\/p\/[[p]]","url_tmpl_with_order":"\/pages\/p\/[[p]]\/ob\/[[ob]]"},"order":{"field":"id","type":"DESC","url_tmpl":"\/pages\/p\/[[p]]"},"module":{"title":"Pages","description":"List of pages","name":"pages"},"current":{"title":"Pages","description":"List of pages","name":"pages","url":"\/tutorials\/multilingua"}},"components":{"alert":{"alert1":[{"type":"warning","message":"OK COMPONENT!"},{"type":"danger","message":"ERROR COMPONENT!"}]}},"messages":[]}