Token in linea

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 è ${{<tipo>:<argomenti>}}. 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:<idTipo>:<enSlug>:href}}`	Un percorso di collegamento alla voce di destinazione (vedi modalità delle relazioni). Il suffisso della modalità è obbligatorio.
`${{relation:<idTipo>:<enSlug>: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.
`${{var:chiave}}`	`frontmatter.vars[chiave]` dello stesso documento.

Gli slug non possono contenere :, quindi il parsing delle relazioni non è ambiguo. Scrivere solo ${{relation:<idTipo>:<enSlug>}} 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<string, string> opzionale che qualsiasi voce può dichiarare senza doverlo aggiungere allo schema del tipo:

---
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. 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.