@aigne/doc-smith 0.9.10 → 0.9.11-beta

package/agents/generate-images/scan-image-slots.mjs

@@ -0,0 +1,247 @@
+import { readFile, access, constants } from "node:fs/promises";
+import { join } from "node:path";
+import { loadDocumentPaths, filterValidPaths } from "../../utils/document-paths.mjs";
+import { PATHS, ERROR_CODES } from "../../utils/agent-constants.mjs";
+import { parseSlots } from "../../utils/image-slots.mjs";
+import { calculateContentHash } from "../../utils/image-utils.mjs";
+import { loadLocale } from "../../utils/config.mjs";
+
+/**
+ * Scan slots in a single document
+ * @param {string} docPath - Document path
+ * @param {string} locale - Main language
+ * @returns {Promise<Object|null>} - { path, hash, content, slots } or null (if file does not exist)
+ */
+async function scanDocument(docPath, locale) {
+  // Build document file path: docs/{path}/{locale}.md
+  const normalizedPath = docPath.startsWith("/") ? docPath.slice(1) : docPath;
+  const filePath = join(PATHS.DOCS_DIR, normalizedPath, `${locale}.md`);
+
+  // Check if file exists
+  try {
+    await access(filePath, constants.F_OK | constants.R_OK);
+  } catch (_error) {
+    // File does not exist, skip (may be a document not yet generated)
+    return null;
+  }
+
+  // Read document content
+  const content = await readFile(filePath, "utf8");
+
+  // Calculate hash
+  const hash = calculateContentHash(content);
+
+  // Parse slots
+  const slots = parseSlots(content, docPath);
+
+  return {
+    path: docPath,
+    hash,
+    content,
+    slots,
+  };
+}
+
+/**
+ * Group slots by key
+ * @param {Array} scanResults - Scan results array
+ * @returns {Map} - key -> { key, id, desc, documents }
+ */
+function groupSlotsByKey(scanResults) {
+  const slotMap = new Map();
+
+  for (const result of scanResults) {
+    if (!result || result.slots.length === 0) {
+      continue;
+    }
+
+    for (const slot of result.slots) {
+      const { key, id, desc } = slot;
+
+      if (!slotMap.has(key)) {
+        slotMap.set(key, {
+          key,
+          id,
+          desc,
+          documents: [],
+        });
+      }
+
+      // If the same key is used multiple times, use the last id and desc
+      const existing = slotMap.get(key);
+      existing.id = id;
+      existing.desc = desc;
+
+      // Add document reference
+      existing.documents.push({
+        path: result.path,
+        hash: result.hash,
+        content: result.content,
+      });
+    }
+  }
+
+  return slotMap;
+}
+
+/**
+ * Scan AFS image slots in documents
+ * @param {Object} input - Input parameters
+ * @param {string[]} input.docs - Document path list to scan (optional)
+ * @returns {Promise<Object>} - Scan result
+ */
+export default async function scanImageSlots(input) {
+  try {
+    const { docs } = input;
+
+    // 1. Read main language
+    let locale;
+    try {
+      locale = await loadLocale();
+    } catch (error) {
+      if (error.message === ERROR_CODES.MISSING_CONFIG_FILE) {
+        throw new Error(
+          `Config file does not exist: ${PATHS.CONFIG}, please ensure executing this command in doc-smith project root directory`,
+        );
+      }
+      if (error.message === ERROR_CODES.MISSING_LOCALE) {
+        throw new Error(
+          `Missing locale field in ${PATHS.CONFIG}, please ask the user for the main language for image generation, add the locale field to ${PATHS.CONFIG}, then try executing the command again`,
+        );
+      }
+      throw error;
+    }
+
+    // 2. Load document structure
+    let validPaths;
+    try {
+      validPaths = await loadDocumentPaths();
+    } catch (error) {
+      if (error.message === ERROR_CODES.MISSING_STRUCTURE_FILE) {
+        throw new Error(
+          `Document structure file does not exist: ${PATHS.DOCUMENT_STRUCTURE}, please generate documents using doc-smith skill first`,
+        );
+      }
+      if (error.message === ERROR_CODES.INVALID_STRUCTURE_FILE) {
+        throw new Error(
+          `Invalid document structure file format, please ensure ${PATHS.DOCUMENT_STRUCTURE} contains a valid documents array, otherwise cannot scan image slots in documents, please refer to references/document-structure-schema.md for file structure`,
+        );
+      }
+      throw error;
+    }
+
+    // 3. Collect or validate document paths
+    let docPaths;
+    if (!docs || docs.length === 0) {
+      // Scan all documents
+      docPaths = Array.from(validPaths);
+    } else {
+      // Validate specified document paths
+      const { validPaths: validDocPaths, invalidPaths } = filterValidPaths(docs, validPaths);
+
+      if (invalidPaths.length > 0) {
+        throw new Error(
+          `The following document paths do not exist in document structure: ${invalidPaths.join(", ")}, please check if document paths are correct`,
+        );
+      }
+
+      docPaths = validDocPaths;
+    }
+
+    // 4. Scan all documents
+    const scanResults = await Promise.all(docPaths.map((path) => scanDocument(path, locale)));
+
+    // 5. Group by key
+    const slotMap = groupSlotsByKey(scanResults);
+    const slots = Array.from(slotMap.values());
+
+    // 6. Return result
+    return {
+      success: true,
+      locale,
+      slots,
+      totalDocs: docPaths.length,
+      totalSlots: slots.length,
+      message: `Scanned ${docPaths.length} documents, found ${slots.length} image slots`,
+    };
+  } catch (error) {
+    throw new Error(`Error scanning image slots: ${error.message}`);
+  }
+}
+
+// Add description
+scanImageSlots.description =
+  "Scan AFS image slots in main language documents, parse id, key, desc, " +
+  "calculate document content hash, group by key and return all slot information.";
+
+// Define input schema
+scanImageSlots.input_schema = {
+  type: "object",
+  properties: {
+    docs: {
+      type: "array",
+      items: { type: "string" },
+      description: "Document path list to scan (optional, scans all documents if not provided)",
+    },
+  },
+};
+
+// Define output schema
+scanImageSlots.output_schema = {
+  type: "object",
+  required: ["success"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "Whether operation succeeded",
+    },
+    locale: {
+      type: "string",
+      description: "Main language code",
+    },
+    slots: {
+      type: "array",
+      description: "Slot list grouped by key",
+      items: {
+        type: "object",
+        properties: {
+          key: { type: "string", description: "Image directory name" },
+          id: { type: "string", description: "Slot id of the last usage of this key" },
+          desc: { type: "string", description: "Slot description" },
+          documents: {
+            type: "array",
+            description: "Document list referencing this key",
+            items: {
+              type: "object",
+              properties: {
+                path: { type: "string" },
+                hash: { type: "string" },
+                content: { type: "string" },
+              },
+            },
+          },
+        },
+      },
+    },
+    totalDocs: {
+      type: "number",
+      description: "Total documents scanned",
+    },
+    totalSlots: {
+      type: "number",
+      description: "Total slots found",
+    },
+    message: {
+      type: "string",
+      description: "Operation result description",
+    },
+    error: {
+      type: "string",
+      description: "Error code (present on failure)",
+    },
+    suggestion: {
+      type: "string",
+      description: "Suggested action (present on failure)",
+    },
+  },
+};

