@aigne/doc-smith 0.9.8-beta → 0.9.8

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.9.8](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.8-beta.1...v0.9.8) (2025-12-07)
+
+## [0.9.8-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.8-beta...v0.9.8-beta.1) (2025-12-06)
+
+
+### Features
+
+* **translation:** unify expressions and default to English for image info ([#349](https://github.com/AIGNE-io/aigne-doc-smith/issues/349)) ([c134b1a](https://github.com/AIGNE-io/aigne-doc-smith/commit/c134b1a0f38f5b7daf382b24cf5f71ecd2cccae7))
+
 ## [0.9.8-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.7...v0.9.8-beta) (2025-12-05)
 
 

package/agents/create/replace-d2-with-image.mjs

@@ -2,7 +2,12 @@ import { copyFile, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import fs from "fs-extra";
 import { createHash } from "node:crypto";
-import { DIAGRAM_PLACEHOLDER, d2CodeBlockRegex, ensureTmpDir } from "../../utils/d2-utils.mjs";
+import {
+  DIAGRAM_PLACEHOLDER,
+  d2CodeBlockRegex,
+  diagramImageBlockRegex,
+  ensureTmpDir,
+} from "../../utils/d2-utils.mjs";
 import { DOC_SMITH_DIR, TMP_DIR, TMP_ASSETS_DIR } from "../../utils/constants/index.mjs";
 import { getContentHash, getFileName } from "../../utils/utils.mjs";
 import { getExtnameFromContentType } from "../../utils/file-utils.mjs";
@@ -418,40 +423,36 @@ function findAllDiagramLocations(content) {
   // 2. Find DIAGRAM_IMAGE_START markers
   // Format: <!-- DIAGRAM_IMAGE_START:type:aspectRatio -->...<!-- DIAGRAM_IMAGE_END -->
   // Note: aspectRatio can contain colon (e.g., "16:9"), so we need to match until -->
-  const diagramImageRegex = /<!-- DIAGRAM_IMAGE_START:[^>]+ -->[\s\S]*?<!-- DIAGRAM_IMAGE_END -->/g;
-  let match = diagramImageRegex.exec(content);
-  while (match !== null) {
+  const imageMatches = Array.from(content.matchAll(diagramImageBlockRegex));
+  for (const match of imageMatches) {
     locations.push({
       type: "image",
       start: match.index,
       end: match.index + match[0].length,
     });
-    match = diagramImageRegex.exec(content);
   }
 
   // 3. Find D2 code blocks
   // Note: .* matches title or other text after ```d2 (e.g., ```d2 Vault 驗證流程)
-  match = d2CodeBlockRegex.exec(content);
-  while (match !== null) {
+  const d2Matches = Array.from(content.matchAll(d2CodeBlockRegex));
+  for (const match of d2Matches) {
     locations.push({
       type: "d2",
       start: match.index,
       end: match.index + match[0].length,
     });
-    match = d2CodeBlockRegex.exec(content);
   }
 
   // 4. Find Mermaid code blocks
   // Note: .* matches title or other text after ```mermaid (e.g., ```mermaid Flow Chart)
   const mermaidCodeBlockRegex = /```mermaid.*\n([\s\S]*?)```/g;
-  match = mermaidCodeBlockRegex.exec(content);
-  while (match !== null) {
+  const mermaidMatches = Array.from(content.matchAll(mermaidCodeBlockRegex));
+  for (const match of mermaidMatches) {
     locations.push({
       type: "mermaid",
       start: match.index,
       end: match.index + match[0].length,
     });
-    match = mermaidCodeBlockRegex.exec(content);
   }
 
   // Sort by position in document (top to bottom)

package/agents/utils/save-doc-translation.mjs

@@ -1,4 +1,8 @@
 import { saveDocTranslation as _saveDocTranslation } from "../../utils/utils.mjs";
+import { readFileContent } from "../../utils/docs-finder-utils.mjs";
+import { getFileName } from "../../utils/utils.mjs";
+import { debug } from "../../utils/debug.mjs";
+import { syncDiagramToTranslations } from "../../utils/sync-diagram-to-translations.mjs";
 
 export default async function saveDocTranslation({
   path,
@@ -7,6 +11,7 @@ export default async function saveDocTranslation({
   language,
   labels,
   isShowMessage = false,
+  locale,
 }) {
   await _saveDocTranslation({
     path,
@@ -16,6 +21,35 @@ export default async function saveDocTranslation({
     labels,
   });
 
+  // Sync diagram images from main document to translations
+  // This ensures all images (including diagrams) in the main document are synced to translation files
+  if (path && docsDir && locale) {
+    try {
+      // Read main document content (it should already be saved)
+      const mainFileName = getFileName(path, locale);
+      const mainContent = await readFileContent(docsDir, mainFileName);
+
+      if (mainContent) {
+        const syncResult = await syncDiagramToTranslations(
+          mainContent,
+          path,
+          docsDir,
+          locale,
+          "sync",
+        );
+
+        if (syncResult.updated > 0) {
+          debug(
+            `✅ Synced diagram images to ${syncResult.updated} translation file(s) after translation`,
+          );
+        }
+      }
+    } catch (error) {
+      // Don't fail the translation if sync fails
+      debug(`⚠️  Failed to sync diagram images after translation: ${error.message}`);
+    }
+  }
+
   if (isShowMessage) {
     const message = `✅ Translation completed successfully.`;
     return { message };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.8-beta",
+  "version": "0.9.8",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"

package/prompts/detail/diagram/generate-image-user.md

@@ -6,7 +6,7 @@ Please follow **all global rules, styles, aspect ratio logic, and diagram-type r
 - **Diagram Type:** {{ diagramType }}
 - **Visual Style:** {{ diagramStyle }}
 - **Aspect Ratio:** {{ aspectRatio }}
-- **Language:** {{ locale }}
+- **Language:** English
 
 # Your responsibilities:
 1. Read and analyze the document content.

package/utils/check-document-has-diagram.mjs

@@ -1,6 +1,4 @@
-import { DIAGRAM_PLACEHOLDER, d2CodeBlockRegex } from "./d2-utils.mjs";
-
-const diagramImageRegex = /<!--\s*DIAGRAM_IMAGE_START:[^>]+-->/g;
+import { DIAGRAM_PLACEHOLDER, d2CodeBlockRegex, diagramImageStartRegex } from "./d2-utils.mjs";
 
 /**
  * Check if document content contains diagram-related content
@@ -24,7 +22,7 @@ export function hasDiagramContent(content) {
   }
 
   // Check for existing diagram images (DIAGRAM_IMAGE_START markers)
-  const imageMatches = Array.from(content.matchAll(diagramImageRegex));
+  const imageMatches = Array.from(content.matchAll(diagramImageStartRegex));
   if (imageMatches.length > 0) {
     return true;
   }
@@ -51,7 +49,7 @@ export function getDiagramTypeLabels(content) {
   }
 
   // Check for existing diagram images (AI-generated images)
-  const imageMatches = Array.from(content.matchAll(diagramImageRegex));
+  const imageMatches = Array.from(content.matchAll(diagramImageStartRegex));
   if (imageMatches.length > 0) {
     labels.push("🍌 Image");
   }
@@ -88,7 +86,7 @@ export function hasBananaImages(content) {
   }
 
   // Check for existing diagram images (DIAGRAM_IMAGE_START markers)
-  const imageMatches = Array.from(content.matchAll(diagramImageRegex));
+  const imageMatches = Array.from(content.matchAll(diagramImageStartRegex));
   if (imageMatches.length > 0) {
     return true;
   }

package/utils/d2-utils.mjs

@@ -10,6 +10,18 @@ export const d2CodeBlockRegex = /```d2.*\n([\s\S]*?)```/g;
 
 export const DIAGRAM_PLACEHOLDER = "DIAGRAM_PLACEHOLDER";
 
+// Diagram image regex patterns for reuse across the codebase
+// Pattern 1: Match only the start marker (for checking existence)
+export const diagramImageStartRegex = /<!--\s*DIAGRAM_IMAGE_START:[^>]+-->/g;
+
+// Pattern 2: Match full diagram image block without capturing image path (for finding/replacing)
+export const diagramImageBlockRegex =
+  /<!--\s*DIAGRAM_IMAGE_START:[^>]+-->\s*[\s\S]*?<!--\s*DIAGRAM_IMAGE_END\s*-->/g;
+
+// Pattern 3: Match full diagram image block with image path capture (for extracting paths)
+export const diagramImageWithPathRegex =
+  /<!--\s*DIAGRAM_IMAGE_START:[^>]+-->\s*!\[[^\]]*\]\(([^)]+)\)\s*<!--\s*DIAGRAM_IMAGE_END\s*-->/g;
+
 export async function ensureTmpDir() {
   const tmpDir = path.join(DOC_SMITH_DIR, TMP_DIR);
   if (!(await fs.pathExists(path.join(tmpDir, ".gitignore")))) {
@@ -93,9 +105,8 @@ export function replaceDiagramsWithPlaceholder({ content, diagramIndex }) {
     return content;
   }
 
-  // Import regex from replace-d2-with-image.mjs to find all diagram locations
+  // Use exported regex to find all diagram locations
   // We'll use a similar approach to findAllDiagramLocations
-  const diagramImageRegex = /<!-- DIAGRAM_IMAGE_START:[^>]+ -->[\s\S]*?<!-- DIAGRAM_IMAGE_END -->/g;
   const mermaidCodeBlockRegex = /```mermaid.*\n([\s\S]*?)```/g;
 
   // Find all diagram locations
@@ -113,36 +124,33 @@ export function replaceDiagramsWithPlaceholder({ content, diagramIndex }) {
   }
 
   // 2. Find DIAGRAM_IMAGE_START markers (generated images)
-  let match = diagramImageRegex.exec(content);
-  while (match !== null) {
+  const imageMatches = Array.from(content.matchAll(diagramImageBlockRegex));
+  for (const match of imageMatches) {
     locations.push({
       type: "image",
       start: match.index,
       end: match.index + match[0].length,
     });
-    match = diagramImageRegex.exec(content);
   }
 
   // 3. Find D2 code blocks
-  match = d2CodeBlockRegex.exec(content);
-  while (match !== null) {
+  const d2Matches = Array.from(content.matchAll(d2CodeBlockRegex));
+  for (const match of d2Matches) {
     locations.push({
       type: "d2",
       start: match.index,
       end: match.index + match[0].length,
     });
-    match = d2CodeBlockRegex.exec(content);
   }
 
   // 4. Find Mermaid code blocks
-  match = mermaidCodeBlockRegex.exec(content);
-  while (match !== null) {
+  const mermaidMatches = Array.from(content.matchAll(mermaidCodeBlockRegex));
+  for (const match of mermaidMatches) {
     locations.push({
       type: "mermaid",
       start: match.index,
       end: match.index + match[0].length,
     });
-    match = mermaidCodeBlockRegex.exec(content);
   }
 
   // Sort by position (top to bottom)

package/utils/delete-diagram-images.mjs

@@ -19,12 +19,10 @@ export async function extractDiagramImagePaths(content, path, docsDir) {
   const imagePaths = [];
 
   // Pattern to match: <!-- DIAGRAM_IMAGE_START:... -->![alt](path)<!-- DIAGRAM_IMAGE_END -->
-  const diagramPattern =
-    /<!--\s*DIAGRAM_IMAGE_START:[^>]+-->\s*!\[[^\]]*\]\(([^)]+)\)\s*<!--\s*DIAGRAM_IMAGE_END\s*-->/g;
+  const { diagramImageWithPathRegex } = await import("./d2-utils.mjs");
+  const matches = Array.from(content.matchAll(diagramImageWithPathRegex));
 
-  diagramPattern.lastIndex = 0; // Reset regex
-  let match = diagramPattern.exec(content);
-  while (match !== null) {
+  for (const match of matches) {
     const imagePath = match[1];
 
     // Resolve absolute path
@@ -49,8 +47,6 @@ export async function extractDiagramImagePaths(content, path, docsDir) {
     if (await fs.pathExists(normalizedPath)) {
       imagePaths.push(normalizedPath);
     }
-
-    match = diagramPattern.exec(content);
   }
 
   return imagePaths;

package/utils/sync-diagram-to-translations.mjs

@@ -3,9 +3,7 @@ import { readFileContent } from "./docs-finder-utils.mjs";
 import { debug } from "./debug.mjs";
 import path from "node:path";
 import fs from "fs-extra";
-import { d2CodeBlockRegex } from "./d2-utils.mjs";
-const diagramImageRegex =
-  /<!--\s*DIAGRAM_IMAGE_START:[^>]+-->\s*!\[[^\]]*\]\(([^)]+)\)\s*<!--\s*DIAGRAM_IMAGE_END\s*-->/g;
+import { d2CodeBlockRegex, diagramImageWithPathRegex } from "./d2-utils.mjs";
 
 /**
  * Find all translation files for a document
@@ -21,15 +19,24 @@ async function findTranslationFiles(docPath, docsDir, locale) {
   try {
     const files = readdirSync(docsDir);
     const translationFiles = [];
+    const mainFileName = locale === "en" ? `${flatName}.md` : `${flatName}.${locale}.md`;
 
     // Filter files to find translation files matching the pattern
     for (const file of files) {
-      if (
-        file.startsWith(`${flatName}.`) &&
-        file.endsWith(".md") &&
-        file !== `${flatName}.md` &&
-        file.match(/\.\w+(-\w+)?\.md$/)
-      ) {
+      if (!file.endsWith(".md")) continue;
+      if (file === mainFileName) continue; // Skip main language file
+
+      // Case 1: File without language suffix (xxx.md) - this is English translation when main language is not English
+      if (file === `${flatName}.md` && locale !== "en") {
+        translationFiles.push({
+          language: "en",
+          fileName: file,
+        });
+        continue;
+      }
+
+      // Case 2: File with language suffix (xxx.{lang}.md) - all other translations
+      if (file.startsWith(`${flatName}.`) && file.match(/\.\w+(-\w+)?\.md$/)) {
         const langMatch = file.match(/\.(\w+(-\w+)?)\.md$/);
         if (langMatch && langMatch[1] !== locale) {
           translationFiles.push({
@@ -54,18 +61,14 @@ async function findTranslationFiles(docPath, docsDir, locale) {
  */
 function extractDiagramImagePaths(content) {
   const images = [];
+  const matches = Array.from(content.matchAll(diagramImageWithPathRegex));
 
-  // Reset regex lastIndex
-  diagramImageRegex.lastIndex = 0;
-
-  let match = diagramImageRegex.exec(content);
-  while (match !== null) {
+  for (const match of matches) {
     images.push({
       path: match[1],
       fullMatch: match[0],
       index: match.index,
     });
-    match = diagramImageRegex.exec(content);
   }
 
   return images;
@@ -118,7 +121,8 @@ export async function syncDiagramToTranslations(
       const translationFilePath = path.join(docsDir, fileName);
       const translationContent = await readFileContent(docsDir, fileName);
 
-      if (!translationContent) {
+      // Check for null or undefined (file read failure), but allow empty string (valid content)
+      if (translationContent === null || translationContent === undefined) {
         debug(`⚠️  Could not read translation file: ${fileName}`);
         result.skipped++;
         continue;