@aigne/doc-smith 0.9.10 → 0.9.11-beta

package/agents/localize/translate-documents/prepare-translation.mjs

@@ -0,0 +1,249 @@
+import { loadDocumentPaths, filterValidPaths } from "../../../utils/document-paths.mjs";
+import { PATHS, ERROR_CODES } from "../../../utils/agent-constants.mjs";
+import { loadLocale, loadConfigFromFile, saveValueToConfig } from "../../../utils/config.mjs";
+
+/**
+ * Prepare translation tasks
+ * @param {Object} input - Input parameters
+ * @param {string[]} input.docs - Document paths to translate (optional)
+ * @param {string[]} input.langs - Target language list (required)
+ * @param {boolean} input.force - Whether to force re-translation (optional, default false)
+ * @returns {Promise<Object>} - Translation task list or error message
+ */
+export default async function prepareTranslation(input) {
+  try {
+    // 1. Validate langs parameter
+    const { docs, langs, force = false } = input;
+
+    if (!langs || !Array.isArray(langs) || langs.length === 0) {
+      return {
+        success: false,
+        error: ERROR_CODES.MISSING_LANGS,
+        message: "Target language list cannot be empty",
+        suggestion: 'Please provide at least one target language (e.g., ["en", "ja"])',
+      };
+    }
+
+    // 2. Read source language
+    let sourceLanguage;
+    try {
+      sourceLanguage = await loadLocale();
+    } catch (error) {
+      if (error.message === ERROR_CODES.MISSING_CONFIG_FILE) {
+        return {
+          success: false,
+          error: ERROR_CODES.MISSING_CONFIG_FILE,
+          message: `Config file does not exist: ${PATHS.CONFIG}`,
+          suggestion:
+            "Please ensure you are executing this command in the document project root directory",
+        };
+      }
+      if (error.message === ERROR_CODES.MISSING_LOCALE) {
+        return {
+          success: false,
+          error: ERROR_CODES.MISSING_LOCALE,
+          message: `Missing locale field in ${PATHS.CONFIG}`,
+          suggestion: `Please add locale field to ${PATHS.CONFIG}`,
+        };
+      }
+      throw error;
+    }
+
+    // 3. Filter out languages same as source language
+    const targetLanguages = langs.filter((lang) => lang !== sourceLanguage);
+
+    if (targetLanguages.length === 0) {
+      return {
+        success: true,
+        skipped: true,
+        translationTasks: [],
+        sourceLanguage,
+        message: `All target languages are the same as source language (${sourceLanguage}), skipping translation`,
+      };
+    }
+
+    // 4. Load document structure
+    let validPaths;
+    try {
+      validPaths = await loadDocumentPaths();
+    } catch (error) {
+      if (error.message === ERROR_CODES.MISSING_STRUCTURE_FILE) {
+        return {
+          success: false,
+          error: ERROR_CODES.MISSING_STRUCTURE_FILE,
+          message: `Document structure file does not exist: ${PATHS.DOCUMENT_STRUCTURE}`,
+          suggestion: "Please generate document structure file first",
+        };
+      }
+      if (error.message === ERROR_CODES.INVALID_STRUCTURE_FILE) {
+        return {
+          success: false,
+          error: ERROR_CODES.INVALID_STRUCTURE_FILE,
+          message: "Invalid document structure file format",
+          suggestion: `Please ensure ${PATHS.DOCUMENT_STRUCTURE} contains a valid documents array`,
+        };
+      }
+      throw error;
+    }
+
+    // 5. Collect or validate document paths
+    let docPaths;
+    if (!docs || docs.length === 0) {
+      // Translate all documents
+      docPaths = Array.from(validPaths);
+    } else {
+      // Validate specified document paths
+      const { validPaths: validDocPaths, invalidPaths } = filterValidPaths(docs, validPaths);
+
+      if (invalidPaths.length > 0) {
+        return {
+          success: false,
+          error: ERROR_CODES.INVALID_DOC_PATHS,
+          message: `The following document paths do not exist in document structure: ${invalidPaths.join(", ")}`,
+          suggestion: `Please check if document paths are correct, or add these paths to ${PATHS.DOCUMENT_STRUCTURE}`,
+          invalidPaths,
+        };
+      }
+
+      docPaths = validDocPaths;
+    }
+
+    // 6. Update translateLanguages in config.yaml (only handle additions)
+    try {
+      const config = await loadConfigFromFile();
+      const existingLanguages = config?.translateLanguages || [];
+
+      // Find new languages (in targetLanguages but not in existingLanguages)
+      const newLanguages = targetLanguages.filter((lang) => !existingLanguages.includes(lang));
+
+      // If there are new languages, update config
+      if (newLanguages.length > 0) {
+        const updatedLanguages = [...existingLanguages, ...newLanguages];
+        await saveValueToConfig(
+          "translateLanguages",
+          updatedLanguages,
+          "A list of languages to translate the documentation to",
+        );
+      }
+    } catch (error) {
+      // If update fails, log warning but don't affect main flow
+      console.warn(`Failed to update translateLanguages in config.yaml: ${error.message}`);
+    }
+
+    // 7. Generate translation tasks
+    // Convert targetLanguages to object array so iterate_on can use
+    const translationTasks = docPaths.map((path) => ({
+      path,
+      sourceLanguage,
+      force,
+      targetLanguages: targetLanguages.map((lang) => ({ language: lang })),
+    }));
+
+    return {
+      success: true,
+      translationTasks,
+      sourceLanguage,
+      targetLanguages,
+      totalDocs: docPaths.length,
+      message: `Preparing to translate ${docPaths.length} documents to ${targetLanguages.length} languages (${targetLanguages.join(", ")})`,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: ERROR_CODES.UNEXPECTED_ERROR,
+      message: `Error preparing translation tasks: ${error.message}`,
+      suggestion: "Check file system permissions and file formats",
+    };
+  }
+}
+
+// Add description
+prepareTranslation.description =
+  "Check translation parameters, filter target languages, collect document paths, prepare for batch translation. " +
+  "Automatically read source language from config.yaml, filter target languages same as source language, " +
+  "validate document paths exist in planning/document-structure.yaml.";
+
+// Define input schema
+prepareTranslation.input_schema = {
+  type: "object",
+  properties: {
+    docs: {
+      type: "array",
+      items: { type: "string" },
+      description:
+        "Document paths to translate (optional, translates all documents if not provided)",
+    },
+    langs: {
+      type: "array",
+      items: { type: "string" },
+      description: "Target language list (required, at least one)",
+    },
+    force: {
+      type: "boolean",
+      description:
+        "Whether to force re-translation (optional, default false. When true, re-translate even if source document unchanged)",
+    },
+  },
+  required: ["langs"],
+};
+
+// Define output schema
+prepareTranslation.output_schema = {
+  type: "object",
+  required: ["success"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "Whether operation succeeded",
+    },
+    translationTasks: {
+      type: "array",
+      description: "Translation task list (present on success)",
+      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: "Filtered target language list",
+    },
+    totalDocs: {
+      type: "number",
+      description: "Total document count",
+    },
+    message: {
+      type: "string",
+      description: "Operation result description",
+    },
+    skipped: {
+      type: "boolean",
+      description: "Whether translation was skipped",
+    },
+    error: {
+      type: "string",
+      description: "Error code (present on failure)",
+    },
+    suggestion: {
+      type: "string",
+      description: "Suggested action (present on failure)",
+    },
+    invalidPaths: {
+      type: "array",
+      items: { type: "string" },
+      description: "Invalid document paths list (present on failure)",
+    },
+  },
+};