package/agents/localize/index.yaml

@@ -2,61 +2,38 @@ type: team
 name: localize
 alias:
   - translate
-description: Translate documents into other languages
+description: |
+  Batch translate documents to multiple languages, supports translating multiple documents and multiple languages at once.
 skills:
-  - url: ../init/index.mjs
-    default_input:
-      skipIfExists: true
-      checkOnly: true
-  - ../utils/load-sources.mjs
-  - url: ../init/check.mjs
-  - type: transform
-    task_render_mode: hide
-    jsonata: |
-      $merge([
-        $,
-        {
-          'documentStructure': originalDocumentStructure
-        }
-      ])
-  - url: ../update/check-diagram-flag.mjs
-  - url: ../utils/choose-docs.mjs
-    default_input:
-      isTranslate: true
-  - ../localize/choose-language.mjs
+  - url: ./translate-documents/prepare-translation.mjs  # Check and prepare translation tasks
+  - url: ./translate-documents/load-glossary.mjs        # Load glossary (once)
   - type: team
-    name: batchTranslateDocument
+    name: processAllDocuments       # Process all documents
     skills:
-      - ../localize/translate-multilingual.yaml
-    iterate_on: selectedDocs
-    concurrency: 5
-  - url: ../utils/check-feedback-refiner.mjs
-    default_input:
-      stage: translation_refine
-  - url: ./record-translation-history.mjs
-  - url: ../utils/action-success.mjs
-    default_input:
-      action: '✅ Translation completed'
+      - url: ./translate-documents/translate-to-languages.yaml
+    iterate_on: translationTasks
+    concurrency: 3
+  - url: ./translate-documents/generate-summary.mjs     # Generate final summary report
 input_schema:
   type: object
   properties:
