verbatra check

Informa, por cada locale de destino, de cuántas claves faltan, están obsoletas o al día, y termina con un código en el que un paso de CI puede ramificar. check lee y compara como verbatra translate antes de llamar al proveedor y se detiene ahí: sin llamada al proveedor, sin escribir archivos, sin clave de API.

SinopsisCopiar enlace a esta sección

verbatra check [flags]

EjemplosCopiar enlace a esta sección

# hacer fallar el build cuando las traducciones se desfasaron
verbatra check

# estado legible por máquina para dos locales
verbatra check --locales de,fr --json

# listar además los textos de origen traducidos de más de una forma
verbatra check --consistency

# fallar ante placeholders, markup e ICU rotos, y también ante avisos
verbatra check --qa --strict

# fallar mientras haya traducciones automáticas esperando aprobación
verbatra check --require-reviewed

# fallar ante correos, claves de API o números de tarjeta en el origen
verbatra check --sensitive

# comprobar solo el archivo que un editor o un agente acaba de cambiar
verbatra check --file locales/de.json --json

FlagsCopiar enlace a esta sección

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

Una clave falta cuando el origen la tiene y el destino no, y está obsoleta cuando su texto de origen cambió desde la última traducción. Un locale está sincronizado cuando no tiene ninguna de las dos. Para ver las listas de claves detrás de los recuentos, usa verbatra diff.

ComportamientoCopiar enlace a esta sección

Informe de consistenciaCopiar enlace a esta sección

--consistency lista, por locale de destino, cada texto de origen que dos o más claves traducen de forma distinta: el origen, cada traducción y las claves que la llevan. Nunca cambia el código de salida, un valor ni la cola de revisión. Las reglas de comparación:

• Los valores se comparan tras la normalización Unicode NFC, con \r\n convertido en \n y sin espacios al principio ni al final. Los espacios internos y las mayúsculas cuentan.
• Solo se comparan claves al día, y una traducción igual a su origen queda para EQUALS_SOURCE.
• Nunca se agrupan claves cuya descripción, significado, marca de plural o msgctxt de gettext difieran.
• Las formas de plural se comparan por forma: las formas one y other de una clave nunca se agrupan entre sí.

Falsos positivos conocidos: variantes de contexto de i18next (invite_male, invite_female), entradas de gettext marcadas con #, fuzzy, claves con aspecto de plural en un formato sin plurales (yaml, ngx-translate-json, xliff, properties, ini, resx) y las formas de plural de un formato custom:. Dales una descripción o un significado distintos, o ignora el hallazgo. Con --json, cada locale lleva inconsistencies: { source, context?, description?, meaning?, isPlural, pluralForm?, translations: [{ value, keys }] }[].

Claves protegidasCopiar enlace a esta sección

Una clave obsoleta que una persona escribió, importó o cambió fuera de verbatra, o una clave que coincide con pinnedKeys, es una que translate deja para una persona (mira Proteger las traducciones humanas). check la sigue contando y muestra la parte protegida, por ejemplo 2 stale (1 protected). --json la da como protected por locale; si verbatra.provenance.json no se puede leer, solo cuentan las claves fijadas.

Categorías de pluralCopiar enlace a esta sección

Cada check lista los plurales a los que les falta una categoría de plural CLDR que usa su idioma de destino, como un <plurals> de Android en polaco con solo one y other:

plural categories (warning: exit 1 only under --qa --strict)
  pl: 2 plurals missing CLDR categories
    cart {count} plural: missing few, many
    files: missing few, many

Las categorías salen de las reglas CLDR integradas en Node.js (mira soporte de idiomas). Formatos comprobados:

other siempre es obligatoria. Una rama exacta como =1 nunca sustituye a una categoría, las ramas de select nunca se comprueban y solo se comprueba un plural del que el destino tiene al menos una forma. Es un aviso: un check simple conserva su código de salida y --qa --strict falla por él. verbatra doctor informa de los mismos plurales. Con --json, cada locale lleva incompletePlurals, ordenado por clave:

