#!/usr/bin/env node /** * translate-docs.js — Bidirectional translation for Mintlify i18n * * Usage: * node scripts/translate-docs.js # Chinese → English (default) * node scripts/translate-docs.js --to zh # English → Chinese * node scripts/translate-docs.js --to en # Chinese → English * node scripts/translate-docs.js # custom dirs or single file * node scripts/translate-docs.js --force # ignore cache, re-translate all * node scripts/translate-docs.js --provider openai # use OpenAI (default) * node scripts/translate-docs.js --provider anthropic # use Anthropic Claude * * Directory structure: * essentials/ ← Chinese (source of truth) * essentials-en/ ← English (generated) * developer-docs/ ← Chinese (source of truth) * developer-docs-en/ ← English (generated) * * Environment: * OPENAI_API_KEY — required when --provider openai (default) * ANTHROPIC_API_KEY — required when --provider anthropic */ if (typeof window === 'undefined') { 'use strict' const fs = require('fs') const path = require('path') const crypto = require('crypto') // 本地开发：自动加载 .env 文件（CI 环境变量优先，不会被覆盖） ;(function loadDotEnv() { const envPath = path.resolve('.env') if (!fs.existsSync(envPath)) return for (const line of fs.readFileSync(envPath, 'utf8').split('\n')) { const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/) if (m && !process.env[m[1]]) { process.env[m[1]] = m[2].trim().replace(/^["'](.*)["']$/, '$1') } } })() // ── Provider config ─────────────────────────────────────────────────────────── const PROVIDERS = { openai: { model: 'gpt-5.2', baseURL: 'https://chatgpt.waffo.co/api/openai/v1', envKey: 'OPENAI_API_KEY', cacheVer: 'openai:gpt-5.2:v2:data-dictionary', }, anthropic: { model: 'claude-sonnet-4-6', envKey: 'ANTHROPIC_API_KEY', cacheVer: 'anthropic:claude-sonnet-4-6:v2:data-dictionary', }, } const CONCURRENCY = 3 const CACHE_PATH = path.resolve('.translate-cache.json') const TERMINOLOGY_PATH = path.resolve('DATA_DICTIONARY.md') // ── System prompts ─────────────────────────────────────────────────────────── const SYSTEM_ZH_TO_EN = `You are a professional technical documentation translator specializing in fintech and payment systems. Translate the Markdown/MDX content from Chinese to English. STRICT RULES — follow exactly, no exceptions: 1. STRUCTURE: Preserve all Markdown structure — headings (#/##/###), bullet lists, numbered lists, tables, blockquotes, horizontal rules. 2. FRONTMATTER: Keep all YAML keys unchanged. Translate only the VALUES of title and description fields. 3. MDX COMPONENTS: Keep all JSX/MDX tags exactly — , , , , , , , , , , , , , , , etc. - Translate text content INSIDE component tags. - Translate visible attribute VALUES (e.g. title="查看详情" → title="View Details"). - NEVER change attribute names (title=, cols=, icon=, href=, type=, etc.). 4. CODE BLOCKS: Preserve EVERYTHING inside fenced code blocks exactly — do not translate code, variable names, comments, or strings. 5. INLINE CODE: Preserve all backtick-wrapped text exactly (e.g. \`error.code\`, \`PaymentIntent\`). 6. URLS & PATHS: Preserve all URLs, file paths, anchor links, and route strings exactly. 7. SPACING: Preserve blank lines and spacing between sections exactly as the source. 8. TONE: Natural, professional developer-documentation English. Sentence case for headings. 9. TERMINOLOGY: Use DATA_DICTIONARY.md as the mandatory data dictionary. Locked Waffo/product/API terms must remain exactly as their canonical terms in every language; do not translate, localize, transliterate, or substitute them. 10. OUTPUT: Return ONLY the translated content. No preamble, no explanation, no trailing notes.` const SYSTEM_EN_TO_ZH = `You are a professional technical documentation translator specializing in fintech and payment systems. Translate the Markdown/MDX content from English to Chinese (Simplified). STRICT RULES — follow exactly, no exceptions: 1. STRUCTURE: Preserve all Markdown structure — headings (#/##/###), bullet lists, numbered lists, tables, blockquotes, horizontal rules. 2. FRONTMATTER: Keep all YAML keys unchanged. Translate only the VALUES of title and description fields. 3. MDX COMPONENTS: Keep all JSX/MDX tags exactly — , , , , , , , , , , , , , , , etc. - Translate text content INSIDE component tags. - Translate visible attribute VALUES (e.g. title="View Details" → title="查看详情"). - NEVER change attribute names (title=, cols=, icon=, href=, type=, etc.). 4. CODE BLOCKS: Preserve EVERYTHING inside fenced code blocks exactly — do not translate code, variable names, comments, or strings. 5. INLINE CODE: Preserve all backtick-wrapped text exactly (e.g. \`error.code\`, \`PaymentIntent\`). 6. URLS & PATHS: Preserve all URLs, file paths, anchor links, and route strings exactly. 7. SPACING: Preserve blank lines and spacing between sections exactly as the source. 8. TONE: Natural, professional Chinese technical documentation. Use standard simplified Chinese. 9. TERMINOLOGY: Use DATA_DICTIONARY.md as the mandatory data dictionary. Locked Waffo/product/API terms must remain exactly as their canonical terms in every language; do not translate, localize, transliterate, or substitute them. 10. OUTPUT: Return ONLY the translated content. No preamble, no explanation, no trailing notes.` function loadTerminologyDictionary() { if (!fs.existsSync(TERMINOLOGY_PATH)) return '' const dictionary = fs.readFileSync(TERMINOLOGY_PATH, 'utf8').trim() if (!dictionary) return '' return `\n\nTERMINOLOGY DATA DICTIONARY — mandatory:\n${dictionary}\n\nApply this dictionary exactly. Terms marked as locked must remain as their canonical term in every language. If the content conflicts with this dictionary, follow the dictionary.` } // ── Provider adapters ──────────────────────────────────────────────────────── async function callOpenAI(apiKey, model, baseURL, systemPrompt, content) { const OpenAI = require('openai') const client = new OpenAI({ apiKey, ...(baseURL && { baseURL }) }) const res = await client.chat.completions.create({ model, max_completion_tokens: 8192, messages: [ { role: 'system', content: systemPrompt }, { role: 'user', content }, ], }) return res.choices[0].message.content } async function callAnthropic(apiKey, model, systemPrompt, content) { const Anthropic = require('@anthropic-ai/sdk') const client = new Anthropic({ apiKey }) const res = await client.messages.create({ model, max_tokens: 8192, system: systemPrompt, messages: [{ role: 'user', content }], }) return res.content[0].text } // ── 重试 ────────────────────────────────────────────────────────────────────── const MAX_RETRIES = 3 const RETRY_DELAY = 5000 const CHUNK_LIMIT = 6000 async function withRetry(fn, retries = MAX_RETRIES) { for (let attempt = 1; attempt <= retries; attempt++) { try { return await fn() } catch (err) { const isLast = attempt === retries if (isLast) throw err const delay = RETRY_DELAY * attempt process.stderr.write(` retry ${attempt}/${retries - 1} (${err.message}), waiting ${delay / 1000}s...\n`) await new Promise(r => setTimeout(r, delay)) } } } // ── 分片翻译（大文件按 H2 拆分）──────────────────────────────────────────────── function splitByH2(content) { const parts = content.split(/(?=\n## )/g) return parts.length > 1 ? parts : [content] } async function translateChunked(callFn, content) { if (Buffer.byteLength(content, 'utf8') <= CHUNK_LIMIT) { return withRetry(() => callFn(content)) } const chunks = splitByH2(content) if (chunks.length === 1) { return withRetry(() => callFn(content)) } const results = [] for (let i = 0; i < chunks.length; i++) { process.stderr.write(` chunk ${i + 1}/${chunks.length} (${Buffer.byteLength(chunks[i], 'utf8')} bytes)\n`) results.push(await withRetry(() => callFn(chunks[i]))) } return results.join('\n') } async function translateWithOpenAI(apiKey, model, baseURL, systemPrompt, content) { return translateChunked(c => callOpenAI(apiKey, model, baseURL, systemPrompt, c), content) } async function translateWithAnthropic(apiKey, model, systemPrompt, content) { return translateChunked(c => callAnthropic(apiKey, model, systemPrompt, c), content) } // ── Cache ───────────────────────────────────────────────────────────────────── function loadCache() { try { return JSON.parse(fs.readFileSync(CACHE_PATH, 'utf8')) } catch { return {} } } function saveCache(cache) { fs.writeFileSync(CACHE_PATH, JSON.stringify(cache, null, 2), 'utf8') } function cacheKeyHash(cacheVer, direction, content) { return `${cacheVer}:${direction}:${crypto.createHash('md5').update(content).digest('hex')}` } // ── File processing ─────────────────────────────────────────────────────────── function ensureDir(filePath) { const dir = path.dirname(filePath) if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }) } function needsTranslation(content, direction) { const hasChinese = /[\u4e00-\u9fff]/.test(content) if (direction === 'zh2en') return hasChinese if (direction === 'en2zh') return !hasChinese return false } async function processFile({ inputPath, outputPath, provider, apiKey, model, baseURL, cacheVer, cache, force, direction, systemPrompt }) { const content = fs.readFileSync(inputPath, 'utf8') if (!needsTranslation(content, direction)) { ensureDir(outputPath) fs.copyFileSync(inputPath, outputPath) return 'copied' } const key = cacheKeyHash(cacheVer, direction, content) if (!force && cache[key] && fs.existsSync(outputPath)) { return 'cached' } const translated = provider === 'openai' ? await translateWithOpenAI(apiKey, model, baseURL, systemPrompt, content) : await translateWithAnthropic(apiKey, model, systemPrompt, content) ensureDir(outputPath) fs.writeFileSync(outputPath, translated, 'utf8') cache[key] = { output: outputPath, ts: new Date().toISOString() } return 'translated' } // ── Concurrency pool ────────────────────────────────────────────────────────── async function pool(tasks, concurrency) { let i = 0 async function worker() { while (i < tasks.length) await tasks[i++]() } await Promise.all(Array.from({ length: concurrency }, worker)) } // ── Directory scan ──────────────────────────────────────────────────────────── // Files to skip (Mintlify examples, non-business content) const SKIP_FILES = new Set(['test.mdx', 'code.mdx', 'images.mdx', 'markdown.mdx', 'navigation.mdx', 'reusable-snippets.mdx', 'settings.mdx']) function findMdFiles(dir) { const files = [] for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { const full = path.join(dir, entry.name) if (entry.isDirectory()) files.push(...findMdFiles(full)) else if ((entry.name.endsWith('.md') || entry.name.endsWith('.mdx')) && !SKIP_FILES.has(entry.name)) files.push(full) } return files } // ── CLI ─────────────────────────────────────────────────────────────────────── function parseArgs(argv) { const raw = argv.slice(2) const force = raw.includes('--force') const provIdx = raw.indexOf('--provider') const provider = provIdx !== -1 ? raw[provIdx + 1] : 'openai' const toIdx = raw.indexOf('--to') const toLang = toIdx !== -1 ? raw[toIdx + 1] : 'en' const rest = raw.filter((a, i) => !['--force','--provider','--to'].includes(a) && raw[i - 1] !== '--provider' && raw[i - 1] !== '--to' ) return { force, provider, toLang, positional: rest } } async function main() { const { force, provider, toLang, positional } = parseArgs(process.argv) if (!['en', 'zh'].includes(toLang)) { console.error(`ERROR: --to must be "en" or "zh", got "${toLang}"`) process.exit(1) } if (!PROVIDERS[provider]) { console.error(`ERROR: Unknown provider "${provider}". Choose: openai | anthropic`) process.exit(1) } const { model, baseURL, envKey, cacheVer } = PROVIDERS[provider] const apiKey = process.env[envKey] if (!apiKey) { console.error(`ERROR: ${envKey} is not set.`) console.error(provider === 'openai' ? ' export OPENAI_API_KEY=sk-...' : ' export ANTHROPIC_API_KEY=sk-ant-...') process.exit(1) } const direction = toLang === 'en' ? 'zh2en' : 'en2zh' const systemPrompt = `${toLang === 'en' ? SYSTEM_ZH_TO_EN : SYSTEM_EN_TO_ZH}${loadTerminologyDictionary()}` const dirLabel = toLang === 'en' ? 'Chinese → English' : 'English → Chinese' // Default directory mappings // essentials/ = Chinese source // essentials-en/ = English translated const DEFAULT_DIRS_ZH2EN = [ { input: 'essentials', output: 'en/essentials' }, { input: 'developer-docs', output: 'en/developer-docs' }, ] const DEFAULT_DIRS_EN2ZH = [ { input: 'en/essentials', output: 'essentials' }, { input: 'en/developer-docs', output: 'developer-docs' }, ] const inputArg = positional[0] const outputArg = positional[1] let dirPairs if (inputArg) { const out = outputArg || inputArg.replace(/\/?$/, toLang === 'en' ? '-en' : '') dirPairs = [{ input: inputArg, output: out }] } else { const defaults = toLang === 'en' ? DEFAULT_DIRS_ZH2EN : DEFAULT_DIRS_EN2ZH dirPairs = defaults.filter(d => fs.existsSync(d.input)) if (!dirPairs.length) { console.error(`ERROR: No source directories found for ${dirLabel}`) process.exit(1) } } // Collect all file pairs const filePairs = [] for (const { input, output } of dirPairs) { const stat = fs.existsSync(input) && fs.statSync(input) if (!stat) { console.error(`ERROR: "${input}" does not exist`); process.exit(1) } if (stat.isDirectory()) { for (const f of findMdFiles(input)) { filePairs.push({ input: f, output: path.join(output, path.relative(input, f)) }) } } else { filePairs.push({ input, output }) } } if (!filePairs.length) { console.log('No .md/.mdx files found.'); return } const label = dirPairs.map(d => `${d.input} → ${d.output}`).join(', ') console.log(`\n${dirLabel}: ${label}`) console.log(`Provider: ${provider} Model: ${model} Files: ${filePairs.length} Concurrency: ${CONCURRENCY}\n`) const cache = loadCache() const counts = { translated: 0, cached: 0, copied: 0, failed: 0 } const start = Date.now() let done = 0 const total = filePairs.length const tasks = filePairs.map(({ input, output }) => async () => { const rel = path.relative(process.cwd(), input) try { const status = await processFile({ inputPath: input, outputPath: output, provider, apiKey, model, baseURL, cacheVer, cache, force, direction, systemPrompt }) done++ counts[status]++ const icon = { translated: '✓', cached: '·', copied: '→' }[status] || '?' console.log(`[${done}/${total}] ${icon} ${rel} (${status})`) } catch (err) { done++ counts.failed++ console.error(`[${done}/${total}] ✗ ${rel} ERROR: ${err.message}`) } }) await pool(tasks, CONCURRENCY) saveCache(cache) const elapsed = ((Date.now() - start) / 1000).toFixed(1) console.log(`\nDone in ${elapsed}s — translated: ${counts.translated}, cached: ${counts.cached}, copied: ${counts.copied}, failed: ${counts.failed}`) console.log(`Output: ${dirPairs.map(d => path.resolve(d.output)).join(', ')}`) } main().catch(err => { console.error(err); process.exit(1) }) }

​はじめに

​統合方法

​コアコンセプト

​Webhook

​SDK

​ツールとリファレンス

​ユースケース

はじめに

統合方法

コアコンセプト

Webhook

SDK

ツールとリファレンス

ユースケース