-    glossary:
-      type: string
-      description: Glossary file for consistent terminology (use @filename.md)
     docs:
       type: array
       items:
         type: string
-      description: Documents to translate
+      description: |
+        List of document paths to translate (optional, e.g., ["/overview", "/api/auth"]), must exist in planning/document-structure.yaml.
+        If not provided or empty array, translates all documents; if paths are provided, only translates specified documents and validates path validity.
     langs:
       type: array
       items:
         type: string
-      description: 'Target languages (available: en, zh, zh-TW, ja, fr, de, es, it, ru, ko, pt, ar)'
-    feedback:
-      type: string
-      description: Tell us how to improve the translation style
-    diagram:
+      description: |
+        Target language list (required, e.g., ["en", "ja", "fr"]), using standard language codes.
+    force:
       type: boolean
-      description: Translate only diagram images without translating document content (use --diagram flag)
+      description: |
+        Whether to force re-translation (optional, default false). When set to true, re-translates all documents even if source documents haven't changed.
+  required:
+    - langs
 mode: sequential

package/{prompts/translate → agents/localize/prompts}/translate-document.md

@@ -21,36 +21,9 @@ Translation Requirements:
 - Use Terminology Reference: Ensure accuracy and consistency of professional terminology.
 - Preserve Terms: Retain specific terms in their original form, avoiding translation.
 - Maintain tone consistency: use a neutral tone for developer/DevOps docs, a polite tone for end-user/client docs, and do not mix address styles (e.g., **"you"** vs **"您"**).
-- Translate Descriptions Only in <x-field>: All `<x-field>` component attributes must maintain the original format. Only translate the description content within `data-desc` attribute or `<x-field-desc>` elements.
 
-{% include "./code-block.md" %}
-
-{% include "./admonition.md" %}
 </translation_rules>
 
-{% if feedback %}
-<translation_user_feedback>
-{{ feedback }}
-</translation_user_feedback>
-{% endif %}
-
-{% if detailFeedback %}
-<translation_review_feedback>
-{{ detailFeedback }}
-</translation_review_feedback>
-{% endif %}
-
-{% if userPreferences %}
-<user_preferences>
-{{userPreferences}}
-
-User preference guidelines:
-
-- User preferences are derived from feedback provided in previous user interactions. When generating translations, consider user preferences to avoid repeating issues mentioned in user feedback
-- User preferences carry less weight than current user feedback
-  </user_preferences>
-  {% endif %}
-
 {% include "./glossary.md" %}
 
 Terms to preserve (do not translate):
@@ -81,26 +54,6 @@ Table Translation - Demonstrates how to translate table content while preserving
 </after_translate>
 </example_item>
 
-<example_item>
-XField Component Translation - Shows how to translate only description content within x-field components while preserving all attributes.
-
-<before_translate>
-
-<x-field data-name="teamDid" data-type="string" data-required="true" data-desc="The DID of the team or Blocklet managing the webhook."></x-field>
-
-<x-field data-name="apiKey" data-type="string" data-required="true">
-    <x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section.</x-field-desc>
-</before_translate>
-
-<after_translate>
-<x-field data-name="teamDid" data-type="string" data-required="true" data-desc="管理 Webhook 的团队或 Blocklet 的 DID。"></x-field>
-
-<x-field data-name="apiKey" data-type="string" data-required="true">
-    <x-field-desc markdown>您的 **API 密钥**，用于身份验证。请从 `设置 > API 密钥` 部分生成一个。</x-field-desc>
-</x-field>
-</after_translate>
-</example_item>
-
 <example_item>
 Code Block Translation - Illustrates translating only comments in code blocks while keeping all code content unchanged.
 
@@ -201,98 +154,6 @@ Cache for server cleared: [list of cleared cache keys]
 </after_translate>
 </example_item>
 
