docs: add translating option with OpenAI (#109)

Author: seokju-na

docs/README.md

@@ -24,4 +24,7 @@ just docs-gen reference --lang=ko
 
 # Generate specific reference documentations with glob pattern.
 just docs-gen reference --pattern='Tree/Methods/*'
+
+# Translate with OpenAI. Or pass api token with environment variables. (/docs/.env)
+just docs-gen reference --translate-ai-token="<OpenAI API Key>"
 ```

docs/gen/cli.ts

@@ -1,6 +1,12 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Cli } from 'clipanion';
+import dotenv from 'dotenv';
 import { ReferenceCommand } from './commands/reference';
 
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: path.join(dirname, '..', '.env') });
+
 const [node, app, ...args] = process.argv;
 
 const cli = new Cli({

docs/gen/commands/reference.ts

@@ -1,28 +1,30 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { Command, Option } from 'clipanion';
-import { isNotNil } from 'es-toolkit';
 import micromatch from 'micromatch';
+import OpenAI from 'openai';
 import type { DeclarationReflection } from 'typedoc';
+import { type ReferenceDoc, renderReferenceDoc } from '../doc';
 import { findRootDir } from '../fs';
 import { LanguageOption } from '../lang';
-import {
-  findCategory,
-  genErrors,
-  genExample,
-  genParameters,
-  genReturns,
-  genSignature,
-  genSummary,
-  runTypedoc,
-} from '../typedoc';
+import { translate } from '../translate';
+import { findCategory, getReferenceDoc, runTypedoc } from '../typedoc';
 
 export class ReferenceCommand extends Command {
   static paths = [['reference']];
 
   readonly patterns = Option.Array('-p,--pattern', []);
   readonly lang = LanguageOption;
   readonly withOutput = Option.Boolean('--with-output', true);
+  readonly translateAiToken = Option.String('--translate-ai-token', {
+    description:
+      'Translate documentation with OpenAI when the token is given. Only works when language options is not "en".',
+    env: 'TRANSLATE_AI_TOKEN',
+  });
+  readonly translateAiModel = Option.String('--translate-ai-model', {
+    description: 'AI model for when translating documentation with OpenAI. Default model is "gpt-4o".',
+    env: 'TRANSLATE_AI_MODEL',
+  });
 
   async execute() {
     const rootDir = await findRootDir();
@@ -36,7 +38,7 @@ export class ReferenceCommand extends Command {
     const references: Array<{
       name: string;
       category: string[];
-      doc: string;
+      doc: ReferenceDoc;
     }> = [];
     this.traverseReflections(project.children!, reflection => {
       const category = findCategory(reflection);
@@ -53,9 +55,13 @@ export class ReferenceCommand extends Command {
       references.push({
         name: reflection.name,
         category,
-        doc: this.genReferenceDoc(reflection),
+        doc: getReferenceDoc(reflection),
       });
     });
+
+    const ai =
+      this.translateAiToken != null && this.lang !== 'en' ? new OpenAI({ apiKey: this.translateAiToken }) : null;
+
     for (let i = 0; i < references.length; i += 1) {
       const reference = references[i]!;
       const filename =
@@ -64,7 +70,11 @@ export class ReferenceCommand extends Command {
           : path.join(this.lang, 'reference', ...reference.category, `${reference.name}.md`);
       const filepath = path.join(rootDir, 'docs', filename);
       await fs.mkdir(path.dirname(filepath), { recursive: true });
-      await fs.writeFile(filepath, reference.doc, 'utf8');
+      const doc =
+        ai != null
+          ? await translate(ai, reference.doc, this.lang, { model: this.translateAiModel as OpenAI.ChatModel })
+          : reference.doc;
+      await fs.writeFile(filepath, renderReferenceDoc(doc, this.lang), 'utf8');
       console.log(`[${i + 1}/${references.length}] ${filename} generated`);
     }
   }
@@ -83,23 +93,4 @@ export class ReferenceCommand extends Command {
       }
     }
   }
-
-  private genReferenceDoc(reflection: DeclarationReflection) {
-    const sig = reflection.signatures?.[0];
-    if (sig == null) {
-      throw new Error(`Signature not found: ${reflection.name}`);
-    }
-
-    const summary = genSummary(sig);
-    const signature = genSignature(sig, { lang: this.lang });
-    const parameters = genParameters(sig, { lang: this.lang });
-    const returns = genReturns(sig, { lang: this.lang });
-    const errors = genErrors(sig, { lang: this.lang });
-    const example = genExample(sig, { lang: this.lang });
-
-    return [`# ${reflection.name}`, summary, signature, parameters, returns, errors, example]
-      .flat()
-      .filter(isNotNil)
-      .join('\n\n');
-  }
 }

docs/gen/doc.ts

