Tokens inline

Os corpos MDX muitas vezes precisam de um valor que o Scribe já conhece: um link para outra entrada, a URL pública de um asset, um valor literal que nunca deve ser traduzido ou uma pequena string específica do documento reutilizada em vários lugares. Fixar esses valores no código torna os corpos frágeis (um slug renomeado ou um asset movido quebra links silenciosamente) e prejudica a tradução (uma URL nunca deve ser "traduzida").

Os tokens inline resolvem isso. Você cria um token uma vez no corpo em inglês. Ele é resolvido para cada idioma no momento da leitura, enquanto o processo de tradução o trata como um placeholder opaco e imutável.

Sintaxe

Um token tem o formato ${{<kind>:<args>}}. Existem quatro tipos:

Token	Resolve para
`${{static:"text"}}`	O literal exato `text` (uma string JSON, então aspas e escapes são bem definidos). Nunca é traduzido, sendo idêntico em todos os idiomas.
`${{relation:<typeId>:<enSlug>:href}}`	Um caminho de link para a entrada de destino (veja modos de relação). O sufixo de modo é obrigatório.
`${{relation:<typeId>:<enSlug>:slug}}`	A string do slug em inglês do destino, que é um identificador estável para componentes MDX que carregam o conteúdo do Scribe por conta própria.
`${{asset:/web/path.webp}}`	A URL pública do asset (`assets.publicPath` concatenado ao caminho). Veja assets.
`${{var:key}}`	O valor `frontmatter.vars[key]` do mesmo documento.

Os slugs não podem conter :, por isso a análise sintática de relações não tem ambiguidades. Um ${{relation:<typeId>:<enSlug>}} simples, sem o sufixo de modo, gera um erro de validação.

Modos de relação

Todo token de relação deve terminar com :href ou :slug.

Modo	Propósito
`:href`	Link navegável. O formato resolvido depende de quem consome (veja abaixo).
`:slug`	Identidade: sempre a string do slug em inglês do destino.

O modo :href é resolvido de forma diferente dependendo de quem lê o documento:

Consumidor	`:href` resolve para
`createScribe()` (tempo de execução do app)	Caminho sem idioma com o slug localizado, por exemplo, `/para/vestidos`. Passe-o diretamente para o componente `Link` do seu roteador.
Exportação estática `.md`	Caminho público localizado completo com extensão de arquivo, por exemplo, `/es/para/vestidos.md`, que corresponde à estrutura de arquivos exportada.

Válvula de escape

${{ (uma barra invertida entre o cifrão e as chaves) renderiza um literal ${{ e nunca é tratado como um token. Use isso para mostrar a sintaxe de tokens no conteúdo da documentação. Esta página faz exatamente isso.

A chave de frontmatter `vars`

vars é um Record<string, string> opcional que qualquer entrada pode declarar sem adicioná-lo ao schema de tipos:

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

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

vars é uma chave reservada. Ela é extraída antes da validação do schema (para que um schema rigoroso nunca a rejeite), nunca é tratada como um campo traduzível e existe apenas no documento em inglês. Documentos traduzidos leem ${{var:key}} do mapa vars do seu documento pai em inglês, garantindo assim uma única fonte de verdade.

Hashing e tradução

Os tokens são extraídos antes do hashing. Cada token é substituído por um marcador numérico inerte (%%1%%, %%2%%, e assim por diante, na ordem de aparição), e esse corpo com placeholders é o que recebe o hash e é enviado ao tradutor. Consequências:

Alterar o valor de um token (o texto estático, o destino da relação, o caminho do asset ou um valor var) não altera o hash em inglês, então nenhum idioma fica desatualizado por causa de uma edição apenas de valor.
Adicionar, remover ou reordenar tokens altera o hash, de modo que as traduções são preparadas novamente conforme o esperado.
Um corpo com zero tokens gera exatamente o mesmo hash de antes, de modo que a adoção de tokens não causa desatualizações em massa.

O tradutor recebe instruções de que os marcadores %%n%% são imutáveis: reproduza cada um exatamente uma vez, nunca os traduza ou renumere, e mova-os dentro de uma frase apenas quando a gramática exigir. Após o recebimento de uma tradução, uma verificação pós-recebimento confirma se cada marcador aparece exatamente uma vez. Se houver divergência, a linha falha e o sistema tenta novamente. Corpos traduzidos armazenados mantêm os marcadores e os preenchem no momento da leitura.

Substituição no momento da leitura

A substituição ocorre no caminho de leitura, sendo controlada da mesma forma que a resolução de assets. O createScribe() a habilita para o tempo de execução do app, enquanto exportações estáticas a habilitam para a estrutura .md. A CLI, o comando scribe validate e o estúdio mantêm a sintaxe bruta do token para poderem inspecionar e recalcular o hash dos corpos de origem.

Documentos em inglês têm seus tokens substituídos no próprio local, resolvidos para o idioma padrão.
Documentos traduzidos têm seus marcadores %%n%% preenchidos usando a lista de tokens extraída do corpo atual em inglês, resolvidos para o idioma do documento. Assim, um link de relação sempre aponta para o slug localizado atual, mesmo quando a própria tradução for mais antiga.

Dois casos extremos resolvem para uma string vazia em tempo de execução (e são sinalizados pelo comando scribe validate): uma relação cujo tipo de destino não tem path no modo :href e uma chave var ausente.

Validação

O comando scribe validate relata os seguintes problemas no nível da entrada:

Sintaxe de token malformada (string JSON inválida, número incorreto de argumentos, tipo desconhecido): erro.
relation: typeId desconhecido, enSlug desconhecido, modo ausente ou uma relação :href apontando para um tipo não roteável: erro.
asset: o arquivo não existe no disco: erro.
var: a chave está ausente no mapa vars do documento ou vars não é um registro de string para string: erro.

Os tokens brutos são mascarados como texto inerte antes da validação do corpo MDX. Portanto, um token válido nunca produz um falso erro de análise MDX.

Referências no corpo e exclusão

O painel "Used by" do estúdio e o navegador de assets escaneiam os corpos. Os tokens ${{relation:...}} aparecem como referências reversas (rótulo de campo body), e os tokens ${{asset:...}} são registrados como referências declaradas a assets. Excluir uma entrada referenciada apenas a partir do corpo de outra entrada nunca causa exclusão em cascata, separação ou bloqueio. Consulte exclusão de entrada. O plano de exclusão lista essas referências em uma seção "body references" que emite apenas aviso: elas ficarão órfãs e se tornarão erros de validação após a exclusão.