-<example_item>
-D2 Diagram Translation - Shows how to translate only labels in D2 diagrams while preserving all syntax and structure.
-
-<before_translate>
-
-```d2 High-Level Architecture
-direction: down
-
-User: {
-  shape: c4-person
-}
-
-Your-Application: {
-  label: "Your Application"
-  shape: rectangle
-
-  PaymentProvider: {
-    label: "PaymentProvider"
-    shape: rectangle
-
-    Payment-Components: {
-      label: "Payment Components"
-      shape: rectangle
-      grid-columns: 2
-
-      CheckoutForm: { label: "CheckoutForm" }
-      CheckoutTable: { label: "CheckoutTable" }
-      CheckoutDonate: { label: "CheckoutDonate" }
-      CustomerInvoiceList: { label: "CustomerInvoiceList" }
-    }
-  }
-}
-
-Payment-Kit-Backend: {
-  label: "Payment Kit Backend"
-  shape: cylinder
-}
-
-User -> Your-Application.PaymentProvider.Payment-Components: "Interacts with UI"
-Your-Application.PaymentProvider -> Payment-Kit-Backend: "Handles API Communication"
-Payment-Kit-Backend -> Your-Application.PaymentProvider: "Returns Data"
-Your-Application.PaymentProvider.Payment-Components -> User: "Renders UI Updates"
-
-```
-
-</before_translate>
-
-<after_translate>
-
-```d2 高层架构
-direction: down
-
-User: {
-  shape: c4-person
-}
-
-Your-Application: {
-  label: "您的应用程序"
-  shape: rectangle
-
-  PaymentProvider: {
-    label: "PaymentProvider"
-    shape: rectangle
-
-    Payment-Components: {
-      label: "支付组件"
-      shape: rectangle
-      grid-columns: 2
-
-      CheckoutForm: { label: "CheckoutForm" }
-      CheckoutTable: { label: "CheckoutTable" }
-      CheckoutDonate: { label: "CheckoutDonate" }
-      CustomerInvoiceList: { label: "CustomerInvoiceList" }
-    }
-  }
-}
-
-Payment-Kit-Backend: {
-  label: "Payment Kit 后端"
-  shape: cylinder
-}
-
-User -> Your-Application.PaymentProvider.Payment-Components: "与 UI 交互"
-Your-Application.PaymentProvider -> Payment-Kit-Backend: "处理 API 通信"
-Payment-Kit-Backend -> Your-Application.PaymentProvider: "返回数据"
-Your-Application.PaymentProvider.Payment-Components -> User: "渲染 UI 更新"
-
-```
-
-</after_translate>
-</example_item>
-
 </example>
 
 Original text as follows:

package/agents/localize/translate-documents/generate-summary.mjs