interface IncompletePlural {
  code: "PLURAL_CATEGORIES_INCOMPLETE";
  key: string;              // clave base, o la clave del mensaje ICU
  argument?: string;        // el argumento del plural ICU, como count
  ruleType: "cardinal" | "ordinal";
  missing: ("zero" | "one" | "two" | "few" | "many" | "other")[]; // en orden CLDR
}

Control de calidadCopiar enlace a esta sección

--qa aplica las comprobaciones que una ejecución de traducción hace sobre la salida del proveedor a los valores que ya están en tus archivos de locale, obsoletos o no, incluidas las formas de plural extra que necesita el idioma de destino. Los hallazgos tienen dos gravedades:

• error: el valor no pasa la puerta de integridad, con placeholder, markup, icu, degenerate o empty. Los detalles listan los tokens perdidos como -{{name}} y los añadidos como +{{nom}}.
• warning: el valor lleva un motivo de revisión calculado a partir del valor, su origen y tu configuración (glosario, maxLength), así que ninguno que dependa del proveedor o de la caché; con FOREIGN_PLACEHOLDER_CHANGED, los details del hallazgo nombran cada token perdido o cambiado, como -{name}. Un valor con error no recibe avisos.

qa: 1 error, 1 warning
  de: 1 error, 1 warning in 42 values checked
    greeting: error placeholder (-{{name}}, +{{nme}})
    title: warning EQUALS_SOURCE

Las claves huérfanas y las que faltan se omiten, y las claves de origen que no son ICU válido aparecen una vez en invalidSourceKeys. Los valores protegidos, fijados y rechazados se comprueban como cualquier otro. Con --json, result.qa guarda los totales y cada locale su propio qa:

interface CheckQaSummary { errors: number; warnings: number; invalidSourceKeys: string[] }
interface LocaleQaReport { checked: number; errors: number; warnings: number; findings: QaFinding[] }
type QaFinding =
  | { key: string; severity: "error"; reason: "placeholder" | "markup" | "icu" | "degenerate" | "empty"; details?: string[] }
  | { key: string; severity: "warning"; reason: string; details?: string[] }; // uno de los motivos de revisión de arriba

Exigir traducciones revisadasCopiar enlace a esta sección

--require-reviewed falla con 1 mientras un valor cuyo origen sea machine, memory, fuzzy o agent no esté aprobado en el verbatra.provenance.json confirmado, donde Studio y las herramientas MCP guardan sus decisiones. Una aprobación anterior al cambio del texto de origen o del valor no cuenta.

review: failed [REVIEW_REQUIRED] 2 machine-written translations not approved
  de: 2 unreviewed: checkout.title, checkout.total

Con --json, result.review es { reviewed, unreviewed, code? }, donde code es REVIEW_REQUIRED, o REVIEW_STATE_UNREADABLE cuando el archivo de procedencia está dañado o viene de un verbatra más nuevo (entonces la puerta falla). Cada locale lleva review.unreviewed, las claves en el orden del origen.

Contenido sensibleCopiar enlace a esta sección

--sensitive ejecuta la revisión de la protección de contenido sensible sobre cada clave de origen (nombre de clave, valor, descripción y significado) y el glosario de cada locale comprobado, con los detectores, patrones y la lista allow de sensitiveData (sin bloque, los detectores por defecto), con cualquier mode y proveedor, none incluido: los valores siguen saliendo del equipo en entregas por exportación, XLIFF y TMX. Informa de claves y detectores, nunca del texto encontrado fuera de un nombre de clave, y sale con 1 ante cualquier hallazgo.

El detector email omite los dominios de ejemplo reservados, así que prueba con una dirección de aspecto real.

sensitive: 1 key and 0 glossary terms hold content that looks sensitive
  support.contact: email in value

Con --json, result.sensitive es { findings, glossaryTerms }, y cada hallazgo { key, fields, detectors }; detectors puede incluir pattern-timeout-<n>.

