@alauda/doom 0.14.0 → 0.14.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/cli/export.js CHANGED
@@ -14,6 +14,7 @@ export const exportCommand = new Command('export')
14
14
  .action(async function (root) {
15
15
  setNodeEnv('production');
16
16
  const { port, host, ...globalOptions } = this.optsWithGlobals();
17
+ const { base } = globalOptions;
17
18
  let { config } = await loadConfig(root, globalOptions);
18
19
  const outDir = config.outDir;
19
20
  if (!(await pathExists(path.resolve(outDir, 'index.html'), 'file'))) {
@@ -82,7 +83,7 @@ export const exportCommand = new Command('export')
82
83
  const exportPdf = async (sidebarItems, lang = config.lang) => {
83
84
  await generatePdf({
84
85
  pages: collectPages(sidebarItems),
85
- outFile: `${removeBothEndsSlashes(config.base) || config.title}-${lang}.pdf`,
86
+ outFile: `${removeBothEndsSlashes(base || config.base) || config.title}-${lang}.pdf`,
86
87
  ...commonOptions,
87
88
  });
88
89
  };
package/lib/cli/index.js CHANGED
@@ -28,6 +28,7 @@ program
28
28
  })
29
29
  .option('-c, --config <config>', 'Specify the path to the config file')
30
30
  .option('-v <version>', 'Specify the version of the documentation')
31
+ .option('-b, --base <base>', 'Override the base of the documentation')
31
32
  .option('-p, --prefix <prefix>', 'Specify the prefix of the documentation base')
32
33
  .option('-f, --force [boolean]', 'Force to fetch latest reference remotes or scaffolding templates, otherwise use local cache', (value) => !!value && value !== 'false', false)
33
34
  .option('-i, --ignore [boolean]', 'Ignore internal routes', (value) => !!value && value !== 'false', false)
@@ -1,5 +1,5 @@
1
1
  import { type DoomConfig, type GlobalCliOptions } from '../utils/index.js';
2
- export declare function loadConfig(root?: string, { config: configFile, prefix, v: version, ignore, force, }?: GlobalCliOptions): Promise<{
2
+ export declare function loadConfig(root?: string, { config: configFile, base, prefix, v: version, ignore, force, }?: GlobalCliOptions): Promise<{
3
3
  config: DoomConfig;
4
4
  filepath?: string;
5
5
  }>;
@@ -121,7 +121,7 @@ const getCommonConfig = (config, cliRoot, configFilePath, version, ignore, force
121
121
  const findConfig = (basePath) => {
122
122
  return DEFAULT_EXTENSIONS.map((ext) => basePath + ext).find(fs.existsSync);
123
123
  };
124
- export async function loadConfig(root, { config: configFile, prefix, v: version, ignore, force, } = {}) {
124
+ export async function loadConfig(root, { config: configFile, base, prefix, v: version, ignore, force, } = {}) {
125
125
  let configFilePath;
126
126
  if (configFile) {
127
127
  configFilePath = path.resolve(configFile);
@@ -176,7 +176,7 @@ export async function loadConfig(root, { config: configFile, prefix, v: version,
176
176
  lang: commonConfig.lang,
177
177
  root: commonConfig.root,
178
178
  });
179
- let base = addLeadingSlash(mergedConfig.base || '/');
179
+ base = addLeadingSlash(base || mergedConfig.base || '/');
180
180
  if (normalizedVersion && normalizedVersion !== 'unversioned') {
181
181
  base = removeTrailingSlash(base) + `/${normalizedVersion}`;
182
182
  }
@@ -214,7 +214,7 @@ export async function loadConfig(root, { config: configFile, prefix, v: version,
214
214
  addTrailingSlash(mergedConfig.outDir) + normalizedVersion;
215
215
  }
216
216
  else {
217
- mergedConfig.outDir = `dist${normalizedVersion === 'unversioned' ? `/unversioned${base}` : base}`;
217
+ mergedConfig.outDir = `dist${normalizedVersion === 'unversioned' ? `${base}unversioned` : base}`;
218
218
  }
219
219
  if (mergedConfig.builderConfig?.server?.open === true) {
220
220
  mergedConfig.builderConfig.server.open = mergedConfig.base;
@@ -1,14 +1,18 @@
1
1
  import { Command } from 'commander';
2
2
  export interface I18nFrontmatter {
3
3
  i18n?: {
4
- title?: {
5
- en?: string;
6
- };
4
+ title?: Record<string, string>;
7
5
  additionalPrompts?: string;
8
6
  disableAutoTranslation?: boolean;
9
7
  };
10
8
  sourceSHA?: string;
11
9
  title?: string;
12
10
  }
13
- export declare const translate: (zhContent: string, enContent?: string, additionalPrompts?: string) => Promise<string>;
11
+ export declare const translate: ({ source, sourceContent, target, targetContent, additionalPrompts, }: {
12
+ source: string;
13
+ sourceContent: string;
14
+ target: string;
15
+ targetContent?: string;
16
+ additionalPrompts?: string;
17
+ }) => Promise<string>;
14
18
  export declare const translateCommand: Command;
@@ -7,12 +7,16 @@ import matter from 'gray-matter';
7
7
  import { AzureOpenAI } from 'openai';
8
8
  import { pRateLimit } from 'p-ratelimit';
9
9
  import { cyan } from 'yoctocolors';
10
+ import { normalizeImgSrc, } from '../plugins/replace/normalize-img-src.js';
11
+ import { mdProcessor, mdxProcessor } from '../plugins/replace/utils.js';
10
12
  import { pathExists } from '../utils/index.js';
11
13
  import { loadConfig } from './load-config.js';
12
- import { mdProcessor, mdxProcessor } from '../plugins/replace/utils.js';
13
- import { normalizeImgSrc } from '../plugins/replace/normalize-img-src.js';
14
+ const LANGUAGE_CODES = {
15
+ zh: '中文',
16
+ en: '英文',
17
+ };
14
18
  let openai;
15
- export const translate = async (zhContent, enContent = '', additionalPrompts = '') => {
19
+ export const translate = async ({ source, sourceContent, target, targetContent = '', additionalPrompts, }) => {
16
20
  if (!openai) {
17
21
  openai = new AzureOpenAI({
18
22
  endpoint: process.env.AZURE_OPENAI_ENDPOINT ||
@@ -21,16 +25,18 @@ export const translate = async (zhContent, enContent = '', additionalPrompts = '
21
25
  apiVersion: process.env.OPENAI_API_VERSION || '2025-01-01-preview',
22
26
  });
23
27
  }
28
+ const sourceLang = LANGUAGE_CODES[source];
29
+ const targetLang = LANGUAGE_CODES[target];
24
30
  const { choices } = await openai.beta.chat.completions.parse({
25
31
  messages: [
26
32
  {
27
33
  role: 'system',
28
34
  content: `
29
35
  ## 角色
30
- 你是一位专业的技术文档工程师,擅长写作高质量的英文技术分档。请你帮我准确地将以下中文翻译成英文,风格与英文技术文档保持一致。
36
+ 你是一位专业的技术文档工程师,擅长写作高质量的${targetLang}技术分档。请你帮我准确地将以下${sourceLang}翻译成${targetLang},风格与${targetLang}技术文档保持一致。
31
37
 
32
38
  ## 规则
33
- - 第一条消息为需要翻译的最新中文内容,第二条消息为之前翻译过的但内容可能过期的英文内容,如果没有翻译过则为空
39
+ - 第一条消息为需要翻译的最新${sourceLang}内容,第二条消息为之前翻译过的但内容可能过期的${targetLang}内容,如果没有翻译过则为空
34
40
  - 输入格式为 MDX 格式,输出格式也必须保留原始 MDX 格式,且不要额外包装在不必要的代码块中
35
41
  - 文档中的资源链接不要翻译和替换
36
42
  - MDX 组件中包含的内容需要翻译,MDX 组件参数的值不需要翻译,但以下这些特殊的 MDX 组件参数值需要翻译
@@ -43,13 +49,13 @@ export const translate = async (zhContent, enContent = '', additionalPrompts = '
43
49
 
44
50
  ## 策略
45
51
  分四步进行翻译工作,并打印每步的结果:
46
- 1. 根据中文内容直译成英文,保持原有格式,不要遗漏任何信息
52
+ 1. 根据${sourceLang}内容直译成${targetLang},保持原有格式,不要遗漏任何信息
47
53
  2. 根据第一步直译的结果,指出其中存在的具体问题,要准确描述,不宜笼统的表示,也不需要增加原文不存在的内容或格式,包括不仅限于
48
- - 不符合英文表达习惯,明确指出不符合的地方
54
+ - 不符合${targetLang}表达习惯,明确指出不符合的地方
49
55
  - 语句不通顺,指出位置,不需要给出修改意见,意译时修复
50
56
  - 晦涩难懂,模棱两可,不易理解,可以尝试给出解释
51
- 3. 根据第一步直译的结果和第二步指出的问题,重新进行意译,保证内容的原意的基础上,使其更易于理解,更符合英文技术文档的表达习惯,同时保持原有的格式不变
52
- 4. 当存在之前翻译的英文内容时,将第三步的结果按句子与之前的英文内容细致地比较,如果翻译结果意思相近,仅仅表达方式不同的,只需要保留之前的英文内容即可,不需要重复翻译
57
+ 3. 根据第一步直译的结果和第二步指出的问题,重新进行意译,保证内容的原意的基础上,使其更易于理解,更符合${targetLang}技术文档的表达习惯,同时保持原有的格式不变
58
+ 4. 当存在之前翻译的${targetLang}内容时,将第三步的结果按句子与之前的${targetLang}内容细致地比较,如果翻译结果意思相近,仅仅表达方式不同的,只需要保留之前的${targetLang}内容即可,不需要重复翻译
53
59
 
54
60
  最终只需要输出最后一步的结果,不需要输出之前步骤的结果。
55
61
 
@@ -58,11 +64,11 @@ ${additionalPrompts}
58
64
  },
59
65
  {
60
66
  role: 'user',
61
- content: zhContent,
67
+ content: sourceContent,
62
68
  },
63
69
  {
64
70
  role: 'user',
65
- content: enContent,
71
+ content: targetContent,
66
72
  },
67
73
  ],
68
74
  model: 'gpt-4o-mini',
@@ -81,17 +87,27 @@ const limit = pRateLimit({
81
87
  export const translateCommand = new Command('translate')
82
88
  .description('Translate the documentation')
83
89
  .argument('[root]', 'Root directory of the documentation')
90
+ .option('-s, --source <language>', 'Document source language', 'zh')
91
+ .option('-t, --target <language>', 'Document target language', 'en')
84
92
  .action(async function (root) {
85
- const { config } = await loadConfig(root, this.optsWithGlobals());
93
+ const { source, target, ...globalOptions } = this.optsWithGlobals();
94
+ if (!Object.hasOwn(LANGUAGE_CODES, source) ||
95
+ !Object.hasOwn(LANGUAGE_CODES, target) ||
96
+ source === target) {
97
+ console.error(`Translate from language \`${cyan(source)}\` to \`${cyan(target)}\` is not supported.`);
98
+ process.exitCode = 1;
99
+ return;
100
+ }
101
+ const { config } = await loadConfig(root, globalOptions);
86
102
  const docsDir = config.root;
87
- const zhDir = path.resolve(docsDir, 'zh');
88
- const enDir = path.resolve(docsDir, 'en');
89
- if (!(await pathExists(zhDir, 'directory'))) {
90
- console.error(`The directory "${cyan(zhDir)}" does not exist.`);
103
+ const sourceDir = path.resolve(docsDir, source);
104
+ const targetDir = path.resolve(docsDir, target);
105
+ if (!(await pathExists(sourceDir, 'directory'))) {
106
+ console.error(`The directory "${cyan(sourceDir)}" does not exist.`);
91
107
  process.exitCode = 1;
92
108
  return;
93
109
  }
94
- const dirents = await fs.readdir(zhDir, {
110
+ const dirents = await fs.readdir(sourceDir, {
95
111
  recursive: true,
96
112
  withFileTypes: true,
97
113
  });
@@ -99,55 +115,61 @@ export const translateCommand = new Command('translate')
99
115
  if (!d.isFile() || !/\.mdx?$/.test(d.name)) {
100
116
  return;
101
117
  }
102
- const zhFilePath = path.resolve(d.parentPath ||
118
+ const sourceFilePath = path.resolve(d.parentPath ||
103
119
  // eslint-disable-next-line @typescript-eslint/no-deprecated
104
120
  d.path, d.name);
105
- const zhContent = await fs.readFile(zhFilePath, 'utf-8');
106
- const zhFrontmatter = matter(zhContent).data;
107
- if (zhFrontmatter.i18n?.disableAutoTranslation) {
121
+ const sourceContent = await fs.readFile(sourceFilePath, 'utf-8');
122
+ const sourceFrontmatter = matter(sourceContent).data;
123
+ if (sourceFrontmatter.i18n?.disableAutoTranslation) {
108
124
  return;
109
125
  }
110
126
  const sourceSHA = crypto
111
127
  .createHash('sha256')
112
- .update(zhContent)
128
+ .update(sourceContent)
113
129
  .digest('hex');
114
- const enFilePath = zhFilePath.replace(zhDir, enDir);
115
- let enContent;
116
- let enFrontmatter;
117
- if (await pathExists(enFilePath, 'file')) {
118
- enContent = await fs.readFile(enFilePath, 'utf-8');
119
- enFrontmatter = matter(enContent).data;
120
- if (enFrontmatter.i18n?.disableAutoTranslation ||
121
- enFrontmatter.sourceSHA === sourceSHA) {
130
+ const targetFilePath = sourceFilePath.replace(sourceDir, targetDir);
131
+ let targetContent;
132
+ let targetFrontmatter;
133
+ if (await pathExists(targetFilePath, 'file')) {
134
+ targetContent = await fs.readFile(targetFilePath, 'utf-8');
135
+ targetFrontmatter = matter(targetContent).data;
136
+ if (targetFrontmatter.i18n?.disableAutoTranslation ||
137
+ targetFrontmatter.sourceSHA === sourceSHA) {
122
138
  return;
123
139
  }
124
140
  }
125
141
  await limit(async () => {
126
- const relativePath = path.relative(docsDir, zhFilePath);
142
+ const relativePath = path.relative(docsDir, sourceFilePath);
127
143
  logger.info(`Translating ${cyan(relativePath)}`);
128
- const isMdx = zhFilePath.endsWith('.mdx');
144
+ const isMdx = sourceFilePath.endsWith('.mdx');
129
145
  const processor = isMdx ? mdxProcessor : mdProcessor;
130
- const ast = processor.parse(zhContent);
146
+ const ast = processor.parse(sourceContent);
131
147
  const normalizeImgSrcOptions = {
132
148
  localPublicBase: path.resolve(docsDir, 'public'),
133
- sourceBase: path.dirname(zhFilePath),
134
- targetBase: path.dirname(enFilePath),
135
- translating: 'en',
149
+ sourceBase: path.dirname(sourceFilePath),
150
+ targetBase: path.dirname(targetFilePath),
151
+ translating: [source, target],
136
152
  };
137
- enContent = await translate(processor.stringify({
138
- ...ast,
139
- children: ast.children.map((it) => normalizeImgSrc(it, normalizeImgSrcOptions)),
140
- }), enContent, enFrontmatter?.i18n?.additionalPrompts ??
141
- zhFrontmatter.i18n?.additionalPrompts);
142
- const { data, content } = matter(enContent);
143
- const newFrontmatter = { ...enFrontmatter, ...data };
153
+ targetContent = await translate({
154
+ source,
155
+ sourceContent: processor.stringify({
156
+ ...ast,
157
+ children: ast.children.map((it) => normalizeImgSrc(it, normalizeImgSrcOptions)),
158
+ }),
159
+ target,
160
+ targetContent,
161
+ additionalPrompts: targetFrontmatter?.i18n?.additionalPrompts ??
162
+ sourceFrontmatter.i18n?.additionalPrompts,
163
+ });
164
+ const { data, content } = matter(targetContent);
165
+ const newFrontmatter = { ...targetFrontmatter, ...data };
144
166
  newFrontmatter.sourceSHA = sourceSHA;
145
- if (zhFrontmatter.i18n?.title?.en) {
146
- newFrontmatter.title = zhFrontmatter.i18n.title.en;
167
+ if (sourceFrontmatter.i18n?.title?.[target]) {
168
+ newFrontmatter.title = sourceFrontmatter.i18n.title[target];
147
169
  }
148
- enContent = matter.stringify(content.startsWith('\n') ? content : '\n' + content, newFrontmatter);
149
- await fs.mkdir(path.dirname(enFilePath), { recursive: true });
150
- await fs.writeFile(enFilePath, enContent);
170
+ targetContent = matter.stringify(content.startsWith('\n') ? content : '\n' + content, newFrontmatter);
171
+ await fs.mkdir(path.dirname(targetFilePath), { recursive: true });
172
+ await fs.writeFile(targetFilePath, targetContent);
151
173
  logger.info(`${cyan(relativePath)} translated`);
152
174
  });
153
175
  }));
@@ -1,11 +1,12 @@
1
1
  import type { Content } from 'mdast';
2
2
  import type { NormalizedReferenceSource } from './types.js';
3
- export declare const normalizeImgSrc: (content: Content, { refSource, localPublicBase, publicBase, sourceBase, targetBase, force, translating, }: {
3
+ export interface NormalizeImgSrcOptions {
4
4
  refSource?: NormalizedReferenceSource;
5
5
  localPublicBase: string;
6
6
  publicBase?: string;
7
7
  sourceBase: string;
8
8
  targetBase: string;
9
9
  force?: boolean;
10
- translating?: string;
11
- }) => Content;
10
+ translating?: readonly [string, string];
11
+ }
12
+ export declare const normalizeImgSrc: (content: Content, { refSource, localPublicBase, publicBase, sourceBase, targetBase, force, translating, }: NormalizeImgSrcOptions) => Content;
@@ -30,10 +30,13 @@ export const normalizeImgSrc = (content, { refSource, localPublicBase, publicBas
30
30
  return `/_remotes/${refSource.name}/${imageSrc}`;
31
31
  }
32
32
  else if (!RELATIVE_URL_PATTERN.test(src)) {
33
- if (translating &&
34
- src.startsWith('/zh/') &&
35
- fs.existsSync(path.resolve(localPublicBase, translating, src.replace('/zh/', '')))) {
36
- return src.replace('/zh/', `/${translating}/`);
33
+ if (translating) {
34
+ const [source, target] = translating;
35
+ const sourcePrefix = `/${source}/`;
36
+ if (src.startsWith(sourcePrefix) &&
37
+ fs.existsSync(path.resolve(localPublicBase, target, src.replace(sourcePrefix, '')))) {
38
+ return src.replace(sourcePrefix, `/${target}/`);
39
+ }
37
40
  }
38
41
  return src;
39
42
  }
@@ -8,6 +8,7 @@ export type BaseServeOptions = Parameters<typeof serve>[0];
8
8
  export type ServeOptions = Omit<BaseServeOptions, 'config'>;
9
9
  export interface GlobalCliOptions {
10
10
  config?: string;
11
+ base?: string;
11
12
  prefix?: string;
12
13
  v?: string;
13
14
  ignore?: boolean;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alauda/doom",
3
- "version": "0.14.0",
3
+ "version": "0.14.2",
4
4
  "type": "module",
5
5
  "description": "Doctor Doom making docs.",
6
6
  "repository": {
@@ -83,7 +83,7 @@
83
83
  "@types/cli-progress": "^3.11.6",
84
84
  "@types/ejs": "^3.1.5",
85
85
  "@types/fs-extra": "^11.0.4",
86
- "@types/node": "^18.19.78",
86
+ "@types/node": "^18.19.79",
87
87
  "@types/picomatch": "^3.0.2",
88
88
  "@types/react": "^18.3.18",
89
89
  "@types/react-dom": "^18.3.5",
@@ -96,7 +96,7 @@
96
96
  "prettier-plugin-pkg": "^0.18.1",
97
97
  "simple-git-hooks": "^2.11.1",
98
98
  "typescript": "^5.8.2",
99
- "typescript-eslint": "^8.25.0"
99
+ "typescript-eslint": "^8.26.0"
100
100
  },
101
101
  "publishConfig": {
102
102
  "access": "public"