@aigne/doc-smith 0.9.10 → 0.9.11-beta

package/agents/localize/translate-images/prepare-image-input.mjs

@@ -0,0 +1,124 @@
+import { basename } from "node:path";
+import { ERROR_CODES } from "../../../utils/agent-constants.mjs";
+
+/**
+ * Prepare input parameters for image translation
+ * @param {Object} input - Input parameters (single task from translationTasks)
+ * @param {string} input.key - Image key
+ * @param {string} input.desc - Image description
+ * @param {string} input.assetDir - Image asset directory
+ * @param {string} input.sourceImagePath - Source image path
+ * @param {string} input.sourceHash - Source image hash
+ * @param {string} input.aspectRatio - Aspect ratio
+ * @param {string} input.size - Image size
+ * @param {string} input.sourceLanguage - Source language (from parent)
+ * @param {string} input.targetLanguage - Target language (from parent)
+ * @returns {Promise<Object>} - Prepared input parameters
+ */
+export default async function prepareImageInput(input) {
+  const {
+    key,
+    desc,
+    assetDir,
+    sourceImagePath,
+    sourceHash,
+    aspectRatio,
+    size,
+    sourceLanguage,
+    targetLanguage,
+  } = input;
+
+  try {
+    // Prepare existingImage parameter (mediaFile format)
+    const existingImage = [
+      {
+        type: "local",
+        path: sourceImagePath,
+        filename: basename(sourceImagePath),
+        mimeType: sourceImagePath.endsWith(".png") ? "image/png" : "image/jpeg",
+      },
+    ];
+
+    return {
+      success: true,
+      // Parameters for translate-image.yaml
+      existingImage,
+      desc,
+      sourceLanguage,
+      targetLocale: targetLanguage,
+      ratio: aspectRatio,
+      size,
+      // Parameters for save-image-translation.mjs
+      key,
+      assetDir,
+      targetLanguage,
+      sourceHash,
+      message: `Preparing image translation: ${key} (${sourceLanguage} → ${targetLanguage})`,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: ERROR_CODES.UNEXPECTED_ERROR,
+      message: `Error preparing image translation input: ${error.message}`,
+      key,
+    };
+  }
+}
+
+// Add description
+prepareImageInput.description =
+  "Prepare input parameters for image translation, converting translation tasks to the format required by translate-image.yaml. " +
+  "Build sourceImage mediaFile object array and pass necessary parameters.";
+
+// Define input schema
+prepareImageInput.input_schema = {
+  type: "object",
+  required: [
+    "key",
+    "desc",
+    "assetDir",
+    "sourceImagePath",
+    "sourceHash",
+    "aspectRatio",
+    "size",
+    "sourceLanguage",
+    "targetLanguage",
+  ],
+  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 path" },
+    sourceHash: { type: "string", description: "Source image hash" },
+    aspectRatio: { type: "string", description: "Aspect ratio" },
+    size: { type: "string", description: "Image size" },
+    sourceLanguage: { type: "string", description: "Source language code" },
+    targetLanguage: { type: "string", description: "Target language code" },
+    reason: { type: "string", description: "Translation reason" },
+  },
+};
+
+// Define output schema
+prepareImageInput.output_schema = {
+  type: "object",
+  required: ["success"],
+  properties: {
+    success: { type: "boolean", description: "Whether operation succeeded" },
+    existingImage: {
+      type: "array",
+      description: "Source image mediaFile object array",
+      items: { type: "object" },
+    },
+    desc: { type: "string", description: "Image description" },
+    sourceLanguage: { type: "string", description: "Source language code" },
+    targetLocale: { type: "string", description: "Target language code" },
+    ratio: { type: "string", description: "Aspect ratio" },
+    size: { type: "string", description: "Image size" },
+    key: { type: "string", description: "Image key" },
+    assetDir: { type: "string", description: "Image asset directory" },
+    targetLanguage: { type: "string", description: "Target language code" },
+    sourceHash: { type: "string", description: "Source image hash" },
+    message: { type: "string", description: "Operation result description" },
+    error: { type: "string", description: "Error code (present on failure)" },
+  },
+};

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

