@aigne/doc-smith 0.9.10 → 0.9.11-beta

package/agents/localize/translate-images/check-image-translation.mjs

@@ -0,0 +1,225 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as yamlParse } from "yaml";
+import { calculateFileHash, findImageFile } from "../../../utils/image-utils.mjs";
+
+/**
+ * Check if images need translation
+ * @param {Object} input - Input parameters
+ * @param {Array} input.slots - Image slot list (from scan-doc-images output)
+ * @param {string} input.targetLanguage - Target language
+ * @param {string} input.sourceLanguage - Source language (main language)
+ * @returns {Promise<Object>} - Check result
+ */
+export default async function checkImageTranslation(input) {
+  const { slots, targetLanguage, sourceLanguage } = input;
+
+  if (!slots || slots.length === 0) {
+    return {
+      success: true,
+      translationTasks: [],
+      message: "No images to check",
+    };
+  }
+
+  const translationTasks = [];
+  let sharedCount = 0;
+  let alreadyTranslatedCount = 0;
+  let needUpdateCount = 0;
+
+  for (const slot of slots) {
+    const { key, desc, assetDir, metaPath, exists } = slot;
+
+    // If image asset does not exist, skip
+    if (!exists) {
+      continue;
+    }
+
+    // Read .meta.yaml
+    let meta;
+    try {
+      const metaContent = await readFile(metaPath, "utf8");
+      meta = yamlParse(metaContent);
+    } catch (_error) {
+      // Failed to read .meta.yaml, skip
+      continue;
+    }
+
+    // 1. Check if it's a text-free shared image
+    if (meta.generation?.shared === true) {
+      sharedCount++;
+      continue; // Skip text-free images
+    }
+
+    // 2. Check if target language already exists
+    const languages = meta.languages || [];
+    const alreadyTranslated = languages.includes(targetLanguage);
+
+    // 3. Find source language image
+    const imagesDir = join(assetDir, "images");
+    const sourceImagePath = await findImageFile(imagesDir, sourceLanguage);
+    if (!sourceImagePath) {
+      // Source image does not exist, skip
+      continue;
+    }
+
+    // 4. Calculate source image hash
+    const sourceHash = await calculateFileHash(sourceImagePath);
+
+    // 5. Determine if translation is needed
+    let needsTranslation = false;
+    let reason = "";
+
+    if (!alreadyTranslated) {
+      // Target language version does not exist, needs translation
+      needsTranslation = true;
+      reason = "missing";
+    } else {
+      // Already translated, check if source image is updated
+      const translations = meta.translations || {};
+      const translationInfo = translations[targetLanguage];
+
+      if (!translationInfo || !translationInfo.sourceHash) {
+        // No source hash recorded, needs re-translation
+        needsTranslation = true;
+        reason = "no_hash";
+      } else if (translationInfo.sourceHash !== sourceHash) {
+        // Source image has been updated, needs re-translation
+        needsTranslation = true;
+        reason = "source_updated";
+        needUpdateCount++;
+      } else {
+        // Already translated and source image unchanged, skip
+        alreadyTranslatedCount++;
+      }
+    }
+
+    if (needsTranslation) {
+      // Get image aspect ratio (from meta or default)
+      const aspectRatio = meta.generation?.aspectRatio || "4:3";
+      const size = meta.generation?.size || "2K";
+
+      translationTasks.push({
+        key,
+        desc,
+        assetDir,
+        sourceImagePath,
+        sourceHash,
+        aspectRatio,
+        size,
+        reason,
+      });
+    }
+  }
+
+  return {
+    success: true,
+    translationTasks,
+    sourceLanguage,
+    targetLanguage,
+    stats: {
+      total: slots.length,
+      shared: sharedCount,
+      alreadyTranslated: alreadyTranslatedCount,
+      needUpdate: needUpdateCount,
+      needTranslation: translationTasks.length,
+    },
+    message:
+      `Checked ${slots.length} images: ` +
+      `${sharedCount} text-free shared images, ` +
+      `${alreadyTranslatedCount} already translated, ` +
+      `${translationTasks.length} need translation` +
+      (needUpdateCount > 0 ? ` (${needUpdateCount} need update)` : ""),
+  };
+}
+
+// Add description
+checkImageTranslation.description =
+  "Check if images need translation to target language. " +
+  "Skip text-free shared images, check source image hash to determine if re-translation is needed. " +
+  "Return list of image translation tasks.";
+
+// Define input schema
+checkImageTranslation.input_schema = {
+  type: "object",
+  required: ["slots", "targetLanguage", "sourceLanguage"],
+  properties: {
+    slots: {
+      type: "array",
+      description: "Image slot list (from scan-doc-images output)",
+      items: {
+        type: "object",
+        properties: {
+          key: { type: "string" },
+          desc: { type: "string" },
+          assetDir: { type: "string", nullable: true },
+          metaPath: { type: "string", nullable: true },
+          exists: { type: "boolean" },
+        },
+      },
+    },
+    targetLanguage: {
+      type: "string",
+      description: "Target language code",
+    },
+    sourceLanguage: {
+      type: "string",
+      description: "Source language code (main language)",
+    },
+  },
+};
+
+// Define output schema
+checkImageTranslation.output_schema = {
+  type: "object",
+  required: ["success"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "Whether operation succeeded",
+    },
+    translationTasks: {
+      type: "array",
+      description: "List of image translation tasks",
+      items: {
+        type: "object",
+        properties: {
+          key: { type: "string", description: "Image key" },
+          desc: { type: "string", description: "Image description" },
+          assetDir: { type: "string", description: "Image asset directory" },
+          sourceImagePath: { type: "string", description: "Source image file path" },
+          sourceHash: { type: "string", description: "Source image hash" },
+          aspectRatio: { type: "string", description: "Aspect ratio" },
+          size: { type: "string", description: "Image size" },
+          reason: {
+            type: "string",
+            description: "Translation reason (missing/no_hash/source_updated)",
+          },
+        },
+      },
+    },
+    sourceLanguage: {
+      type: "string",
+      description: "Source language code",
+    },
+    targetLanguage: {
+      type: "string",
+      description: "Target language code",
+    },
+    stats: {
+      type: "object",
+      description: "Statistics",
+      properties: {
+        total: { type: "number", description: "Total image count" },
+        shared: { type: "number", description: "Text-free shared image count" },
+        alreadyTranslated: { type: "number", description: "Already translated count" },
+        needUpdate: { type: "number", description: "Need update count" },
+        needTranslation: { type: "number", description: "Need translation count" },
+      },
+    },
+    message: {
+      type: "string",
+      description: "Operation result description",
+    },
+  },
+};

