Manual de ZoneTraductor

Guía de la versión actual: del primer proyecto al XML traducido.

ZoneTraductor permite traducir las cadenas de archivos XML de mods de S.T.A.L.K.E.R. y de otros proyectos con XML. Esta guía va desde la preparación de los archivos hasta el XML que podrás colocar en el mod. Puedes trabajar manualmente sin cuenta de DeepL ni DeepSeek; esas API son opcionales.

Para quienes ya tienen XML de un mod y quieren traducirlos, revisar términos y guardar un archivo listo para copiar al juego.

Pendiente: las capturas del programa y la última versión de ZoneTraductor todavía no están publicadas. Este manual y la descarga quedan listos en unas horas.

Ruta rápida: del mod al XML traducido

1. Deja el programa en una carpeta donde puedas escribir y, si dispones de un corpus compatible, coloca corpus/ junto al ejecutable.
2. En Proyecto → Nuevo proyecto, elige Modo STALKER o Modo Genérico, una carpeta de origen y otra de trabajo.
3. En el engranaje, confirma los idiomas y añade las claves de los servicios que vayas a utilizar.
4. Abre un XML, traduce una cadena y comprueba el texto, los códigos de formato y la vista previa.
5. Marca como Revisada cada traducción aprobada. Repite con otras cadenas o utiliza Lote para generar propuestas con DeepSeek.
6. Pulsa Guardar para crear el XML de salida. Comprueba su ubicación en la carpeta de trabajo antes de copiarlo al mod.

Dos guardados distintos:Guardar proyecto conserva el avance en project.ztproj; Guardar escribe el XML que se usa en el mod. El autoguardado del proyecto tampoco sustituye el segundo paso.

1. Preparar el programa y los archivos

ZoneTraductor funciona en Windows 10 u 11 de 64 bits y necesita Microsoft Edge WebView2 Runtime. Mantén zonetraductor.exe y WebView2Loader.dll juntos; la DLL no instala el Runtime. Descomprime el paquete en una carpeta donde tu usuario pueda escribir.

En la carpeta del programa están prompt.txt y configuracion.json. Al usarlo pueden aparecer cache-traducciones.json y memoria-traducciones.json. Conserva esos archivos si quieres mantener ajustes, respuestas reutilizables y traducciones aprobadas. Los proyectos y los XML editados se guardan en la carpeta de trabajo que elijas, no en la carpeta del EXE.

Si tienes un corpus compatible, copia la carpeta completa como zonetraductor/corpus/. Es opcional: sin ella puedes editar y usar DeepL o DeepSeek. El programa comprueba el manifiesto y las sumas de los archivos antes de usarlo.

Las claves de API quedan protegidas para el usuario de Windows que las guardó. Al mover el programa a otra cuenta o equipo, introdúcelas de nuevo.

Antes de comenzar: prepara una carpeta con los XML originales y otra carpeta vacía o destinada al trabajo. Si los textos están empaquetados en .db o .dbx, extráelos primero con las herramientas adecuadas para ese mod; ZoneTraductor trabaja con XML accesibles.

2. Crear o abrir un proyecto

Abre Proyecto → Nuevo proyecto. El programa te pide el tipo de proyecto:

• Modo STALKER: busca mods con la estructura gamedata/configs/text/idioma/archivo.xml y permite elegir un mod y sus archivos de idioma.
• Modo Genérico: copia los XML de una carpeta y sus subcarpetas al espacio de trabajo. Úsalo cuando la estructura no sigue la anterior.

El tipo describe la estructura de los archivos. No elige un juego oficial ni decide qué vocabulario necesita el mod.

Después, selecciona la carpeta de origen y una carpeta de trabajo distinta. ZoneTraductor copia al espacio de trabajo los XML que va a manejar, de modo que la carpeta de origen queda como referencia. Cuando finalice, elige un mod y un XML en modo STALKER, o un XML de la lista en modo Genérico.

El proyecto se guarda como project.ztproj en la raíz de la carpeta de trabajo. Para seguir otro día, abre Proyecto → Abrir proyecto existente y selecciona ese archivo. Proyecto → Cerrar proyecto descarga el proyecto actual.

