Keys y catálogos

Un catálogo es un fichero JSON por idioma, y una key es el nombre al que responde un mensaje. Lo normal es que no escribas ninguna: escribes texto y el compilador la nombra por ti. Esta página trata de las veces en que quieres que la key sea tuya, que es lo que le pasa a casi todo proyecto que ya tiene una.

Cuatro formas, un solo catálogo

Se mezclan sin problema en el mismo proyecto y acaban en el mismo fichero. Se elige por mensaje, no por app.

Lo normal: ninguna key

Escribe la frase. El compilador convierte el texto en un id corto y estable, lo escribe en tu catálogo fuente y genera los tipos. Si cambias la redacción sale una key nueva, y eso es lo que se busca: la traducción de la frase vieja nunca se cuela en silencio como si fuera la de la nueva.

t`Hola {name}`;

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

Ids legibles

Cuando quieras abrir el catálogo y reconocer las cosas, nombra el mensaje donde lo escribes con t.id. El texto se queda en tu código y lo que aterriza en el fichero es el id:

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

Los puntos son una convención de nombres, y tu catálogo puede escribirlos de las dos maneras: una key plana "inbox.title", o un title dentro de un grupo inbox. Todos los comandos leen las dos y devuelven la forma que tu fichero ya tenía, así que nada te reformatea el catálogo. Los ids dinámicos (t.id(unaVar)) se dejan intactos, y dos ids iguales con textos distintos disparan el aviso de colisión.

Keys que ya son tuyas

A veces la key es lo importante: la compartes con una app móvil o con una memoria de traducción, sobrevive a cualquier componente y su texto vive solo en el catálogo. Declara esas con defineKeys y Verbaly las trata como usadas, así extract --prune las conserva y check verifica que cada una existe:

import { defineKeys } from 'virtual:verbaly';

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

Los tipos salen de tu propio catálogo, así que una key que no existe es un error ahí mismo, en la línea que la declara, y tu editor completa las que sí. Léelas donde quieras con t(BannerText.title). Los grupos se anidan lo que haga falta, y un valor vacío se salta porque vacío significa sin traducir.

Keys en HTML plano

El texto que vive en HTML que nadie compila no tiene llamada que extraer, así que la key viaja en el elemento. Escribes primero el catálogo y apuntas a él. Este sitio está hecho así, y HTML plano cubre el intérprete entero.

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

Dos formas de catálogo

La plana es la que escribe extract. La anidada es la que escribe una persona. Las dos se leen en todas partes, y cada comando devuelve la forma que el fichero ya tenía, así que un proyecto nunca acaba mitad y mitad.

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

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

Qué idiomas tienes

Si no listas locales, cada fichero JSON de tu carpeta de catálogos es un idioma: deja ahí un pt.json y se detecta. Si listas locales, esa lista es la lista entera, así que un fichero que dejó una ejecución anterior se ignora. npx verbaly doctor te dice cuál de las dos está pasando.