@@ -0,0 +1,163 @@
+/**
+ * Generate final summary report for translation tasks
+ * @param {Object} input - Input parameters
+ * @param {Array} input.translationTasks - Translation task list
+ * @param {string} input.sourceLanguage - Source language code
+ * @param {Array} input.targetLanguages - Target language list
+ * @param {number} input.totalDocs - Total document count
+ * @param {boolean} input.skipped - Whether translation was skipped
+ * @returns {Object} - Object containing formatted message and statistics
+ */
+export default function generateSummary(input) {
+  const { translationTasks, sourceLanguage, targetLanguages, totalDocs, skipped } = input;
+
+  // If translation was skipped
+  if (skipped) {
+    return {
+      message: `⏭️  Translation skipped: All target languages are the same as source language (${sourceLanguage})`,
+      summary: {
+        skipped: true,
+        sourceLanguage,
+        totalDocs: 0,
+        totalLanguages: 0,
+        totalTranslations: 0,
+      },
+    };
+  }
+
+  // Calculate statistics
+  const totalLanguages = targetLanguages.length;
+  const totalTranslations = totalDocs * totalLanguages;
+
+  // Generate document path list (show at most 5)
+  const docPaths = translationTasks.map((task) => task.path);
+  const displayDocs =
+    docPaths.length > 5
+      ? [...docPaths.slice(0, 5), `... and ${docPaths.length - 5} more documents`]
+      : docPaths;
+
+  // Generate formatted message
+  const message = `
+✅ Translation tasks completed
+
+📊 **Translation Statistics**:
+   - Source language: ${sourceLanguage}
+   - Target languages: ${targetLanguages.join(", ")} (${totalLanguages} languages)
+   - Document count: ${totalDocs}
+   - Total translations: ${totalTranslations}
+
+📄 **Translated Documents**:
+${displayDocs.map((doc) => `   - ${doc}`).join("\n")}
+
+💡 **Tips**:
+   - Translation files saved to docs/{path}/{language}.md
+   - Document .meta.yaml languages field has been automatically updated
+   - Check the corresponding language files to view translation results
+  `.trim();
+
+  return {
+    message,
+    summary: {
+      skipped: false,
+      sourceLanguage,
+      targetLanguages,
+      totalDocs,
+      totalLanguages,
+      totalTranslations,
+      documentPaths: docPaths,
+    },
+  };
+}
+
+// Add description
+generateSummary.description =
+  "Generate final summary report for translation tasks. " +
+  "Summarize translation statistics (source language, target languages, document count, etc.) and generate readable formatted message. " +
+  "If translation was skipped, generate corresponding skip notice.";
+
+// Define input schema
+generateSummary.input_schema = {
+  type: "object",
+  properties: {
+    translationTasks: {
+      type: "array",
+      description: "Translation task list",
+      items: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          sourceLanguage: { type: "string" },
+          targetLanguages: {
+            type: "array",
+            items: { type: "object", properties: { language: { type: "string" } } },
+          },
+        },
+      },
+    },
+    sourceLanguage: {
+      type: "string",
+      description: "Source language code",
+    },
+    targetLanguages: {
+      type: "array",
+      items: { type: "string" },
+      description: "Target language list",
+    },
+    totalDocs: {
+      type: "number",
+      description: "Total document count",
+    },
+    skipped: {
+      type: "boolean",
+      description: "Whether translation was skipped",
+    },
+  },
+};
+
+// Define output schema
+generateSummary.output_schema = {
+  type: "object",
+  required: ["message", "summary"],
+  properties: {
+    message: {
+      type: "string",
+      description: "Formatted summary message containing translation statistics and tips",
+    },
+    summary: {
+      type: "object",
+      description: "Structured statistics data",
+      properties: {
+        skipped: {
+          type: "boolean",
+          description: "Whether translation was skipped",
+        },
+        sourceLanguage: {
+          type: "string",
+          description: "Source language code",
+        },
+        targetLanguages: {
+          type: "array",
+          items: { type: "string" },
+          description: "Target language list",
+        },
+        totalDocs: {
+          type: "number",
+          description: "Total document count",
+        },
+        totalLanguages: {
+          type: "number",
+          description: "Total target language count",
+        },
+        totalTranslations: {
+          type: "number",
+          description: "Total translation count (documents × languages)",
+        },
+        documentPaths: {
+          type: "array",
+          items: { type: "string" },
+          description: "List of all translated document paths",
+        },
+      },
+    },
+  },
+};

package/agents/localize/translate-documents/load-glossary.mjs

@@ -0,0 +1,52 @@
+import { readFile, access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { PATHS } from "../../../utils/agent-constants.mjs";
+
+/**
+ * Load glossary
+ * @returns {Promise<Object>} - Object containing glossary content
+ */
+export default async function loadGlossary() {
+  const glossaryPath = PATHS.GLOSSARY;
+
+  try {
+    // Check if glossary file exists
+    await access(glossaryPath, constants.F_OK | constants.R_OK);
+
+    // Read glossary content
+    const glossary = await readFile(glossaryPath, "utf8");
+
+    return {
+      glossary: glossary.trim(),
+      message: `Glossary loaded: ${glossaryPath}`,
+    };
+  } catch (_error) {
+    // Glossary file does not exist, return empty string
+    return {
+      glossary: "",
+      message: "Glossary file not found, will not use glossary",
+    };
+  }
+}
+
+// Add description
+loadGlossary.description =
+  "Load translation glossary file (intent/GLOSSARY.md). " +
+  "If file exists, read content; otherwise return empty string. " +
+  "Glossary content will be used in all translation tasks to ensure consistency of proper nouns.";
+
+// Define output schema
+loadGlossary.output_schema = {
+  type: "object",
+  required: ["glossary", "message"],
+  properties: {
+    glossary: {
+      type: "string",
+      description: "Glossary content (empty string if not exists)",
+    },
+    message: {
+      type: "string",
+      description: "Operation result description",
+    },
+  },
+};