Si ya tenías traducciones en XML genéricos

En un proyecto genérico, las traducciones que ya estén escritas en los XML del espacio de trabajo no se registran automáticamente como avance del proyecto. Abre el XML y, en Configuración → Modo genérico, usa Importar traducciones del XML actual si quieres incorporarlas a project.ztproj y a los contadores. Revisa el resultado antes de seguir.

3. Reconocer la ventana principal

• A la izquierda están el mod, cuando aplica, y los XML disponibles. Sus contadores ayudan a localizar archivos pendientes.
• Texto origen muestra la cadena seleccionada y no se edita. Traducción es el campo de destino.
• La fila de botones reúne Copiar, Pegar, Guardar, Formatear texto, Traducir, Traducir IA, Lote, Versiones, Exportar, Importar y Estadísticas.
• Debajo de la traducción aparecen el estado de la cadena, Deshacer, Rehacer, el modo de esa cadena y las sugerencias de memoria.
• Vista previa (formato del juego) representa colores conocidos y saltos de línea. Contexto en el archivo enseña cadenas cercanas; la cercanía en el XML no garantiza que formen un mismo diálogo.
• Glosario muestra los términos que coinciden, conflictos y decisiones del proyecto.
• Al final están Buscar por texto o ID, el filtro, Anterior, Siguiente, el contador y el indicador de guardado del proyecto.

La búsqueda y el filtro afectan a las cadenas por las que navegas. Por ejemplo, selecciona Propuestas para revisar salidas automáticas o Con marcadores alterados para localizar posibles errores de formato. Escape limpia la búsqueda y vuelve al filtro Todas.

Estados de una cadena

No marques una propuesta como revisada solo porque la API respondió sin error: el estado representa una decisión editorial.

4. Configurar idiomas, DeepL y DeepSeek

Abre el engranaje de la cabecera. Elige idioma de interfaz, idioma de origen y destino, y pulsa Guardar dentro del diálogo. Esos idiomas se usan en las peticiones y ayudan a ubicar la salida en modo STALKER.

Para DeepL, introduce su clave y usa Verificar API. Comprobar los idiomas consulta los idiomas que admite ese servicio; si la consulta falla, la aplicación usa su lista local y lo indica. El botón Traducir utiliza DeepL.

Para DeepSeek, introduce su clave y elige Flash o Pro. El botón Traducir IA utiliza ese modelo; la respuesta indica cuál respondió realmente. Lote también trabaja con DeepSeek. La elección de modelo puede cambiar el costo del proveedor.

El modo de traducción guía a DeepSeek. Editorial permite adaptar orden y registro al español latinoamericano natural; Fidelidad pide conservar más la estructura y las repeticiones del original. Puedes cambiar el modo general aquí y fijar una excepción para una cadena con el selector Modo del proyecto / Editorial / Fidelidad del editor. Vuelve a Modo del proyecto para quitarla.

Abrir archivo de prompt para editar abre prompt.txt. Los cambios se aplican a peticiones posteriores de DeepSeek. Si el prompt personalizado contiene un glosario fijo antiguo, revisa el aviso: sus instrucciones podrían contradecir el corpus o las preferencias del proyecto.

5. Traducir y revisar una cadena

1. Selecciona un XML y usa Anterior/Siguiente o busca un texto o ID.
2. Lee el Texto origen y, si hace falta, el Contexto en el archivo.
3. Escribe la traducción, usa Copiar/Pegar, pulsa Traducir para DeepL o Traducir IA para DeepSeek.
4. Revisa nombres propios, términos del mod, signos, códigos y Vista previa. Si la respuesta no sirve, edítala en el campo de destino.
5. Pulsa Revisada cuando la apruebes. Si debe quedar vacía, utiliza Vacía a propósito.
6. Continúa con la siguiente cadena. Deshacer y Rehacer sirven para corregir cambios en la sesión.

El área bajo los botones informa si se consultó la API, se usó caché o hubo un error. Cancelar petición detiene una solicitud activa. Una respuesta automática queda como propuesta, incluso si se recuperó de la caché.