package/agents/localize/translate-images/detect-text/detect-and-update-shared.mjs

@@ -0,0 +1,148 @@
+import { readFile } from "node:fs/promises";
+import { join, basename } from "node:path";
+import { parse as yamlParse } from "yaml";
+import { findImageFile, getImageMimeType } from "../../../../utils/image-utils.mjs";
+
+/**
+ * Detect if image contains text and update .meta.yaml shared field
+ * @param {Object} input - Input parameters
+ * @param {Array} input.slots - Image slot list (from scan-doc-images output)
+ * @param {string} input.sourceLanguage - Source language (main language)
+ * @returns {Promise<Object>} - Processing result
+ */
+export default async function detectAndUpdateShared(input) {
+  const { slots, sourceLanguage } = input;
+
+  if (!slots || slots.length === 0 || !slots.some((s) => s.exists)) {
+    return {
+      success: true,
+      detectionTasks: [],
+      message: "No images to detect",
+    };
+  }
+
+  const detectionTasks = [];
+
+  for (const slot of slots) {
+    const { key, assetDir, metaPath, exists } = slot;
+
+    // If image asset does not exist, skip
+    if (!exists) {
+      continue;
+    }
+
+    // Read .meta.yaml
+    let meta;
+    try {
+      const metaContent = await readFile(metaPath, "utf8");
+      meta = yamlParse(metaContent);
+    } catch (_error) {
+      // Failed to read .meta.yaml, skip
+      continue;
+    }
+
+    // Check if shared field has already been detected
+    if (meta.generation?.shared === true) {
+      // Already detected, skip shared images
+      continue;
+    }
+
+    // Find main language image
+    const imagesDir = join(assetDir, "images");
+    const sourceImagePath = await findImageFile(imagesDir, sourceLanguage);
+
+    if (!sourceImagePath) {
+      // Main language image does not exist, skip
+      continue;
+    }
+
+    // Add to detection task list
+    detectionTasks.push({
+      key,
+      assetDir,
+      metaPath,
+      sourceImagePath,
+      // Prepare imageFile parameter (mediaFile format)
+      imageFile: [
+        {
+          type: "local",
+          path: sourceImagePath,
+          filename: basename(sourceImagePath),
+          mimeType: getImageMimeType(sourceImagePath),
+        },
+      ],
+    });
+  }
+
+  return {
+    success: true,
+    detectionTasks,
+    sourceLanguage,
+    message: `${detectionTasks.length} images need text detection`,
+  };
+}
+
+// Add description
+detectAndUpdateShared.description =
+  "Detect if images contain text, prepare batch detection tasks. " +
+  "Only detect images without generation.shared field set.";
+
+// Define input schema
+detectAndUpdateShared.input_schema = {
+  type: "object",
+  required: ["slots", "sourceLanguage"],
+  properties: {
+    slots: {
+      type: "array",
+      description: "Image slot list (from scan-doc-images output)",
+      items: {
+        type: "object",
+        properties: {
+          key: { type: "string" },
+          desc: { type: "string" },
+          assetDir: { type: "string", nullable: true },
+          metaPath: { type: "string", nullable: true },
+          exists: { type: "boolean" },
+        },
+      },
+    },
+    sourceLanguage: {
+      type: "string",
+      description: "Source language code (main language)",
+    },
+  },
+};
+
+// Define output schema
+detectAndUpdateShared.output_schema = {
+  type: "object",
+  required: ["success"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "Whether operation succeeded",
+    },
+    detectionTasks: {
+      type: "array",
+      description: "List of image detection tasks",
+      items: {
+        type: "object",
+        properties: {
+          key: { type: "string", description: "Image key" },
+          assetDir: { type: "string", description: "Image asset directory" },
+          metaPath: { type: "string", description: ".meta.yaml file path" },
+          sourceImagePath: { type: "string", description: "Main language image path" },
+          imageFile: { type: "array", description: "imageFile mediaFile object array" },
+        },
+      },
+    },
+    sourceLanguage: {
+      type: "string",
+      description: "Source language code",
+    },
+    message: {
+      type: "string",
+      description: "Operation result description",
+    },
+  },
+};

