Docs / Conceptos
Página traducida automáticamente
Seguridad de la traducción
El modelo de seguridad: cadenas no confiables, la puerta de integridad, las señales de revisión, el presupuesto de tokens y errores que nunca filtran nada.
verbatra no se fía ni de las cadenas que traduce ni de lo que devuelve un proveedor.
| Capa | Protege contra | Si falla |
|---|---|---|
| Frontera contra la inyección de prompts | una cadena que parece una instrucción | nada que falle: las cadenas son siempre solo datos |
| Puerta de integridad | placeholders, ICU o marcado rotos, valores vacíos o degenerados | la clave se retiene y se reintenta en la siguiente ejecución |
| Señales de revisión | un valor válido pero sospechoso | la clave se escribe y entra en la cola de una persona |
| Presupuesto de tokens | gastar por encima de un techo que tú fijas | el resto de la ejecución se retiene, o se marca |
| Errores estructurados | una clave o una cabecera que se cuela en un mensaje | un código estable con un mensaje fijo |
Cadenas no confiables y la frontera contra la inyección de prompts
Una cadena traducible puede contener texto que parece una instrucción ("ignora tus instrucciones"), así que verbatra trata cada cadena como entrada no confiable. Las reglas de sistema que se envían a un proveedor LLM son constantes de compilación. Todo lo variable (las entradas, tu glosario y tu tono, los nombres de idioma, las categorías de destino de un plural) viaja solo en la carga JSON del turno de usuario, nunca en el canal de instrucciones. La respuesta debe ajustarse a un esquema fijo; una respuesta con una clave que nunca se pidió hace fallar su sublote entero.
Nombres de idioma, escritura y región
Un código de locale solo no siempre basta: sr-Latn a menudo vuelve en cirílico, y pt-BR y
pt-PT se confunden. Por eso un proveedor LLM también recibe el nombre en inglés, la escritura y la
región de cada idioma, tomados de Node.js para el locale de tu configuración aunque localeMap envíe
otro código. Viajan como datos, una regla de sistema fija pide al modelo que escriba en la escritura
y la variante nombradas, y no forman parte de la huella de la caché. Un código que
Node.js no sabe nombrar, como el de uso privado qaa, se envía sin nombre.
La puerta de integridad
Una traducción que cumple el esquema aún puede estar rota, así que una puerta decide a partir del propio valor candidato si lo acepta; nunca se fía del informe del proveedor. La misma puerta se aplica en todas las vías de escritura: una respuesta del proveedor, un acierto de caché, una fila importada de un libro de trabajo y una edición escrita en Studio. Un valor compartido por varias claves con el mismo texto de origen se comprueba clave por clave frente al origen de cada una.
| Comprobación | Un candidato se rechaza cuando |
|---|---|
| Placeholders | sus placeholders difieren de los del origen, comparados como un multiconjunto (el número cuenta, el orden no). Qué cuenta como placeholder lo define cada formato. |
| ICU | en next-intl y ARB, ya no se puede analizar como mensaje ICU, o sus ramas de plural no encajan con el idioma de destino (abajo). La comparación tiene en cuenta las ramas, así que se detecta un placeholder inventado dentro de una rama de plural. |
| Tokens inventados | en i18next, ngx-translate y YAML, añade un token con forma {name} que el origen nunca tuvo. Quitar uno está permitido, porque ahí las llaves simples son texto literal. |
| Marcado en línea | sus etiquetas HTML o XML difieren de las del origen, o están desequilibradas (abajo). |
| Degeneración | es un bucle de repeticiones, o su longitud se ha disparado respecto al origen. |
| Vacío | está vacío o solo tiene espacios para un origen que no lo está. Vaciar una traducción es un acto deliberado: lo hace el marcador [[CLEAR]] del libro de trabajo (Traducción manual). |
Un candidato que incumple varias comprobaciones se rechaza con un solo motivo, el primero que se
aplica en este orden: empty, icu (no se puede analizar), placeholder, markup, icu (ramas),
degenerate. Cada motivo, y los detalles que verbatra imprime con él, está en
Motivos de rechazo por integridad.
Lo que garantiza la puerta: un valor rechazado nunca se escribe. Aparece en el resumen de la ejecución como discrepancia de integridad, conserva su hash anterior en el archivo de bloqueo y se reintenta en la siguiente ejecución. Una clave que no recibió ninguna traducción (la llamada al proveedor falló, o la clave seguía ausente tras una petición de reparación) se informa en cambio como fallo del proveedor, y se reintenta igual. Del lado del origen, una clave cuyo propio valor tiene ICU no válido se aparta antes de traducir.
Lo que no garantiza: que la traducción sea correcta. Demuestra la estructura, no el significado.
Ramas de plural por idioma de destino
Un plural ICU tiene una rama por categoría de plural CLDR de su idioma (ejemplos). Para next-intl y ARB, verbatra lee las categorías del idioma de destino de los datos CLDR integrados en Node.js:
- A un proveedor LLM se le piden exactamente esas ramas (cardinales para
plural, ordinales paraselectordinal). Las categorías viajan como datos, así que la frontera contra la inyección no cambia. - La puerta rechaza un
pluraloselectordinalal que le falta una rama obligatoria o que conserva una que el idioma no tiene, en todas las vías de escritura, y nombra cada rama incorrecta. - Las ramas de valor exacto como
=0deben sobrevivir todas, y una traducción puede añadir más. Las ramas deselectson claves de tu código, así que una traducción conserva exactamente las del origen. - Para un locale del que Node.js no tiene reglas de plural, solo se exige
other.
Un valor escrito antes de esta comprobación, como un plural francés sin many, se queda hasta que
cambie su origen; verbatra check --qa lo encuentra ya.
Paridad del marcado en línea
Una etiqueta en línea perdida o rota (un <b> en un bloque Trans de i18next, un <b>
escapado en un <string> de Android, un <a href> en gettext) rompe la representación, así que la
puerta compara nombres de etiqueta y de atributo como un multiconjunto:
- Se rechaza: una etiqueta quitada, inventada o renombrada; un conjunto distinto de nombres de
atributo (incluido añadir
dir); marcado desequilibrado o mal anidado; dos etiquetas fusionadas en una. - Se acepta: las mismas etiquetas en otro orden; un valor de atributo traducido como
titleoalt;<br>escrito como<br/>. - Valores vigilados: un atributo de URL debe conservar su esquema y su host (
/docspuede pasar a/de/docs, nunca ahttps://evil.example/docs), una URLjavascript:se rechaza, y valores comostyle, los manejadores de eventos o un<meta content>deben quedar exactamente como en el origen. - No se traduce: el contenido de
script,styley elementos parecidos debe volver sin cambios. Escapa esa etiqueta en la prosa (<script>) para traducir el texto que la rodea.
También se rechaza el marcado inventado en una cadena que no tenía ninguno, mientras que una
palabra entre corchetes angulares corriente como <Enter> se lee como texto. Las etiquetas que el
formato ya informa como placeholders se dejan a la comprobación de placeholders. Comentarios,
texto sin procesar y orígenes mal formados: consulta markup.
Señales de revisión
Una segunda capa, consultiva, marca los resultados sospechosos para una persona. Una señal nunca retiene una clave: el valor se escribe, se bloquea y entra en la cola de revisión.
| Motivo | Marca una traducción que |
|---|---|
LENGTH_ | es mucho más corta o más larga que su origen, ponderada por escritura |
MAX_ | supera el presupuesto maxLength de la clave |
EQUALS_ | es idéntica a su texto de origen |
GLOSSARY_ | omite la traducción de un término del glosario, o altera un término que no se traduce |
GLOSSARY_ | usa una forma que el glosario prohíbe |
INTEGRITY_ | conserva cada placeholder pero en otro orden |
PROVIDER_ | viene de un lote que el proveedor degradó, como una formalidad perdida |
FUZZY_ | se reutilizó de un origen parecido y editado |
FOREIGN_ | pierde o cambia un token con forma de placeholder que su formato no interpola, como {name} en i18next |
BIDI_ | deja abierto un control de dirección, o añade una anulación que invierte el texto |
DeepL, Google y LibreTranslate reciben ese token enmascarado y retienen un valor que no pueden
enmascarar ni restaurar (PLACEHOLDER_); la marca cubre los LLM y a las personas.
Los aciertos de caché y los valores compartidos se marcan como las traducciones nuevas. Las claves
marcadas aparecen como needsReview en el resumen de la ejecución, en las columnas de revisión del
libro de trabajo y en la página Review de Studio, hasta que una persona
aprueba, rechaza o reescribe el valor
(Decisiones de revisión).
El presupuesto de tokens
maxTokens cuenta los tokens de una ejecución en todas las llamadas y todos los locales;
budgetBehavior: "stop" retiene el resto de la ejecución en cuanto se superaría el techo, para
reintentarlo en la siguiente (reglas).
Lo que garantiza el presupuesto: el trabajo hecho antes del techo queda escrito y bloqueado, y nada
se queda a medio escribir. Lo que no: una petición en curso puede costar más de lo proyectado, el
techo acota una ejecución (no una sesión de watch), y no cubre las retraducciones desde Studio o
de agentes.
Los errores nunca filtran nada
Cuando una llamada al proveedor falla, el error bruto del SDK (que puede llevar cabeceras de la petición o credenciales) se descarta: nunca se registra ni se vuelve a lanzar. verbatra lanza en su lugar un error estructurado con un código estable y un mensaje fijo sin secretos. Cómo se ocultan las claves está en Tratamiento de datos.
Dónde lo ves
Todo lo anterior son datos en el resumen de la ejecución, por locale, y el fallo de un locale nunca detiene a los demás.
Valores confirmados
verbatra check --qa aplica la puerta y las señales de
revisión a los valores confirmados sin llamar al proveedor.
Relacionado
- Cómo funciona una ejecución: dónde está cada comprobación en la canalización.
- Tratamiento de datos y privacidad: qué sale de tu máquina.