Un solo archivoCopiar enlace a esta sección

--file <path> comprueba un único archivo de locale, pensado para hooks de editor y de agente tras una edición. Lee ese archivo, verbatra.limits.json nuevo (si no se puede usar, se ignora con un aviso en stderr, como con --qa; doctor nombra el problema) y, para un locale de destino, el archivo de origen, nada más. La ruta se resuelve respecto a --cwd y se asocia a su locale mediante files.pattern.

• Un archivo que no se puede analizar da un error syntax con el código del adaptador (INVALID_JSON, INVALID_YAML, ...) y la línea y la columna cuando el analizador informa de una posición.
• Un archivo de destino se comprueba como con --qa, categorías de plural incluidas; un archivo de origen, solo la sintaxis. Un catálogo apple-xcstrings se comprueba para cada locale de destino.
• Una ruta que no es el archivo de ningún locale configurado falla con NOT_A_LOCALE_FILE y sale con 2.

Con --json, result reutiliza el informe de --qa, así que un hook analiza una sola forma:

interface CheckFileSummary {
  file: string;                          // relativo a la raíz del proyecto
  role: "source" | "target" | "catalogue";
  locales: {
    locale: string;
    incompletePlurals: IncompletePlural[];
    qa: { checked: number; errors: number; warnings: number; findings: (QaFinding | QaSyntaxFinding)[] };
  }[];
  qa: CheckQaSummary;
}
interface QaSyntaxFinding {
  severity: "error"; reason: "syntax"; code: string; message: string;
  line?: number; column?: number;       // si el analizador informa de una posición, contando desde 1
}

Las claves que faltan y las obsoletas no forman parte de la comprobación de un archivo.

Salida JSONCopiar enlace a esta sección

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

--json imprime un envoltorio cuyo result es el documento de estado. Sin --qa, --require-reviewed ni --sensitive, inSync es verdadero exactamente cuando el comando sale con 0:

interface CheckSummary {
  inSync: boolean;
  locales: LocaleCheckSummary[];
  qa?: CheckQaSummary;          // solo con --qa
  review?: CheckReviewSummary;  // solo con --require-reviewed
  sensitive?: CheckSensitiveSummary; // solo con --sensitive
}

interface LocaleCheckSummary {
  locale: string;
  missing: number;              // en el origen, ausente del destino
  stale: number;                // el origen cambió desde la última traducción
  upToDate: number;
  inSync: boolean;              // missing === 0 && stale === 0
  emptySource?: number;         // valor de origen vacío: nunca falta ni está desactualizado
  provenance?: ProvenanceSummary; // recuentos por origen y estado de revisión
  protected?: number;
  incompletePlurals?: IncompletePlural[];
  inconsistencies?: InconsistencyGroup[]; // solo con --consistency
  qa?: LocaleQaReport;          // solo con --qa
  review?: LocaleReviewReport;  // solo con --require-reviewed
}

Una clave de origen cuyo valor está vacío o solo tiene espacios, como una que extract añadió sin valor por defecto, aún no tiene nada que traducir: se cuenta en emptySource en lugar de missing o stale, nunca deja un locale fuera de sincronía, y la salida de terminal indica el número.

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

check muestra verbatra: checking the locales... done (0.1s) en stderr, o verbatra: checking locales/de.json... con --file. --quiet la omite. Mira Salida en el terminal.

Códigos de salidaCopiar enlace a esta sección

La salida 1 significa que el resultado no está limpio, no que la ejecución fallara; el informe se imprime igual. En un proyecto cuyo archivo de origen aún no existe, verbatra doctor sigue informando. El contrato está en Códigos de salida.

RelacionadoCopiar enlace a esta sección

• verbatra diff lista las claves exactas detrás de estos recuentos.
• CI y códigos de salida muestra check como puerta contra desfases.
• El archivo de bloqueo explica cómo se detecta que algo está obsoleto.