@@ -0,0 +1,172 @@
+import { readFile, writeFile, copyFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import { ERROR_CODES } from "../../../utils/agent-constants.mjs";
+import { getExtensionFromMimeType } from "../../../utils/image-utils.mjs";
+
+/**
+ * Save translated image and update .meta.yaml
+ * @param {Object} input - Input parameters
+ * @param {string} input.key - Image key
+ * @param {string} input.assetDir - Image asset directory
+ * @param {string} input.targetLanguage - Target language
+ * @param {string} input.sourceHash - Source image hash
+ * @param {Array} input.images - Image translation result (from translate-image.yaml)
+ * @returns {Promise<Object>} - Operation result
+ */
+export default async function saveImageTranslation(input) {
+  const { key, assetDir, targetLanguage, sourceHash, images } = input;
+
+  try {
+    // 1. Validate image data
+    // Format: [{ filename, mimeType, type, path }, ...]
+    if (!images || !Array.isArray(images) || images.length === 0) {
+      return {
+        success: false,
+        key,
+        error: "GENERATION_FAILED",
+        message: "Translated image data not found",
+        suggestion:
+          "Check the output format of the image translation agent, expecting images array",
+        availableKeys: Object.keys(input),
+      };
+    }
+
+    // Use the first image
+    const imageInfo = images[0];
+    if (!imageInfo.path) {
+      return {
+        success: false,
+        key,
+        error: "INVALID_IMAGE_DATA",
+        message: "Image data missing path field",
+        suggestion: "Check the images format returned by the image translation agent",
+      };
+    }
+
+    // 2. Determine target file path
+    const ext = getExtensionFromMimeType(imageInfo.mimeType);
+    const targetImagePath = join(assetDir, "images", `${targetLanguage}.${ext}`);
+
+    // Ensure directory exists
+    await mkdir(dirname(targetImagePath), { recursive: true });
+
+    // 3. Copy from temporary file to target location
+    await copyFile(imageInfo.path, targetImagePath);
+
+    // 4. Update .meta.yaml
+    const metaPath = join(assetDir, ".meta.yaml");
+    const metaContent = await readFile(metaPath, "utf8");
+    const meta = yamlParse(metaContent);
+
+    // 4.1 Add target language to languages array
+    if (!meta.languages || !Array.isArray(meta.languages)) {
+      meta.languages = [];
+    }
+    if (!meta.languages.includes(targetLanguage)) {
+      meta.languages.push(targetLanguage);
+    }
+
+    // 4.2 Update translations info
+    if (!meta.translations) {
+      meta.translations = {};
+    }
+    meta.translations[targetLanguage] = {
+      sourceHash,
+      translatedAt: new Date().toISOString(),
+    };
+
+    // 5. Save updated .meta.yaml
+    const updatedMetaContent = yamlStringify(meta);
+    await writeFile(metaPath, updatedMetaContent, "utf8");
+
+    return {
+      success: true,
+      key,
+      targetLanguage,
+      targetImagePath,
+      message: `Image translation saved: ${targetImagePath}`,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: ERROR_CODES.SAVE_ERROR,
+      message: `Error saving image translation: ${error.message}`,
+      key,
+    };
+  }
+}
+
+// Add description
+saveImageTranslation.description =
+  "Save translated image to target path and update .meta.yaml file. " +
+  "Record source image hash and translation time for determining if re-translation is needed later.";
+
+// Define input schema
+saveImageTranslation.input_schema = {
+  type: "object",
+  required: ["key", "assetDir", "targetLanguage", "sourceHash", "images"],
+  properties: {
+    key: {
+      type: "string",
+      description: "Image key",
+    },
+    assetDir: {
+      type: "string",
+      description: "Image asset directory path",
+    },
+    targetLanguage: {
+      type: "string",
+      description: "Target language code",
+    },
+    sourceHash: {
+      type: "string",
+      description: "Source image hash",
+    },
+    images: {
+      type: "array",
+      description: "Image list returned by image translation agent",
+      items: {
+        type: "object",
+        properties: {
+          filename: { type: "string", description: "Filename" },
+          mimeType: { type: "string", description: "MIME type" },
+          type: { type: "string", description: "Type (local)" },
+          path: { type: "string", description: "Temporary file path" },
+        },
+      },
+    },
+  },
+};
+
+// Define output schema
+saveImageTranslation.output_schema = {
+  type: "object",
+  required: ["success"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "Whether operation succeeded",
+    },
+    key: {
+      type: "string",
+      description: "Image key",
+    },
+    targetLanguage: {
+      type: "string",
+      description: "Target language code (present on success)",
+    },
+    targetImagePath: {
+      type: "string",
+      description: "Saved image path (present on success)",
+    },
+    message: {
+      type: "string",
+      description: "Operation result description",
+    },
+    error: {
+      type: "string",
+      description: "Error code (present on failure)",
+    },
+  },
+};

