Tokens en línea

Los cuerpos de MDX suelen necesitar valores que Scribe ya conoce, como un enlace a otra entrada, la URL pública de un recurso, un literal que no se debe traducir o una pequeña cadena de texto específica del documento que se reutiliza en varios lugares. Escribir estos valores directamente hace que el contenido sea frágil (cambiar el nombre de un slug o mover un recurso rompe los enlaces sin previo aviso) y ensucia la traducción (las URL no se deben traducir).

Los tokens en línea resuelven este problema. Solo tienes que crear el token una vez en el documento en inglés y este se resolverá para cada idioma en el momento de la lectura. Durante la traducción, el sistema lo tratará como un marcador de posición opaco e inmutable.

Sintaxis

La sintaxis de un token es ${{<kind>:<args>}}. Existen cuatro tipos:

Token	Se resuelve en
`${{static:"text"}}`	El literal exacto `text` (una cadena JSON, por lo que las comillas y los caracteres de escape están bien definidos). No se traduce y es idéntico en todos los idiomas.
`${{relation:<typeId>:<enSlug>:href}}`	Una ruta de enlace a la entrada de destino (consulta los modos de relación). El sufijo de modo es obligatorio.
`${{relation:<typeId>:<enSlug>:slug}}`	La cadena del slug en inglés del destino, que sirve como identificador estable para los componentes MDX que cargan contenido de Scribe por sí mismos.
`${{asset:/web/path.webp}}`	La URL pública del recurso (la unión de `assets.publicPath` y la ruta). Consulta la sección de recursos.
`${{var:key}}`	La clave `frontmatter.vars[key]` del mismo documento.

Los slugs no pueden contener :, por lo que el análisis de las relaciones es inequívoco. Escribir un token ${{relation:<typeId>:<enSlug>}} sin el sufijo de modo provocará un error de validación.

Modos de relación

Todos los tokens de relación deben terminar en :href o :slug.

Modo	Propósito
`:href`	Enlace por el que se puede navegar. Su forma final dependerá de dónde se consuma (como se explica más abajo).
`:slug`	Identidad (siempre devolverá la cadena del slug en inglés de la entrada de destino).

El sufijo :href se resuelve de forma distinta según quién lea el documento:

Entorno de lectura	Resultado de `:href`
`createScribe()` (ejecución de la app)	Ruta sin idioma pero con el slug traducido (por ejemplo, `/for/vestidos`). Se puede pasar directamente al `Link` del enrutador.
Exportación `.md` estática	Ruta pública completa y traducida con la extensión del archivo (por ejemplo, `/es/for/vestidos.md`), coincidiendo con la estructura de archivos de la exportación.

Sintaxis de escape

Si escribes $\\{{ (una barra invertida entre el signo de dólar y las llaves), se generará el texto literal ${{ y no se interpretará como un token. Utiliza este recurso para mostrar la sintaxis de los tokens en la documentación (esta página es un buen ejemplo de ello).

La clave `vars` del frontmatter

La clave vars es un Record<string, string> opcional que cualquier entrada puede declarar sin necesidad de añadirlo al esquema de tipos:

---
title: Spring sale
vars:
  cta: Shop the sale
---

Ready? ${{var:cta}}. Limited time only.

vars es una clave reservada. Se extrae antes de validar el esquema (para que un esquema estricto no la rechace), nunca se trata como un campo traducible y solo existe en el documento en inglés. Los documentos traducidos leen ${{var:key}} del mapa de vars de su versión original en inglés, por lo que solo hay una única fuente de verdad.

Hash y traducción

Los tokens se extraen antes de aplicar el hash. Cada uno se sustituye por un marcador inerte y numerado (%%1%%, %%2%%, …, en orden de aparición). El documento con estos marcadores es lo que se cifra y se envía para traducir. Consecuencias:

Cambiar el valor de un token (el texto estático, el destino de una relación, la ruta de un recurso o el valor de una variable var) no modifica el hash original en inglés, así que ninguna traducción se quedará obsoleta por editar solo el valor.
Añadir, eliminar o reordenar tokens sí cambia el hash, de forma que las traducciones volverán a entrar en fase de preparación como es de esperar.
Un documento sin tokens mantendrá exactamente el mismo hash que antes, así que implementar tokens no provocará que todo el contenido se marque como obsoleto.

Se indica a los traductores que los marcadores %%n%% son inmutables (deben reproducir cada uno exactamente una vez, nunca traducirlos ni renumerarlos, y solo moverlos dentro de una frase cuando la gramática lo exija). Al recibir una traducción, el sistema realiza una comprobación para verificar que cada marcador aparece exactamente una vez. Si hay alguna discrepancia, la fila falla y se vuelve a intentar. Los documentos traducidos y guardados conservan los marcadores para rellenarlos en el momento de la lectura.

Sustitución durante la lectura

La sustitución es un proceso que ocurre durante la ruta de lectura y está controlado al igual que la resolución de recursos. createScribe() lo activa durante la ejecución de la aplicación, mientras que las exportaciones estáticas lo activan en la estructura .md. La interfaz de línea de comandos, scribe validate y el entorno de estudio mantienen la sintaxis original de los tokens para poder inspeccionar los documentos de origen y volver a calcular sus hashes.

En los documentos en inglés, los tokens se sustituyen en el mismo lugar y se resuelven para el idioma por defecto.
En los documentos traducidos, los marcadores %%n%% se rellenan con la lista de tokens extraída del documento original en inglés actual y se resuelven para el idioma de la traducción. De este modo, el enlace de una relación siempre apuntará al slug activo del idioma correspondiente incluso si la propia traducción es antigua.

Existen dos casos extremos que darán como resultado una cadena vacía durante la ejecución (y que scribe validate señalará): una relación cuyo tipo de destino carece de path en el modo :href y la ausencia de la clave var.

Validación

scribe validate notifica los siguientes problemas a nivel de entrada:

Sintaxis de token mal formada (cadena JSON incorrecta, aridad errónea, tipo desconocido): provoca un error.
relation: typeId desconocido, enSlug desconocido, falta el modo o una relación :href apunta a un tipo que no se puede enrutar (error).
asset: el archivo no se encuentra en el disco (error).
var: la clave no está en el mapa de vars del documento o vars no es un registro de cadenas a cadenas (error).

Los tokens sin procesar se ocultan como texto inerte antes de validar el contenido MDX, por lo que un token válido nunca generará un falso error de análisis MDX.

Referencias en el documento y eliminación

El panel "Used by" del estudio y el navegador de recursos examinan el contenido de los documentos. Los tokens ${{relation:...}} aparecen como referencias inversas (etiqueta de campo body) y los tokens ${{asset:...}} se registran como referencias a recursos declarados. Borrar una entrada a la que solo se hace referencia desde el cuerpo de otra nunca provocará un efecto en cascada, desconexión o bloqueo (consulta cómo eliminar una entrada). El plan de eliminación incluye estas referencias en la sección "body references", que sirve solo de advertencia (quedarán huérfanas y se convertirán en errores de validación una vez borradas).