package/agents/localize/translate-images/detect-text/detect-image-text.yaml

@@ -0,0 +1,44 @@
+name: detectImageText
+description: Detect if image contains text content
+model: gemini-2.5-flash
+modalities: ["text", "image"]
+instructions:
+  - role: system
+    url: ./prompts/detect-image-text-system.md
+  - role: user
+    url: ./prompts/detect-image-text-user.md
+input_file_key: imageFile
+include_input_in_output: true
+input_schema:
+  type: object
+  properties:
+    key:
+      type: string
+      description: Image key
+    imageFile:
+      type: array
+      description: Array of mediaFile objects for image files
+      items:
+        type: object
+        properties:
+          type:
+            type: string
+            description: File type, should be "local"
+          path:
+            type: string
+            description: Absolute path to the image file
+          filename:
+            type: string
+            description: Image filename
+          mimeType:
+            type: string
+            description: MIME type (e.g., "image/png", "image/jpeg")
+  required:
+    - key
+    - imageFile
+output_schema:
+  type: object
+  properties:
+    hasText:
+      type: boolean
+      description: Whether the image contains text

package/agents/localize/translate-images/detect-text/detect-images-text.yaml

@@ -0,0 +1,21 @@
+type: team
+name: detectImagesText
+description: Detect if images contain text and update shared field
+skills:
+  - url: ./detect-and-update-shared.mjs # Prepare detection tasks
+  - type: team
+    name: processTextDetections # Batch detect image text
+    skills:
+      - type: team
+        name: detectSingleImageText
+        description: Detect if a single image contains text and save result
+        skills:
+          - url: ./detect-image-text.yaml # Detect image text
+          - url: ./save-text-detection.mjs # Save detection result
+        mode: sequential
+        include_input_in_output: true
+
+    iterate_on: detectionTasks
+    concurrency: 1
+mode: sequential
+include_input_in_output: true

package/agents/localize/translate-images/detect-text/prompts/detect-image-text-system.md