package/agents/localize/translate-images/scan-doc-images.mjs

@@ -0,0 +1,165 @@
+import { access, readFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { parseSlots } from "../../../utils/image-slots.mjs";
+import { PATHS, ERROR_CODES } from "../../../utils/agent-constants.mjs";
+
+/**
+ * Scan image slots in document
+ * @param {Object} input - Input parameters
+ * @param {string} input.path - Document path
+ * @param {string} input.sourceLanguage - Source language code
+ * @param {string} input.language - Target language
+ * @returns {Promise<Object>} - Scan result
+ */
+export default async function scanDocImages(input) {
+  const { path: docPath, sourceLanguage, language } = input;
+  const targetLanguage = language;
+
+  try {
+    // 1. Build source document file path
+    const docFolder = path.join(PATHS.DOCS_DIR, docPath);
+    const sourceFile = path.join(docFolder, `${sourceLanguage}.md`);
+
+    // 2. Read source document content
+    let content;
+    try {
+      await access(sourceFile, constants.F_OK | constants.R_OK);
+      content = await readFile(sourceFile, "utf-8");
+    } catch (_error) {
+      throw new Error(`Source document does not exist: ${sourceFile}, document path: ${docPath}`);
+    }
+
+    // 3. Parse slots in document
+    const slots = parseSlots(content, docPath);
+
+    if (slots.length === 0) {
+      return {
+        success: true,
+        hasSlots: false,
+        slots: [],
+        targetLanguage,
+        path: docPath,
+        message: `No image slots in document`,
+      };
+    }
+
+    // 4. Check source image info for each slot
+    const slotsWithInfo = [];
+    for (const slot of slots) {
+      const { key, desc } = slot;
+
+      // Check if image directory exists
+      const assetDir = path.join(PATHS.ASSETS_DIR, key);
+      const metaPath = path.join(assetDir, ".meta.yaml");
+
+      try {
+        await access(metaPath, constants.F_OK | constants.R_OK);
+
+        slotsWithInfo.push({
+          key,
+          desc,
+          assetDir,
+          metaPath,
+          exists: true,
+        });
+      } catch (_error) {
+        // Image asset does not exist, skip
+        slotsWithInfo.push({
+          key,
+          desc,
+          assetDir: null,
+          metaPath: null,
+          exists: false,
+        });
+      }
+    }
+
+    return {
+      success: true,
+      hasSlots: true,
+      slots: slotsWithInfo,
+      targetLanguage,
+      path: docPath,
+      message: `Found ${slots.length} image slots in document, ${slotsWithInfo.filter((s) => s.exists).length} have source images`,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: ERROR_CODES.UNEXPECTED_ERROR,
+      message: `Error scanning document images: ${error.message}`,
+      path: docPath,
+    };
+  }
+}
+
+// Add description
+scanDocImages.description =
+  "Scan main language document content, extract AFS image slots, and check if corresponding image assets exist. " +
+  "Return list of images that need translation status check.";
+
+// Define input schema
+scanDocImages.input_schema = {
+  type: "object",
+  required: ["path", "sourceLanguage", "language"],
+  properties: {
+    path: {
+      type: "string",
+      description: "Document path",
+    },
+    sourceLanguage: {
+      type: "string",
+      description: "Source language code",
+    },
+    language: {
+      type: "string",
+      description: "Target language code",
+    },
+  },
+};
+
+// Define output schema
+scanDocImages.output_schema = {
+  type: "object",
+  required: ["success"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "Whether operation succeeded",
+    },
+    hasSlots: {
+      type: "boolean",
+      description: "Whether document contains image slots",
+    },
+    slots: {
+      type: "array",
+      description: "Image slot list",
+      items: {
+        type: "object",
+        properties: {
+          key: { type: "string", description: "Image key" },
+          desc: { type: "string", description: "Image description" },
+          assetDir: { type: "string", description: "Image asset directory path", nullable: true },
+          metaPath: { type: "string", description: ".meta.yaml file path", nullable: true },
+          exists: { type: "boolean", description: "Whether image asset exists" },
+        },
+      },
+    },
+    targetLanguage: {
+      type: "string",
+      description: "Target language code",
+    },
+    path: {
+      type: "string",
+      description: "Document path",
+    },
+    message: {
+      type: "string",
+      description: "Operation result description",
+    },
+    error: {
+      type: "string",
+      description: "Error code (present on failure)",
+    },
+  },
+};

