Keys e catálogos

Um catálogo é um arquivo JSON por idioma, e uma key é o nome ao qual uma mensagem responde. O normal é que você não escreva nenhuma: você escreve texto e o compilador a nomeia por você. Esta página trata das vezes em que você quer que a key seja sua, que é o que acontece com quase todo projeto que já tem uma.

Cinco formas, um só catálogo

Elas se misturam sem problema no mesmo projeto e acabam no mesmo arquivo. Escolhe-se por mensagem, não por app.

O normal: nenhuma key

Escreva a frase. O compilador transforma o texto num id curto e estável, escreve-o no seu catálogo fonte e gera os tipos. Se você mudar a redação sai uma key nova, e é isso que se busca: a tradução da frase antiga nunca entra em silêncio como se fosse a da nova.

t`Hola {name}`;

// locales/es.json
"eYJLZELq": "Hola {name}"

Ids legíveis

Quando você quiser abrir o catálogo e reconhecer as coisas, nomeie a mensagem onde a escreve com t.id. O texto fica no seu código e o que chega ao arquivo é o id:

t.id('inbox.title')`Hello {name}`;
// extracted under "inbox.title" and rewritten to:
t('inbox.title', { name });

Os pontos são uma convenção de nomes, e o seu catálogo pode escrevê-los das duas maneiras: uma key plana "inbox.title", ou um title dentro de um grupo inbox. Todos os comandos leem as duas e devolvem a forma que o seu arquivo já tinha, então nada reformata o seu catálogo. Ids dinâmicos (t.id(algumaVar)) ficam intactos, e um id escrito com dois textos é reportado com cada lugar que não bate, porque todos mostram o que foi escrito primeiro, pelo caminho do arquivo, seja qual for a ordem em que seus arquivos carregam.

Texto que vive no catálogo

Você também pode deixar o texto no catálogo e escrever só a chave no seu código. Uma chave escrita como literal conta como usada, então o extract --prune a mantém e o check verifica que ela existe. Escolha isso quando o texto muda mais que o código, ou quando alguém edita os textos sem abrir um componente.

// locales/es.json
"about.bio": "Escribo software en Lima."

t('about.bio');

Quando a chave vem de um dado, um mapa por slug ou por id, declare-a com defineKeys, mais abaixo, para que o compilador a veja e o seu editor a verifique.

Cada chave é tipada

Cada t do seu projeto confere as chaves contra o seu catálogo: o de virtual:verbaly, useT() em React, Vue e Svelte, getT() no Next.js, e o t de qualquer instância. Uma chave que você escreve e que nenhum catálogo tem não compila, o erro a nomeia, e uma mensagem com um {name} o pede.

t('about.bio');   // ✓
t('about.boi');   // ✗ '"about.boi"' is not assignable to … VerbalyKey
t(item.key);      // ✓ a key from data passes as it is

Uma chave que vem de dados, uma string ou um template com uma parte que vem de dados como t(`status.${s}`), passa como está, porque nenhum catálogo tem como saber qual chave será. Uma variável tipada como uma união de chaves, incluindo a própria VerbalyKey, também é um dado: cada chave que ela pode ser tem de existir, e os seus params ficam abertos. Declare essas chaves com defineKeys, mais abaixo, quando quiser que o check confira que existem e que o extract --prune as mantenha.

Keys que já são suas

Às vezes a key é o que importa: você a compartilha com um app móvel ou com uma memória de tradução, ela sobrevive a qualquer componente e o seu texto vive só no catálogo. Declare essas com defineKeys e o Verbaly as trata como usadas, então extract --prune as mantém e check verifica que cada uma existe:

import { defineKeys } from 'virtual:verbaly';

export const BannerText = defineKeys({
  title: 'alerts_banner_title',
  button: 'alerts_banner_button',
});

Os tipos vêm do seu próprio catálogo, então uma key que não existe é um erro ali mesmo, na linha que a declara, e o seu editor completa as que existem. Leia-as onde quiser com t(BannerText.title). Os grupos aninham o quanto for preciso, e um valor vazio é ignorado porque vazio significa sem tradução.

De quem é um texto

Uma mensagem guarda o seu texto num só lugar, e esse lugar é onde você o muda. Um texto escrito no seu código, com t`…` ou t.id, é do código: o extract, os servidores de desenvolvimento e o build o usam, então uma edição dele no catálogo fonte é substituída, e o Verbaly diz qual arquivo tem o texto. Um texto que vive só no catálogo é editado lá. Todo comando que lê um texto fonte lê o que é publicado: check, status, review, translate, export, import, o Studio e os agentes.

Uma tradução lembra para qual texto foi escrita. Nas chaves legíveis, o Verbaly guarda uma impressão curta do texto fonte e de cada tradução em verbaly.lock, ao lado da sua config, tirada no momento em que a tradução é escrita, seja quem for que a escreva. Mude um texto fonte e as traduções dele aparecem como desatualizadas em status, check e doctor até alguém atualizá-las, ou mantê-las com verbaly review --approve. Editar uma tradução a limpa sozinha. Chaves com hash nunca precisam disso: um texto novo é uma chave nova.

Keys em HTML puro

O texto que vive em HTML que ninguém compila não tem chamada para extrair, então a key viaja no elemento. Você escreve primeiro o catálogo e aponta para ele. Este site é feito assim, e HTML puro cobre o interpretador inteiro.

<h1 data-verbaly="inbox.title">Inbox</h1>

Duas formas de catálogo

A plana é a que o extract escreve. A aninhada é a que uma pessoa escreve. As duas são lidas em todo lado, e cada comando devolve a forma que o arquivo já tinha, então um projeto nunca acaba metade e metade.

// flat
{ "inbox.title": "Bandeja" }

// nested, the same key
{ "inbox": { "title": "Bandeja" } }

Que idiomas você tem

Se você não listar locales, cada arquivo JSON da sua pasta de catálogos é um idioma, exceto o do pseudo-idioma: deixe ali um pt.json e ele é detectado. Se listar locales, essa lista é a lista inteira, então um arquivo deixado por uma execução anterior é ignorado. npx verbaly doctor diz qual das duas está acontecendo.