localization-packager

localization-packager — habilidad para agente

Propósito

Ir a múltiples idiomas es un problema de empaquetado en torno a la traducción: cada idioma debe tener los mismos 4 archivos, y lo que se devuelve necesita ser revisado: presencia, longitud del título, capacidad de análisis de subtítulos, recuento de señales, desviación temporal de señales. Esta herramienta crea el plan, la hoja de entrega y la verificación estructural a partir de un ÚNICO archivo JSON de proyecto. Solo utiliza la biblioteca estándar de Python; funciona localmente.

El núcleo de honestidad de esta herramienta: no traduce nada y no juzga ninguna traducción. check verifica la estructura — presencia de archivos, capacidad de análisis, longitudes, tiempos. Un paquete COMPLETO puede contener una mala traducción; solo un lector del idioma puede juzgarlo. Nunca reportes un veredicto COMPLETO como "la traducción es buena" o "lista para publicar" — es "estructuralmente completa, lista para una revisión de calidad humana".

Cuándo usar / no usar

Usa cuando:

• Un video o aplicación se va a lanzar en idiomas adicionales y el trabajo se entrega a traductores: manifest para el plan, sheet para la entrega, check como puerta de lo que se devuelve.
• Un pipeline necesita un sí/no por idioma: check con código de salida 0 = cada idioma estructuralmente completo; código 1 = la salida nombra cada idioma incompleto y sus problemas exactos.

NO uses cuando:

• Necesitas la traducción en sí — esta herramienta no llama a ninguna API de traducción y no produce texto traducido. La columna de destino en blanco es para un traductor humano.
• Necesitas garantía de calidad de traducción — no hay corrección ortográfica, retrotraducción ni puntuación de calidad aquí, por diseño.
• Necesitas activos a nivel de canal (banners, pantallas finales) o metadatos de tienda de aplicaciones más allá de los 4 archivos empaquetados — fuera del alcance, deliberadamente.

Comandos

Cada comando toma el archivo de proyecto como argumento posicional y soporta --json.

# El plan de entrega por idioma
python3 src/localization_packager.py manifest PROYECTO.json

# Hoja de trabajo para el traductor (Markdown por defecto, o CSV;
# un idioma o todos los destinos)
python3 src/localization_packager.py sheet PROYECTO.json \
    [--format md|csv] [--language CODIGO]

# Validar un paquete completo (código de salida 1 cuando algún idioma está
# incompleto; --root cuando las carpetas están en otro lugar)
python3 src/localization_packager.py check PROYECTO.json \
    [--root DIRECTORIO]

Campos del proyecto: project (nombre), source_language, source_title, source_description, source_thumbnail_text, source_subtitles (ruta al SRT de origen, relativa al archivo de proyecto), targets — lista de {"language", "name", "translator"?}; los códigos de idioma deben ser únicos. El archivo se valida en cada lectura; los problemas estructurales (campos faltantes, un idioma duplicado, un SRT de origen faltante o no analizable) son errores con código de salida 2 que nombran el problema.

Estructura del paquete: una carpeta por código de idioma que contiene title.txt, description.txt, subtitles.srt, thumbnail.txt.

Reglas de verificación (exactas)

Por idioma, en orden de archivos:

• title.txt — si falta o está vacío es un problema; si el texto recortado tiene más de 100 caracteres es un problema (100 pasa, 101 marca). Los caracteres son puntos de código Unicode.
• description.txt — si falta o está vacío es un problema.
• subtitles.srt — si falta o está vacío es un problema; si el texto no se analiza como SRT es un problema (se cita el error de análisis); si el recuento de señales difiere del original en más del 25% del recuento de origen es un problema (una diferencia exacta del 25% pasa, y una diferencia menor se anota, no se marca); la desviación máxima de inicio por posición superior a 2000 ms es un problema nombrando la señal y la desviación (exactamente 2000 ms pasa; 2100 ms marca como "2.1s"). La desviación empareja señales por posición sobre las primeras min(origen, destino) señales, solo los inicios.
• thumbnail.txt — si falta o está vacío es un problema.

Veredictos: un idioma sin problemas es COMPLETO, de lo contrario INCOMPLETO con el recuento de problemas. check sale con código 0 solo cuando cada idioma está COMPLETO.

Esquema JSON de salida (--json)

Campos comunes: tool ("localization-packager"), version, command, project_file (nombre del archivo), project.

manifest: source_language, source_title, source_cues, languages — cada {language, name, translator, folder, files} donde files son los 4 archivos requeridos, cada {file, what, source_fact}. check: source_cues, root, languages — cada {language, name, translator, status ("complete" | "incomplete"), items, problems} donde items son los 4 resultados por archivo {file, ok, detail} y problems lista los detalles que fallan — además de complete, total, all_complete, y un note que reitera que la verificación es solo estructural. sheet: sheets — uno por idioma destino, cada {language, name, translator, rows}; rows es {n, item, timing, source, target} — 3 filas de cadena (título, descripción, miniatura) luego una fila por señal de origen (item = "cue N", timing = SRT "start --> end"); target siempre es "" — la columna en blanco que llena el traductor.

En caso de error, stdout es un solo objeto: {"error": "<mensaje>"} con código de salida 2 — incluidos errores de uso de argparse en modo --json. Nunca texto plano, nunca un traceback.

Códigos de salida

• 0 — el comando se ejecutó correctamente; para check, cada idioma está COMPLETO.
• 1 — un hallazgo: check encontró al menos un idioma incompleto. No es un bloqueo — la lista de problemas es la lista de correcciones para enviar de vuelta al traductor.
• 2 — ERROR: el archivo de proyecto no existe o no es JSON válido, falta un campo obligatorio, un idioma destino duplicado, los subtítulos de origen faltan o no se pueden analizar, un --language desconocido, una bandera no válida. No se pueden citar hechos de salida de una ejecución fallida.

Límites y reglas de honestidad que el agente debe respetar

• COMPLETO significa estructuralmente completo — nada más. Nunca lo eleves a "la traducción es correcta", "buena" o "publicable". El lanzamiento aún necesita un lector del idioma; dilo al reportar un paquete COMPLETO.
• INCOMPLETO es una lista de correcciones, no un fracaso del traductor. Reporta los problemas exactos (archivo, número de señal, desviación, recuento de caracteres) — están escritos para ser reenviados tal cual.
• La herramienta no produce texto traducido. La columna de destino de una hoja está en blanco a propósito. Nunca la llenes con traducción automática y presentes el resultado como salida de esta herramienta, y nunca afirmes que un paquete de idioma existe hasta que sus 4 archivos estén realmente en el disco y check se haya ejecutado sobre ellos.
• Las marcas de desviación son posicionales. Si un traductor divide una señal en dos, las señales posteriores cambian de posición y pueden marcarse; la nota de recuento de señales en la salida da el contexto. Reporta ambos hechos, no solo la marca.
• Solo local: la herramienta lee solo el archivo de proyecto, el SRT de origen y las carpetas de paquete nombradas en la línea de comandos, y no envía nada a ningún lado.