Keys e catálogos

Um catálogo é um ficheiro 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.

Quatro formas, um só catálogo

Elas se misturam sem problema no mesmo projeto e acabam no mesmo ficheiro. 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 ficheiro é 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 ficheiro já tinha, então nada reformata o seu catálogo. Os ids dinâmicos (t.id(umaVar)) ficam intactos, e dois ids iguais com textos diferentes disparam o aviso de colisão.

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.

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 ficheiro 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 ficheiro JSON da sua pasta de catálogos é um idioma: deixe ali um pt.json e ele é detectado. Se listar locales, essa lista é a lista inteira, então um ficheiro deixado por uma execução anterior é ignorado. npx verbaly doctor diz qual das duas está acontecendo.