@@ -0,0 +1,43 @@
+You are an AI assistant specialized in analyzing diagram images to detect the presence of text content.
+
+# YOUR TASK
+
+Analyze the provided diagram image and determine whether it contains any text or textual labels.
+
+# WHAT COUNTS AS TEXT
+
+Text includes:
+- ✅ Words, labels, or text annotations in any language
+- ✅ Abbreviations, acronyms, or code snippets
+- ✅ Numbers used as labels or identifiers (e.g., "Step 1", "v2.0")
+- ✅ Technical terms or variable names
+- ✅ Arrows or connectors with text labels
+
+# WHAT DOES NOT COUNT AS TEXT
+
+The following should NOT be considered as text:
+- ❌ Pure icons or symbols without text
+- ❌ Standalone numbers used decoratively (not as labels)
+- ❌ Colors, shapes, or visual patterns
+- ❌ Logos that are purely graphical
+
+# OUTPUT FORMAT
+
+You must respond with ONLY one of these two values:
+- `true` - if the image contains ANY text content
+- `false` - if the image contains NO text (pure visual diagram)
+
+# IMPORTANT RULES
+
+1. Be strict: even a single word or label means the image has text → return `true`
+2. Ignore watermarks or metadata that are not part of the diagram content
+3. Focus on the actual diagram content, not borders or backgrounds
+4. Your response must be ONLY `true` or `false`, nothing else
+
+# EXAMPLES
+
+**Image with node labels like "User", "API", "Database"** → `true`
+**Flowchart with text like "Start", "Process", "End"** → `true`
+**Architecture diagram with component names** → `true`
+**Pure icon-based diagram with no text labels** → `false`
+**Diagram with only arrows and shapes, no text** → `false`

package/agents/localize/translate-images/detect-text/prompts/detect-image-text-user.md

@@ -0,0 +1,14 @@
+# Text Detection Task
+
+Analyze the provided diagram image and determine if it contains any text content.
+
+**Image Key:** {{ key }}
+
+[The diagram image is provided as input to the model]
+
+**Your task:**
+1. Carefully examine the entire image
+2. Look for any words, labels, text annotations, or textual content
+3. Respond with ONLY `true` (has text) or `false` (no text)
+
+**Response:** (true or false only)

package/agents/localize/translate-images/detect-text/save-text-detection.mjs

@@ -0,0 +1,105 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import { ERROR_CODES } from "../../../../utils/agent-constants.mjs";
+
+/**
+ * Save text detection result to .meta.yaml
+ * @param {Object} input - Input parameters
+ * @param {string} input.key - Image key
+ * @param {string} input.metaPath - .meta.yaml file path
+ * @param {boolean} input.hasText - Whether contains text (from detect-image-text.yaml output)
+ * @returns {Promise<Object>} - Operation result
+ */
+export default async function saveTextDetection(input) {
+  const { key, metaPath, hasText } = input;
+
+  try {
+    // Read .meta.yaml
+    const metaContent = await readFile(metaPath, "utf8");
+    const meta = yamlParse(metaContent);
+
+    // Update generation.shared field
+    if (!meta.generation) {
+      meta.generation = {};
+    }
+
+    // shared = !hasText (no text means shared)
+    meta.generation.shared = !hasText;
+
+    // Save updated .meta.yaml
+    const updatedMetaContent = yamlStringify(meta);
+    await writeFile(metaPath, updatedMetaContent, "utf8");
+
+    return {
+      success: true,
+      key,
+      hasText,
+      shared: !hasText,
+      message: `Updated shared field: ${key} (hasText=${hasText}, shared=${!hasText})`,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: ERROR_CODES.SAVE_ERROR,
+      message: `Error saving text detection result: ${error.message}`,
+      key,
+    };
+  }
+}
+
+// Add description
+saveTextDetection.description =
+  "Save image text detection result to .meta.yaml file. " +
+  "Update generation.shared field based on detection result: text-free images shared=true, images with text shared=false.";
+
+// Define input schema
+saveTextDetection.input_schema = {
+  type: "object",
+  required: ["key", "metaPath", "hasText"],
+  properties: {
+    key: {
+      type: "string",
+      description: "Image key",
+    },
+    metaPath: {
+      type: "string",
+      description: ".meta.yaml file path",
+    },
+    hasText: {
+      type: "boolean",
+      description: "Whether image contains text (from detect-image-text.yaml output)",
+    },
+  },
+};
+
+// Define output schema
+saveTextDetection.output_schema = {
+  type: "object",
+  required: ["success"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "Whether operation succeeded",
+    },
+    key: {
+      type: "string",
+      description: "Image key",
+    },
+    hasText: {
+      type: "boolean",
+      description: "Whether image contains text (present on success)",
+    },
+    shared: {
+      type: "boolean",
+      description: "Whether it is a shared image (present on success)",
+    },
+    message: {
+      type: "string",
+      description: "Operation result description",
+    },
+    error: {
+      type: "string",
+      description: "Error code (present on failure)",
+    },
+  },
+};