package/agents/localize/translate-documents/save-translation.mjs

@@ -0,0 +1,171 @@
+import { readFile, writeFile, access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import path from "node:path";
+import {
+  PATHS,
+  ERROR_CODES,
+  FILE_TYPES,
+  DOC_META_DEFAULTS,
+} from "../../../utils/agent-constants.mjs";
+
+/**
+ * Save translation result and update .meta.yaml
+ * @param {Object} input - Input parameters
+ * @param {string} input.path - Document path
+ * @param {string} input.targetFile - Target file path
+ * @param {string} input.targetLanguage - Target language code
+ * @param {string} input.sourceHash - Source document hash
+ * @param {string} input.translation - Translation content
+ * @returns {Promise<Object>} - Operation result
+ */
+export default async function saveTranslation(input) {
+  const { path: docPath, targetFile, targetLanguage, sourceHash, translation } = input;
+  try {
+    // 1. Save translation file
+    await writeFile(targetFile, translation, "utf8");
+
+    // 2. Update .meta.yaml
+    const docFolder = path.join(PATHS.DOCS_DIR, docPath);
+    const metaPath = path.join(docFolder, FILE_TYPES.META);
+
+    let meta = {};
+    let metaExists = false;
+
+    // Try to read existing .meta.yaml
+    try {
+      await access(metaPath, constants.F_OK | constants.R_OK);
+      const metaContent = await readFile(metaPath, "utf8");
+      meta = yamlParse(metaContent);
+      metaExists = true;
+    } catch (_error) {
+      // .meta.yaml does not exist, use defaults
+      meta = {
+        kind: DOC_META_DEFAULTS.KIND,
+        source: targetLanguage,
+        default: targetLanguage,
+      };
+    }
+
+    // 3. Initialize or update languages array
+    if (!meta.languages || !Array.isArray(meta.languages)) {
+      // Initialize languages array, including source language
+      meta.languages = meta.source ? [meta.source] : [];
+    }
+
+    // 4. Add target language (avoid duplicates)
+    if (!meta.languages.includes(targetLanguage)) {
+      meta.languages.push(targetLanguage);
+    }
+
+    // 5. Initialize or update translations object
+    if (!meta.translations || typeof meta.translations !== "object") {
+      meta.translations = {};
+    }
+
+    // 6. Record translation info (sourceHash and translation time)
+    meta.translations[targetLanguage] = {
+      sourceHash,
+      translatedAt: new Date().toISOString(),
+    };
+
+    // 7. Save updated .meta.yaml
+    const updatedMetaContent = yamlStringify(meta);
+    await writeFile(metaPath, updatedMetaContent, "utf8");
+
+    return {
+      success: true,
+      targetFile,
+      targetLanguage,
+      metaUpdated: true,
+      languages: meta.languages,
+      message: metaExists
+        ? `Translation saved and metadata updated: ${targetFile}`
+        : `Translation saved and metadata created: ${targetFile}`,
+      path: docPath,
+    };
+  } catch (error) {
+    return {
+      path: docPath,
+      success: false,
+      error: ERROR_CODES.SAVE_ERROR,
+      message: `Error saving translation: ${error.message}`,
+      suggestion: "Check file system permissions",
+    };
+  }
+}
+
+// Add description
+saveTranslation.description =
+  "Save translation result to target file and update document's .meta.yaml file. " +
+  "Automatically add target language to languages array, " +
+  "record source document hash and translation time to translations object for determining if re-translation is needed later.";
+
+// Define input schema
+saveTranslation.input_schema = {
+  type: "object",
+  required: ["path", "targetFile", "targetLanguage", "sourceHash", "translation"],
+  properties: {
+    path: {
+      type: "string",
+      description: "Document path",
+    },
+    targetFile: {
+      type: "string",
+      description: "Target file path",
+    },
+    targetLanguage: {
+      type: "string",
+      description: "Target language code",
+    },
+    sourceHash: {
+      type: "string",
+      description: "Source document SHA256 hash",
+    },
+    translation: {
+      type: "string",
+      description: "Translation content",
+    },
+  },
+};
+
+// Define output schema
+saveTranslation.output_schema = {
+  type: "object",
+  required: ["success"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "Whether operation succeeded",
+    },
+    targetFile: {
+      type: "string",
+      description: "Target file path (present on success)",
+    },
+    targetLanguage: {
+      type: "string",
+      description: "Target language code (present on success)",
+    },
+    metaUpdated: {
+      type: "boolean",
+      description: "Whether metadata was updated (present on success)",
+    },
+    languages: {
+      type: "array",
+      items: { type: "string" },
+      description: "Updated language list (present on success)",
+    },
+    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/translate-documents/translate-document-to-language.mjs

@@ -0,0 +1,209 @@
+import { readFile, access } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { parse as yamlParse } from "yaml";
+import { PATHS, ERROR_CODES, FILE_TYPES } from "../../../utils/agent-constants.mjs";
+import { calculateContentHash } from "../../../utils/image-utils.mjs";
+import saveTranslation from "./save-translation.mjs";
+
+/**
+ * Translate a single document to a single target language
+ * @param {Object} input - Input parameters
+ * @param {string} input.path - Document path
+ * @param {string} input.sourceLanguage - Source language code
+ * @param {string} input.language - Current iteration target language code (from iterate_on)
+ * @param {boolean} input.force - Whether to force re-translation
+ * @param {string} input.glossary - Glossary content
+ * @param {Object} options - Options parameters
+ * @param {Object} options.context - Context object containing invoke method
+ * @returns {Promise<Object>} - Translation result
+ */
+export default async function translateDocumentToLanguage(input, options) {
+  try {
+    const { path: docPath, sourceLanguage, language, force = false, glossary = "" } = input;
+
+    // When using iterate_on, object properties are spread, directly receiving language field
+    const targetLanguage = language;
+
+    // 1. Build file paths
+    const docFolder = path.join(PATHS.DOCS_DIR, docPath);
+    const sourceFile = path.join(docFolder, `${sourceLanguage}.md`);
+    const targetFile = path.join(docFolder, `${targetLanguage}.md`);
+
+    // 2. Read source document
+    let content;
+    try {
+      await access(sourceFile, constants.F_OK | constants.R_OK);
+      content = await readFile(sourceFile, "utf8");
+    } catch (_error) {
+      throw new Error(
+        `Source document does not exist: ${sourceFile}, document path: ${docPath}, please ensure source language document has been created`,
+      );
+    }
+
+    // 3. Calculate source document hash
+    const sourceHash = calculateContentHash(content);
+
+    // 4. Check if translation is needed (unless forced)
+    if (!force) {
+      const metaPath = path.join(docFolder, FILE_TYPES.META);
+      try {
+        await access(metaPath, constants.F_OK | constants.R_OK);
+        const metaContent = await readFile(metaPath, "utf8");
+        const meta = yamlParse(metaContent);
+
+        // Check if translation record exists for this language
+        if (meta.translations?.[targetLanguage]) {
+          const translationInfo = meta.translations[targetLanguage];
+
+          // If hash is the same, skip translation
+          if (translationInfo.sourceHash === sourceHash) {
+            return {
+              success: true,
+              skipped: true,
+              reason: "hash_unchanged",
+              targetLanguage,
+              message: `Source document unchanged, skipping translation: ${docPath} (${sourceLanguage} -> ${targetLanguage})`,
+              path: docPath,
+            };
+          }
+        }
+      } catch (_error) {
+        // .meta.yaml does not exist or failed to read, continue translation
+      }
+    }
+
+    // 5. Try to read old translation (as reference)
+    let previousTranslation = "";
+    try {
+      await access(targetFile, constants.F_OK | constants.R_OK);
+      previousTranslation = await readFile(targetFile, "utf8");
+    } catch (_error) {
+      // Old translation does not exist, this is normal
+    }
+
+    // 6. Call translation agent
+    const translateDocumentAgent = options.context?.agents?.["translateDocument"];
+    const translateResult = await options.context.invoke(translateDocumentAgent, {
+      language: targetLanguage,
+      content,
+      glossary,
+      previousTranslation,
+    });
+
+    if (!translateResult || !translateResult.translation) {
+      throw new Error(
+        `Translation failed: ${docPath} (${sourceLanguage} -> ${targetLanguage}), please try again`,
+      );
+    }
+
+    // 7. Save translation result
+    const saveResult = await saveTranslation({
+      path: docPath,
+      targetFile,
+      targetLanguage,
+      sourceHash,
+      translation: translateResult.translation,
+    });
+
+    return {
+      ...saveResult,
+      path: docPath,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: ERROR_CODES.UNEXPECTED_ERROR,
+      message: `Error during translation: ${error.message}`,
+      suggestion: "Check file system permissions and translation configuration",
+    };
+  }
+}
+
+// Add description
+translateDocumentToLanguage.description =
+  "Translate a single document to a single target language. " +
+  "Calculate source document hash, check if re-translation is needed (by comparing sourceHash saved in .meta.yaml). " +
+  "If source document is unchanged and not in force mode, skip translation. " +
+  "Otherwise call translation agent to execute translation and save result and sourceHash.";
+
+// Define input schema
+translateDocumentToLanguage.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 (from iterate_on, object properties spread)",
+    },
+    force: {
+      type: "boolean",
+      description: "Whether to force re-translation (optional, default false)",
+    },
+    glossary: {
+      type: "string",
+      description: "Glossary content (optional)",
+    },
+  },
+};
+
+// Define output schema
+translateDocumentToLanguage.output_schema = {
+  type: "object",
+  required: ["success"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "Whether operation succeeded",
+    },
+    skipped: {
+      type: "boolean",
+      description: "Whether translation was skipped (when source document hash unchanged)",
+    },
+    reason: {
+      type: "string",
+      description: "Skip reason (present when skipped=true)",
+    },
+    targetFile: {
+      type: "string",
+      description: "Target file path (present when succeeded and not skipped)",
+    },
+    targetLanguage: {
+      type: "string",
+      description: "Target language code",
+    },
+    metaUpdated: {
+      type: "boolean",
+      description: "Whether metadata was updated (present when succeeded and not skipped)",
+    },
+    languages: {
+      type: "array",
+      items: { type: "string" },
+      description: "Updated language list (present when succeeded and not skipped)",
+    },
+    message: {
+      type: "string",
+      description: "Operation result description",
+    },
+    path: {
+      type: "string",
+      description: "Document path",
+    },
+    error: {
+      type: "string",
+      description: "Error code (present on failure)",
+    },
+    suggestion: {
+      type: "string",
+      description: "Suggested action (present on failure)",
+    },
+  },
+};

package/agents/localize/translate-documents/translate-document.yaml

@@ -0,0 +1,23 @@
+name: translateDocument
+description: Translate document to target language using translation prompts
+instructions:
+  url: ../prompts/translate-document.md
+input_schema:
+  type: object
+  properties:
+    language:
+      type: string
+      description: Target language code (e.g., "en", "ja", "fr", etc.)
+    content:
+      type: string
+      description: Document content to translate (Markdown format)
+    glossary:
+      type: string
+      description: Glossary content (optional, for maintaining consistent translation of proper nouns)
+    previousTranslation:
+      type: string
+      description: Existing translation version (optional, as reference context to improve translation quality)
+  required:
+    - language
+    - content
+output_key: translation

package/agents/localize/translate-documents/translate-to-languages.yaml

@@ -0,0 +1,10 @@
+type: team
+name: translateToLanguages
+description: Translate a single document to multiple languages, and translate images in the document
+skills:
+  - url: ./translate-document-to-language.mjs # Check hash, execute translation, save result
+  - url: ../translate-images/translate-doc-images.yaml # Detect and translate images in the document
+iterate_on: targetLanguages
+concurrency: 1
+mode: parallel
+include_input_in_output: true