--- order: 6 section: features title: Token in linea description: >- Inserisci link, URL degli asset e stringhe non traducibili nel testo MDX grazie a token che si aggiornano in ogni lingua senza dover essere ritradotti. noindex: false canonicalPath: /it/docs/inline-tokens --- Spesso nel testo MDX serve un valore che Scribe conosce già: un link a un'altra voce, l'URL pubblico di un asset, un testo che non va mai tradotto o una breve stringa ripetuta più volte nello stesso documento. Scriverli a mano rende il testo fragile (rinominare uno slug o spostare un asset rompe i link senza dare avvisi) e sporca la traduzione (un URL non andrebbe mai "tradotto"). I token in linea risolvono il problema. Scrivi il token una sola volta nel testo in inglese; Scribe lo risolve per ogni lingua in fase di lettura, mentre per la traduzione è un semplice segnaposto opaco e immutabile. ## Sintassi Un token è `${{:}}`. Esistono quattro tipi: | Token | Risolve in | | --- | --- | | `${{static:"testo"}}` | Il valore letterale esatto `testo` (una stringa JSON, per cui le virgolette e i caratteri di escape sono ben definiti). Non viene mai tradotto e resta identico in ogni lingua. | | `${{relation:::href}}` | Un **percorso di collegamento** alla voce di destinazione (vedi [modalità delle relazioni](#modalit-delle-relazioni)). Il suffisso della modalità è obbligatorio. | | `${{relation:::slug}}` | La stringa dello **slug inglese** di destinazione, un identificatore stabile per i componenti MDX che caricano i contenuti di Scribe autonomamente. | | `${{asset:/web/percorso.webp}}` | L'URL pubblico dell'asset (`assets.publicPath` unito al percorso). Vedi [asset](/docs/assets). | | `${{var:chiave}}` | `frontmatter.vars[chiave]` dello stesso documento. | Gli slug non possono contenere `:`, quindi il parsing delle relazioni non è ambiguo. Scrivere solo `${{relation::}}` senza il suffisso della modalità genera un errore di validazione. ### Modalità delle relazioni Ogni token di relazione deve finire con `:href` o `:slug`. | Modalità | Scopo | | --- | --- | | `:href` | Link navigabile. La forma finale dipende da chi lo legge (vedi sotto). | | `:slug` | Identità: restituisce sempre lo slug inglese della destinazione. | `:href` si risolve in modo diverso in base a chi sta leggendo il documento: | Lettore | Risoluzione di `:href` | | --- | --- | | `createScribe()` (runtime dell'app) | Percorso senza lingua ma con lo slug tradotto, ad es. `/per/abiti`; passalo direttamente al `Link` del tuo router. | | Esportazione statica `.md` | Percorso pubblico completo con estensione del file e lingua, ad es. `/it/per/abiti.md`, rispecchiando la struttura dei file esportati. | ### Meccanismo di escape `${{` (un backslash tra il simbolo del dollaro e le parentesi graffe) renderizza letteralmente `${{` e non viene mai trattato come un token. Usalo per mostrare la sintassi dei token nella documentazione; è esattamente quello che fa questa pagina. ## La chiave frontmatter `vars` `vars` è un `Record` opzionale che qualsiasi voce può dichiarare **senza** doverlo aggiungere allo schema del tipo: ```mdx --- title: Saldi di primavera vars: cta: Scopri i saldi --- Pronti? ${{var:cta}}. Solo per poco tempo. ``` `vars` è una chiave riservata: viene estratta prima della validazione dello schema (così uno schema rigido non la rifiuta mai), non è mai considerata un campo da tradurre ed esiste solo nel documento in inglese. I documenti tradotti leggono `${{var:chiave}}` dalla mappa `vars` del loro documento genitore in inglese, per avere sempre un'unica fonte di verità. ## Hashing e traduzione I token vengono estratti prima dell'hashing. Ogni token viene sostituito con un marcatore inerte e numerato (`%%1%%`, `%%2%%`, e così via, in ordine di apparizione). È proprio questo *testo con segnaposto* che viene hashato e inviato a chi traduce. Di conseguenza: - **Modificare il valore di un token** (il testo statico, la destinazione di una relazione, il percorso di un asset o il valore di una `var`) **non** altera l'hash inglese. Nessuna lingua diventerà non aggiornata per aver modificato solo un valore. - **Aggiungere, togliere o riordinare i token** **cambia** l'hash, per cui le traduzioni richiederanno un aggiornamento, come ci si aspetterebbe. - **Un testo senza token** ha lo stesso hash di prima al singolo byte. Iniziare a usare i token non causerà un'ondata di documenti da aggiornare. Chi traduce sa che i marcatori `%%n%%` non vanno toccati: ognuno deve essere copiato esattamente una volta, mai tradotto o rinumerato, e va spostato all'interno di una frase solo per questioni di grammatica. Quando arriva una traduzione, un controllo finale verifica che ogni marcatore appaia una volta sola; se c'è un errore, la riga fallisce e ci riprova. I testi tradotti vengono salvati con i marcatori e riempiti in fase di lettura. ## Sostituzione in fase di lettura La sostituzione avviene al momento della lettura, gestita con controlli simili a quelli degli asset. `createScribe()` la abilita per il runtime dell'app; le esportazioni statiche la attivano per la struttura `.md`. La CLI, `scribe validate` e lo studio mantengono la sintassi originale dei token per poter ispezionare e ricalcolare gli hash dei testi sorgente. - **Nei documenti in inglese** i token vengono sostituiti direttamente, risolti per la lingua predefinita. - **Nei documenti tradotti** i marcatori `%%n%%` vengono riempiti usando la lista di token estratta dal testo inglese **attuale**, e risolti per la lingua del documento. In questo modo un link di relazione punta sempre allo slug tradotto corretto, anche se la traduzione del documento è vecchia. A runtime ci sono due casi limite che restituiscono una stringa vuota (e che `scribe validate` segnala): una relazione verso un tipo che non ha un `path` in modalità `:href` e una chiave `var` mancante. ## Validazione `scribe validate` segnala questi problemi a livello di voce: - **Sintassi del token non corretta** (stringa JSON malformata, arità errata, tipo sconosciuto): errore. - **`relation`**: `idTipo` o `enSlug` sconosciuti, modalità mancante, o una relazione `:href` verso un tipo senza percorso: errore. - **`asset`**: il file non esiste sul disco: errore. - **`var`**: la chiave manca nella mappa `vars` del documento, oppure `vars` non è un record da stringa a stringa: errore. Prima di validare il testo MDX, i token originali vengono trasformati in testo inerte, quindi un token valido non causerà mai un falso errore di parsing dell'MDX. ## Riferimenti nel testo ed eliminazione Il pannello "Usato da" dello studio e il browser degli asset analizzano il testo: i token `${{relation:...}}` figurano come riferimenti in ingresso (con l'etichetta di campo `body`), mentre i token `${{asset:...}}` sono registrati come riferimenti espliciti ad asset. Se elimini una voce menzionata soltanto dal **testo** di un'altra voce, l'operazione non si propaga a cascata, non sgancia elementi e non blocca niente; vedi [eliminazione di una voce](/docs/cli#scribe-delete). Il piano di eliminazione elenca questi riferimenti in una sezione "riferimenti nel corpo del testo" con valore di semplice avviso: resteranno appesi e diventeranno errori di validazione dopo la cancellazione.