Conservar códigos y comprobar la vista previa

No traduzcas ni borres marcadores como %c[d_orange], %c[default], %s, %d, \n o etiquetas XML. Algunos se sustituyen dentro del juego; otros controlan color o saltos de línea. La vista previa muestra los colores conocidos, pero debes comparar el origen y el destino para comprobar que los códigos sigan presentes y en un lugar lógico.

El filtro Con marcadores alterados busca diferencias en esos códigos y escapes. Úsalo antes de guardar el XML; revisa también signos, espacios y nombres propios que no pueda detectar automáticamente.

6. Usar el corpus y el glosario del proyecto

Cuando corpus/ está junto al EXE, ZoneTraductor comprueba manifiesto.json y las sumas declaradas. En Configuración → Corpus terminológico puedes leer su estado y pulsar Volver a comprobar después de copiar o reemplazar la carpeta. Si no es válido, el programa sigue permitiendo editar y usar las API sin ese corpus.

El panel Glosario muestra equivalencias pertinentes para la cadena abierta. DeepSeek las recibe como referencia contextual. DeepL protege las coincidencias resueltas cuando traduce al español latinoamericano. Si existen equivalencias incompatibles, el panel avisa y no fuerza una elección.

Para fijar una decisión propia del mod, escribe Término original del mod y Traducción y pulsa Añadir al proyecto. Esa preferencia queda en project.ztproj, prevalece sobre el corpus y no cambia los archivos compartidos. Úsala para nombres o términos que deban mantenerse de manera consistente en ese proyecto.

Hay términos que dependen de la frase. Una palabra como fault puede hablar de culpa o de una anomalía; una equivalencia aislada no resuelve ese contexto. Lee la oración, consulta las cadenas cercanas y corrige manualmente cuando sea necesario. Las entradas del corpus clasificadas como interfaz o lugares solo se imponen automáticamente si coinciden con la cadena completa, para evitar que un nombre o una etiqueta se aplique dentro de un diálogo diferente.

7. Entender la caché y la memoria

Caché de API: guarda la respuesta recibida de DeepL o DeepSeek. Al repetir una petición equivalente —mismo texto, proveedor o modelo, idiomas, prompt, modo y referencias pertinentes— puede reutilizarla sin otra llamada. Se controla con Reutilizar respuestas ya traducidas en Configuración y se vacía desde Estadísticas. Una respuesta de caché sigue necesitando revisión.

Memoria de traducciones: recuerda las cadenas marcadas como Revisada. Si encuentra un original igual o parecido, muestra una sugerencia bajo el editor; puedes elegirla y volver a revisarla. No se aplica sola. Su estado y el botón Vaciar la memoria están en Configuración.

Cambiar el texto o algún elemento de la petición puede evitar una coincidencia de caché. Si DeepSeek repite una respuesta que quieres volver a consultar, comprueba primero si el estado indica caché.

8. Traducir varias cadenas con Lote

Lote genera propuestas con DeepSeek para el XML seleccionado. Antes de empezar, guarda cualquier ajuste de idioma, modelo o modo que quieras usar.

1. En Qué traducir, selecciona Las cadenas sin traducir del archivo, Todas las cadenas del archivo o Solo las que pasan el filtro actual. La tercera opción respeta la búsqueda y el filtro visibles.
2. Activa No repetir las cadenas ya traducidas si quieres omitirlas.
3. Si necesitas limitar el trabajo, indica Máximo de cadenas y Máximo de tokens estimados. 0 significa sin límite.
4. Pulsa Calcular y lee la estimación de peticiones, caracteres y tokens.
5. Pulsa Empezar. Puedes pausar, reanudar o cancelar. Si hubo errores, usa Reintentar las fallidas.
6. Revisa las propuestas y el consumo observado al terminar. Después marca como revisadas las traducciones aprobadas y pulsa Guardar para escribir el XML.

El lote protege las cadenas Revisadas y Vacías a propósito. Las respuestas reutilizadas de caché no hacen otra petición. La estimación es aproximada; el consumo observado procede de la respuesta del proveedor. El proyecto se guarda al concluir el lote, pero el XML de salida requiere Guardar.