package/agents/localize/translate-images/translate-doc-images.yaml

@@ -0,0 +1,24 @@
+type: team
+name: translateDocImages
+description: Detect images in document and translate to target language
+skills:
+  - url: ./scan-doc-images.mjs # Scan image slots in document
+  - url: ./detect-text/detect-images-text.yaml # Detect if images contain text and update shared field
+  - url: ./check-image-translation.mjs # Check which images need translation
+  - type: team
+    name: processImageTranslations # Process all image translation tasks
+    skills:
+      - type: team
+        name: translateSingleImage
+        description: Translate a single image (from source language to target language)
+        skills:
+          - url: ./prepare-image-input.mjs # Prepare input parameters for image translation
+          - url: ./translate-image.yaml # Execute image translation
+          - url: ./save-image-translation.mjs # Save translation result
+        mode: sequential
+        include_input_in_output: true
+
+    iterate_on: translationTasks
+    concurrency: 1
+mode: sequential
+include_input_in_output: true

package/agents/localize/{translate-diagram.yaml → translate-images/translate-image.yaml}

@@ -1,5 +1,6 @@
 type: image
-name: translateDiagram
+name: translateSlotImage
+description: Translate image to target language using image-to-image mode
 image_model:
   model: google/gemini-3-pro-image-preview
   imageConfig:
@@ -11,16 +12,16 @@ image_model:
 instructions: |
   You are a multilingual diagram translator specializing in technical diagrams such as flowcharts, architecture diagrams, network topologies, and mind maps.
 
-  Your task is to regenerate the provided image by translating all label-style text into {{locale}}.
+  Your task is to regenerate the provided image by translating all label-style text from {{sourceLanguage}} into {{targetLocale}}.
 
   Requirements:
   - Retain all command-style, technical, or protocol-specific terms (e.g., "API", "TCP/IP", "POST") in English;
-  - Maintain the original diagram’s structure, layout, visual style, and spatial relationships between elements;
+  - Maintain the original diagram's structure, layout, visual style, and spatial relationships between elements;
   - Only translate label or annotation text — all graphical elements should remain unchanged;
-  - **If {{locale}} is Simplified Chinese, Traditional Chinese, Japanese, or Korean, use the font "Microsoft YaHei" (微软雅黑)** to ensure optimal readability, proper character rendering, and consistent typographic style across Latin and CJK scripts;
+  - **If {{targetLocale}} is Simplified Chinese, Traditional Chinese, Japanese, or Korean, use the font "Microsoft YaHei" (微软雅黑)** to ensure optimal readability, proper character rendering, and consistent typographic style across Latin and CJK scripts;
   - For other languages, use a clean sans-serif font that best fits the visual style of the original image;
 
-  Your final output should be a regenerated image identical in design but localized in text according to {{locale}}.
+  Your final output should be a regenerated image identical in design but localized in text according to {{targetLocale}}.
 
 input_file_key: existingImage
 
@@ -29,7 +30,7 @@ input_schema:
   properties:
     existingImage:
       type: array
-      description: Array of mediaFile objects for the source diagram image to translate
+      description: Array of mediaFile objects for source language image (main language)
       items:
         type: object
         properties:
@@ -44,19 +45,29 @@ input_schema:
             description: Image filename
           mimeType:
             type: string
-            description: MIME type of the image (e.g., "image/png", "image/jpeg")
+            description: MIME type (e.g., "image/png", "image/jpeg")
+    desc:
+      type: string
+      description: AFS slot description, explaining the image content
+    sourceLanguage:
+      type: string
+      description: Source language code (e.g., "zh", "en")
+    targetLocale:
+      type: string
+      description: Target language code
     ratio:
       type: string
-      description: Aspect ratio of the image
+      description: Image aspect ratio
+      enum: ["1:1", "5:4", "4:3", "3:2", "16:9", "21:9"]
+      default: "4:3"
     size:
       type: string
-      description: Size of the generated image
-      default: "1K"
-    locale:
-      type: string
-      description: Target language code for translation
+      description: Generated image size
+      default: "2K"
   required:
     - existingImage
+    - sourceLanguage
+    - targetLocale
     - ratio
-    - locale
+
 include_input_in_output: true