@@ -0,0 +1,106 @@
+import { isNotNil } from 'es-toolkit';
+import { escapeHtml, paramLIHtml, paramULHtml } from './html';
+import type { Language } from './lang';
+import { t } from './texts';
+
+export interface ParameterDoc {
+  name: string;
+  type: string;
+  required?: boolean;
+  description?: string;
+  children?: string | ParameterDoc[];
+}
+
+export interface ReturnsDoc {
+  type: string;
+  description?: string;
+  children?: string | ParameterDoc[];
+}
+
+export interface ReferenceDoc {
+  name: string;
+  summary?: string;
+  signature?: string;
+  parameters?: ParameterDoc[];
+  returns?: ReturnsDoc;
+  errors?: string[];
+  examples?: string;
+}
+
+function renderParameterDoc(doc: ParameterDoc, lang: Language, root = true): string {
+  const { name, type, required, description, children } = doc;
+  return paramLIHtml({
+    name,
+    type,
+    required,
+    description,
+    children:
+      typeof children === 'string'
+        ? `<p class="param-description">${escapeHtml(children)}</p>`
+        : Array.isArray(children) && children.length > 0
+          ? paramULHtml(children.map(x => renderParameterDoc(x, lang, false)))
+          : undefined,
+    root,
+    lang,
+  });
+}
+
+export function renderReferenceDoc(doc: ReferenceDoc, lang: Language): string {
+  const { name, summary, signature, parameters, returns, errors, examples } = doc;
+
+  const signatureDoc = signature != null ? [`## ${t('signature', lang)}`, '', signature].join('\n') : null;
+
+  const parametersDocs =
+    parameters != null && parameters.length > 0
+      ? [
+          `### ${t('parameters', lang)}`,
+          '',
+          paramULHtml(parameters.map(parameter => renderParameterDoc(parameter, lang))),
+        ].join('\n')
+      : null;
+
+  const returnsDoc =
+    returns != null
+      ? [
+          `### ${t('returns', lang)}`,
+          '',
+          paramULHtml(
+            paramLIHtml({
+              required: false,
+              type: returns.type,
+              description: returns.description,
+              children:
+                typeof returns.children === 'string'
+                  ? `<p class="param-description">${escapeHtml(returns.children)}</p>`
+                  : Array.isArray(returns.children) && returns.children.length > 0
+                    ? paramULHtml(returns.children.map(x => renderParameterDoc(x, lang, false)))
+                    : undefined,
+              root: true,
+              lang,
+            })
+          ),
+        ].join('\n')
+      : null;
+  const errorsDoc =
+    errors != null && errors.length > 0
+      ? [
+          `### ${t('errors', lang)}`,
+          '',
+          paramULHtml(
+            errors.map(error =>
+              paramLIHtml({
+                required: false,
+                type: 'Error',
+                description: error,
+                root: true,
+                lang,
+              })
+            )
+          ),
+        ].join('\n')
+      : null;
+  const examplesDoc = examples != null ? [`## ${t('examples', lang)}`, '', examples].join('\n') : null;
+  return [`# ${name}`, summary, signatureDoc, parametersDocs, returnsDoc, errorsDoc, examplesDoc]
+    .filter(isNotNil)
+    .join('\n\n');
+}

docs/gen/lang.ts

@@ -9,7 +9,7 @@ const LANGUAGES = ['en', 'ko'] as const;
 
 export type Language = (typeof LANGUAGES)[number];
 
-export const LanguageOption = Option.String('--lang', 'en', {
+export const LanguageOption = Option.String('-l,--lang', 'en', {
   description: 'Language to generate documentation',
   validator: isEnum(LANGUAGES),
 });

docs/gen/texts.ts

@@ -1,7 +1,7 @@
 import type { Language } from './lang';
 
 const texts = {
-  singature: {
+  signature: {
     en: 'Signature',
     ko: '시그니처',
   },
@@ -13,7 +13,7 @@ const texts = {
     en: 'Returns',
     ko: '반환 값',
   },
-  example: {
+  examples: {
     en: 'Examples',
     ko: '예제',
   },

docs/gen/translate.ts

@@ -0,0 +1,44 @@
+import type OpenAI from 'openai';
+import type { ReferenceDoc } from './doc';
+import type { Language } from './lang';
+
+interface Options {
+  /** @defaultValue 'gpt-4o' */
+  model?: OpenAI.ChatModel;
+}
+
+export async function translate(
+  ai: OpenAI,
+  doc: ReferenceDoc,
+  lang: Language,
+  options?: Options
+): Promise<ReferenceDoc> {
+  const prompt = `
+Always answer in the JSON format as given in the input, without triple backticks.
+Translate the following JSON to ${lang}.
+
+If translating in Korean, write the sentence in 해요 style.
+If translating in Korean, translate "Git Object" as "Git 개체".
+If translating in Korean, translate "Tree" as "트리".
+If translating in Korean, translate "Repository" as "리포지토리".
+If translating in Japanese, finish the sentence in ます style.
+Finish with a noun if it is a explanation for a parameter or a return value.
+
+===
+\`\`\`
+${JSON.stringify(doc, null, 2)}
+\`\`\`
+  `;
+
+  const response = await ai.chat.completions.create({
+    model: options?.model ?? 'gpt-4o',
+    messages: [{ role: 'user', content: prompt }],
+  });
+
+  const translatedItem = response.choices[0]?.message.content;
+  if (translatedItem == null) {
+    throw new Error(`API Error while translating ${doc.name} to ${lang}.`);
+  }
+  const translated = JSON.parse(translatedItem) as ReferenceDoc;
+  return { ...translated, name: doc.name };
+}