feat: implement docs-cli for translating MDX files

- Removed old translate-docs.mjs script and replaced it with a new CLI tool.
- Added @docs/cli package with commands for translating documentation files.
- Introduced translation utilities for handling file paths and OpenAI API interactions.
- Configured .gitignore for the new package.
- Established pnpm workspace for better package management.

Author: hotlong

.github/workflows/ai-translate.yml

@@ -32,9 +32,14 @@ jobs:
           files: content/docs/**/*.mdx
           separator: ","
 
+      - name: Install pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 8
+
       - name: Install dependencies
         if: steps.changed-files.outputs.any_changed == 'true'
-        run: npm install openai
+        run: pnpm install
 
       - name: Run translation script
         if: steps.changed-files.outputs.any_changed == 'true'
@@ -45,7 +50,7 @@ jobs:
           OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL }} 
           OPENAI_MODEL: "gpt-4o" 
           CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
-        run: node scripts/translate-docs.mjs
+        run: pnpm translate
 
       - name: Create Pull Request
         if: steps.changed-files.outputs.any_changed == 'true'

package.json

@@ -7,8 +7,11 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "translate": "node scripts/translate-docs.mjs",
-    "translate:all": "node scripts/translate-docs.mjs --all"
+    "translate": "docs-cli translate",
+    "translate:all": "docs-cli translate --all"
+  },
+  "devDependencies": {
+    "@docs/cli": "workspace:*"
   },
   "dependencies": {
     "@fumadocs/ui": "^16.4.7",

packages/docs-cli/.gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.env
+.DS_Store
+*.log
+coverage

packages/docs-cli/bin/cli.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { cac } from 'cac';
+import 'dotenv/config';
+import { registerTranslateCommand } from '../src/commands/translate.mjs';
+
+const cli = cac('docs-cli');
+
+registerTranslateCommand(cli);
+
+cli.help();
+cli.version('0.0.1');
+
+cli.parse();
+

packages/docs-cli/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@docs/cli",
+  "version": "0.0.1",
+  "type": "module",
+  "bin": {
+    "docs-cli": "./bin/cli.mjs"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "openai": "^4.0.0",
+    "cac": "^6.7.14",
+    "dotenv": "^16.4.5"
+  }
+}

packages/docs-cli/src/commands/translate.mjs

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import OpenAI from 'openai';
+import { getAllMdxFiles, resolveTranslatedFilePath, translateContent } from '../utils/translate.mjs';
+
+export function registerTranslateCommand(cli) {
+  cli
+    .command('translate [files...]', 'Translate documentation files')
+    .option('--all', 'Translate all files in content/docs')
+    .option('--model <model>', 'OpenAI model to use', { default: 'gpt-4o' })
+    .action(async (files, options) => {
+      const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+      const OPENAI_BASE_URL = process.env.OPENAI_BASE_URL;
+
+      if (!OPENAI_API_KEY) {
+        console.error('Error: Missing OPENAI_API_KEY environment variable.');
+        process.exit(1);
+      }
+
+      const openai = new OpenAI({
+        apiKey: OPENAI_API_KEY,
+        baseURL: OPENAI_BASE_URL,
+      });
+
+      let targetFiles = [];
+
+      if (options.all) {
+        console.log('Scanning for all .mdx files in content/docs...');
+        targetFiles = getAllMdxFiles('content/docs');
+      } else if (files && files.length > 0) {
+          targetFiles = files;
+      } else if (process.env.CHANGED_FILES) {
+          targetFiles = process.env.CHANGED_FILES.split(',');
+      }
+
+      if (targetFiles.length === 0) {
+        console.log('No files to translate.');
+        console.log('Usage:');
+        console.log('  docs-cli translate content/docs/file.mdx');
+        console.log('  docs-cli translate --all');
+        console.log('  (CI): Set CHANGED_FILES environment variable');
+        return;
+      }
+
+      console.log(`Processing ${targetFiles.length} files...`);
+
+      for (const file of targetFiles) {
+          const enFilePath = path.resolve(process.cwd(), file);
+          
+          if (!fs.existsSync(enFilePath)) {
+              console.log(`File skipped (not found): ${file}`);
+              continue;
+          }
+
+          const zhFilePath = resolveTranslatedFilePath(enFilePath);
+          
+          if (zhFilePath === enFilePath) {
+              console.log(`Skipping: Source and destination are the same for ${file}`);
+              continue;
+          }
+
+          console.log(`Translating: ${file} -> ${path.relative(process.cwd(), zhFilePath)}`);
+
+          try {
+              const content = fs.readFileSync(enFilePath, 'utf-8');
+              const translatedContent = await translateContent(content, openai, options.model);
+
+              const dir = path.dirname(zhFilePath);
+              if (!fs.existsSync(dir)) {
+                  fs.mkdirSync(dir, { recursive: true });
+              }
+
+              fs.writeFileSync(zhFilePath, translatedContent);
+              console.log(`✓ Automatically translated: ${zhFilePath}`);
+          } catch (error) {
+              console.error(`✗ Failed to translate ${file}:`, error);
+          }
+      }
+    });
+}

packages/docs-cli/src/utils/translate.mjs

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import OpenAI from 'openai';
+
+export function getAllMdxFiles(dir) {
+  let results = [];
+  if (!fs.existsSync(dir)) return results;
+  
+  const list = fs.readdirSync(dir);
+  list.forEach(file => {
+    file = path.join(dir, file);
+    const stat = fs.statSync(file);
+    if (stat && stat.isDirectory()) {
+      results = results.concat(getAllMdxFiles(file));
+    } else {
+      if (file.endsWith('.mdx')) {
+        results.push(path.relative(process.cwd(), file));
+      }
+    }
+  });
+  return results;
+}
+
+export function resolveTranslatedFilePath(enFilePath) {
+  // Strategy: content/docs/path/to/file.mdx -> content/docs-zh-CN/path/to/file.mdx
+  const docsRoot = path.join(process.cwd(), 'content/docs');
+  
+  // If input path is relative, make it absolute first to check
+  const absPath = path.resolve(enFilePath);
+  
+  if (!absPath.startsWith(docsRoot)) {
+     // Fallback or specific logic if file is not in content/docs
+     return enFilePath.replace('content/docs', 'content/docs-zh-CN');
+  }
+
+  const relativePath = path.relative(docsRoot, enFilePath);
+  return path.join(process.cwd(), 'content/docs-zh-CN', relativePath);
+}
+
+export async function translateContent(content, openai, model) {
+  const prompt = `
+You are a technical documentation translator for "ObjectStack".
+Translate the following MDX documentation from English to Chinese (Simplified).
+
+Rules:
+1. Preserve all MDX frontmatter (keys and structure). only translate the values if they are regular text.
+2. Preserve all code blocks exactly as they are. Do not translate code comments unless they are purely explanatory and not part of the logic.
+3. Use professional software terminology (e.g. "ObjectStack", "ObjectQL", "ObjectUI" should strictly remain in English).
+4. "Local-First" translate to "本地优先".
+5. "Protocol-Driven" translate to "协议驱动".
+6. Maintain the original markdown formatting (links, bold, italics).
+
+Content to translate:
+---
+${content}
+---
+`;
+
+  try {
+    const response = await openai.chat.completions.create({
+      model: model,
+      messages: [{ role: 'user', content: prompt }],
+      temperature: 0.1,
+    });
+
+    return response.choices[0].message.content.trim();
+  } catch (error) {
+    console.error('Translation failed:', error);
+    throw error;
+  }
+}