verbatra diff

Lista, por locale de destino, las claves pendientes exactas: las que una ejecución añadiría, las que retraduciría y las que ahora están huérfanas. diff hace la misma lectura y el mismo diff que verbatra translate y luego se detiene: sin llamada al proveedor, sin archivos escritos, sin actualizar el archivo de bloqueo y sin clave de API.

SinopsisCopiar enlace a esta sección

verbatra diff [flags]

EjemplosCopiar enlace a esta sección

# lista las claves pendientes por locale (sale con 1 si hay alguna)
verbatra diff

# solo los locales alemán y francés
verbatra diff --locales de,fr

# listas de claves legibles por máquina para herramientas o un comentario en el PR
verbatra diff --json

# lista también las claves de origen que tu código ya no nombra
verbatra diff --unused

FlagsCopiar enlace a esta sección

También acepta los flags globales --cwd, --config y --json.

ComportamientoCopiar enlace a esta sección

Claves pendientes y huérfanasCopiar enlace a esta sección

Cada locale lista cuatro tipos de clave:

Un locale tiene cambios pendientes cuando tiene al menos una clave faltante o cambiada. Las claves huérfanas nunca cuentan como pendientes, porque una ejecución por defecto las deja donde están; solo verbatra translate --prune las elimina. verbatra check da los contadores, diff da las listas de claves.

Claves de origen sin usoCopiar enlace a esta sección

--unused responde otra pregunta que orphaned: ¿qué claves de tu archivo de locale de origen ya no nombra tu aplicación? Analiza las roots del bloque extract con el lector que usa verbatra extract y lista cada clave de origen que ninguna referencia estática nombra. Las dos listas nunca se fusionan. El análisis solo lee: no se elimina nada y no se lee ninguna clave de API. Borrar una clave es decisión tuya.

El análisis modela el runtime de i18next. Esto cuenta como referencia:

• una llamada t(...), $t(...) o <object>.t(...) en cualquier lugar bajo las raíces, también a través de un alias como const { t: translate } = useTranslation(), const tr = i18n.t, t.bind(i18n) o i18n.getFixedT(...);
• un keyPrefix estático o un tercer argumento estático de getFixedT, que cubre también la forma con prefijo de cada clave estática de ese archivo, y un i18nKey estático en Trans o en un objeto;
• una clave con namespace (common:nav.home cubre también nav.home), una clave en lenguaje natural y cada entrada de un array estático de claves;
• una variante de plural o de contexto de una clave referenciada (t("items", { count }) cubre items_one e items_other) y cada clave bajo un padre referenciado.

Las claves se comparan en la codificación propia del formato del catálogo, así que una clave JSON plana con puntos, un plural o una entrada msgctxt de gettext y una entrada <plurals> de Android coinciden con la clave que nombra tu código. Un template literal con cabeza estática, como t(`nav.${page}`), lista las claves bajo nav. como possiblyDynamic, aparte de unused, y nunca hace fallar la ejecución.

El informe lleva un status: complete (se acotaron todas las claves alcanzables, así que unused es fiable), unreliable (una clave listada puede seguir en uso; unreliableBecause nombra cada motivo con su recuento y sus ubicaciones) o not-run (no se lista nada; reason dice por qué):

Las fuentes de funciones de traducción reconocidas son: useTranslation(...) desestructurado en un binding local, no exportado, con argumentos estáticos; un i18n.getFixedT(...) local con argumentos estáticos; una llamada directa a un miembro t (i18n.t("key"), this.props.t("key")) y su alias local; <Translation>{(t) => ...}</Translation>; withTranslation("ns")(Component) con props.t(...); e import { t } from "i18next". Se evalúa cualquier variable o miembro llamado t o $t, así que un frame.t + 1 ajeno puede volver el informe poco fiable. En archivos .tsx, .jsx y .js, el texto JSX y los valores de atributo entre comillas se leen como marcado, nunca como código.

Cada clave listada muestra su forma decodificada (una entrada msgctxt de gettext como menu|Open); --json lleva además la catalogKey tal como la escribe el adaptador. Una clave usada solo fuera del código analizado (una plantilla de servidor, un CMS) va en extract.unused.ignore: un patrón coincide con la clave decodificada, y una clave que coincide se lista bajo ignored, nunca desaparece sin aviso.

Claves protegidasCopiar enlace a esta sección

Las claves faltantes y cambiadas que translate dejaría para una persona (una persona escribió, importó o cambió el valor fuera de verbatra, o la clave coincide con pinnedKeys) se listan además bajo protected; consulta Proteger traducciones humanas. Siguen en add y re-translate, porque siguen pendientes. Si verbatra.provenance.json está dañado o es de un verbatra más nuevo, solo se listan las claves fijadas.

Salida JSONCopiar enlace a esta sección

Esquema: diff-envelope.json valida el envoltorio completo; Esquemas enumera los demás.

--json imprime un envoltorio cuyo result es un DiffSummary. hasPendingChanges es verdadero exactamente cuando el comando sale con 1 por claves pendientes:

interface DiffSummary {
  hasPendingChanges: boolean;
  locales: LocaleDiff[];
  unused?: UnusedKeysReport;   // solo con --unused
}

interface LocaleDiff {
  locale: string;
  missing: string[];           // se añadiría
  changed: string[];           // se retraduciría
  orphaned: string[];          // solo se informa
  emptySource?: string[];      // valor de origen vacío: nunca pendiente
  hasPendingChanges: boolean;  // missing.length > 0 || changed.length > 0
  changedOrigins?: Record<string, KeyOrigin>; // ausente si el archivo de procedencia no se puede leer
  protected?: string[];        // claves pendientes que translate deja como están
}

Información en el terminalCopiar enlace a esta sección

diff muestra una línea mientras trabaja (con un recuento de archivos en curso cuando --unused analiza el código) y sugiere el siguiente comando:

verbatra: diffing and scanning the source... done (0.8s)
next: verbatra translate (send the pending keys to your provider)

Si todas las claves pendientes están protegidas, sugiere verbatra studio; con provider: { id: "none" }, sugiere verbatra export. Estas líneas van a stderr, y --quiet las omite. Consulta Salida en el terminal.

Códigos de salidaCopiar enlace a esta sección

Las claves huérfanas, posiblemente dinámicas e ignoradas, y un informe unreliable o not-run, nunca producen 1 por sí solos. Consulta el contrato de códigos de salida.

RelacionadoCopiar enlace a esta sección

• verbatra check da los contadores por locale detrás de estas listas.
• verbatra translate aplica los cambios pendientes; --prune elimina las claves huérfanas.
• El archivo de configuración documenta el bloque extract y unused.ignore.
• CI y códigos de salida muestra diff en una canalización.