9. Revisar cambios entre versiones del XML

Si actualizaste los XML de un mod, abre el archivo y pulsa Versiones. El informe compara los IDs y los textos originales que recuerda el proyecto con el contenido actual. Distingue cadenas nuevas, modificadas, eliminadas y sin cambios.

Ver las modificadas aplica el filtro correspondiente en el editor. Revisa esas traducciones porque pueden haber quedado desfasadas. Las cadenas eliminadas ya no tienen destino en el XML actual. El informe no borra ni reescribe traducciones por sí mismo.

10. Guardar el proyecto y el XML de salida

Mientras editas, el proyecto intenta guardar el avance automáticamente; el indicador inferior muestra Cambios pendientes, Guardando proyecto… o Proyecto guardado. También puedes usar Proyecto → Guardar proyecto. Ese archivo permite retomar traducciones, estados y preferencias: no es el XML que instalarás.

El botón Guardar y Proyecto → Guardar archivo actual escriben el XML del archivo abierto:

• En Modo STALKER, la salida queda en la carpeta del idioma de destino dentro del espacio de trabajo, con la estructura del mod.
• En Modo Genérico, se actualiza la copia del XML en el espacio de trabajo.
• Se conserva la estructura y la codificación reconocida, incluido el BOM cuando corresponde. Si un carácter no puede representarse en esa codificación, se muestra un error y el archivo no se guarda.
• Cuando existe un destino anterior, el programa crea un respaldo .bak junto al archivo que reemplaza.

Tras guardar, abre la carpeta de trabajo y comprueba el XML resultante. Copia los archivos de destino a la ubicación que usa el mod solo cuando hayas terminado la revisión. ZoneTraductor no instala el mod ni cambia el idioma del juego.

11. Formatear texto y resolver inclusiones XML

Formatear texto trabaja sobre el XML seleccionado. Repara y normaliza estructuras de texto; puede retirar comentarios vacíos. Cuando hace cambios, crea un respaldo y vuelve a cargar las cadenas. Es una acción sobre el archivo, a diferencia de Vista previa, que solo representa el texto en pantalla.

Los #include de estilo C admitidos se resuelven al abrir el XML y se incorporan al resultado al guardarlo. Si falta un archivo incluido, hay un ciclo o la ruta sale de la estructura permitida, el programa avisa. Corrige el problema en los archivos del espacio de trabajo antes de continuar.

12. Exportar e importar CSV o XLIFF

Exportar saca las cadenas visibles del XML activo a CSV o XLIFF. Si hay una búsqueda o filtro activo, solo salen las cadenas que pasan ese filtro. El CSV incluye columnas como archivo, ID, original, traducción, estado y contexto; sirve para revisar o trabajar con otra herramienta.

Importar lee CSV o XLIFF y presenta un resumen antes de aplicar cambios. Compara las filas con las cadenas del proyecto por archivo e identificador, indica las que puede aplicar, las desconocidas, las ilegibles y los conflictos. Si ya hay otra traducción, elige Conservar la que hay en el proyecto o Quedarme con la del archivo. Pulsa Aplicar solo después de revisar el resumen; los cambios entran al historial y puedes deshacerlos.

Si exportaste una selección, no esperes encontrar en ese archivo las demás cadenas del XML. Comprueba el filtro antes de crear el intercambio.

13. Leer estadísticas

Estadísticas resume el avance y los estados del proyecto, el consumo registrado de DeepSeek y la situación de la caché. El consumo de tokens que informa el proveedor no equivale por sí solo a un costo monetario universal. Desde esta ventana puedes Vaciar la caché si necesitas descartar respuestas anteriores.

14. Atajos de teclado

15. Problemas habituales

Al comunicar un fallo, indica el mensaje de error, el nombre del XML, el ID de la cadena y los pasos que lo reprodujeron. No compartas claves de API.

Por 91v (Alberto Trejo) · Manual de uso de ZoneTraductor · Última revisión: 1 de octubre de 2026