Fix path config and i18n for cli help #16

ParallelKim · 2025-03-24T16:08:41Z

Hello team,

I've confirmed that due to incorrect path configuration after file separation in the previous PR, log files were generated in the wrong location. 😿 I suspect other users might have experienced the same issue. I apologize for the inconvenience caused by my inexperience with the Node.js file system.

Key Changes

Improved CLI Flag Structure and Added i18n for Help
- Previously, the CLI help displayed all descriptions in Chinese, English, and Korean, which might have been confusing.
- Now, the locale option is recognized first, allowing the CLI help to support multilingual options.
- The help messages are now much cleaner and easier to understand. (Korean texts are from the system)
Clarified Path Usage
- Files referenced by the CLI tool are now set based on process.cwd().
- Markdown files for prompts referenced by the module are set based on import.meta.url.
- I have confirmed that the log generation issue from the previous PR is now resolved, and logs are being created in the correct path.
- I tested it from a different project to verify the correct path usage. The tests confirmed that translations were successful and log files were created in the correct location.
Preparations for Adding OpenAI API Types
- Currently, the code always uses the completions API. However, today I read that OpenAI recommends using the responses API for new users.
- So, I added a flag to choose api type to use(disabled now)
- Additionally, I plan to add the assistant API later to reduce token waste on system prompts and examples.
Check this: Responses vs. Chat Completions

I hope these changes will enhance the project's efficiency and improve the user experience. Please feel free to provide feedback or additional suggestions.

About Testing

Although I have considered the testing aspects mentioned in the previous PR, nothing has been finalized yet. I will think about it further and make additions.

Thank you for reviewing it. Have a lovely day. 😄

contain error that should fix

coderabbitai · 2025-03-24T16:08:51Z

📝 Walkthrough

Walkthrough

本次 PR 添加了一个用于翻译 Markdown 文件的 CLI 工具，支持保存 Markdown 语法、递归目录翻译、自动重试、详细日志记录以及从 URL 获取内容。改动包括新增描述文件、环境配置、CLI 入口、辅助函数和选项管理方式，同时重构了文件路径常量、API 调用逻辑、导入语句和类型定义，并对多语言注释（英文、中文、韩文）进行了更新。

Changes

文件或目录	变更摘要
`.cursorrules` `README-ko.md` `example.env`	新增描述文件；韩国文档小幅文字调整；新增环境配置文件及环境变量定义。
`src/cli/` (helper.ts, index.ts, main.ts, options.ts, processor.ts)	新增 CLI 辅助函数（设置默认值、参数校验、版本与目录展示）；移除 index.ts 中旧的导出；新增 CLI 入口（main.ts）实现多语言解析；重构选项管理，采用 OPTIONS 常量；调整导入项和类型路径（RuntimeOptions）。
`src/config/constants.ts` `src/index.ts`	更新日志路径常量（使用 process.cwd() 构造绝对路径），引入 MODULE_PATH、PROMPTS_DIR、OFFICIAL_OPENAI_URL_V1，并在入口文件中替换 LOG_DIR 为 DEFAULT_LOG_DIR。
`src/services/` (api.ts, file.ts, openai.ts)	更新翻译逻辑，调整 API 方法调用（选择 translateTextWithCompletionsModule）；重组导入顺序；删除 getDefaultApiKey 函数，并对文件路径引用作出调整。
`src/types/` (common.ts, index.ts, option.ts)	新增类型文件 common.ts（定义 DirectoryStats、ChatData、ApiType）；移除旧接口定义（index.ts）；新增选项和运行时配置相关接口（option.ts）。
`src/utils/` (i18n.ts, logger.ts, validator.ts)	更新多语言文档与注释；调整 logger.ts 的导入格式；修改 validator.ts 中正则表达式，增加对韩文字符的支持。

Sequence Diagram(s)

sequenceDiagram
    participant U as 用户
    participant M as CLI Main
    participant H as CLI Helper
    participant O as Options 模块
    participant P as Processor 模块
    participant A as API 服务

    U->>M: 输入命令行参数
    M->>H: 调用 setDefault 与 checkArgument
    M->>O: 应用并解析 CLI 选项（多语言支持）
    M->>P: 根据参数调用 processInputPath 或 processUrlContent
    P->>A: 调用 translateText 进行翻译
    A-->>P: 返回翻译结果
    P-->>M: 返回处理结果
    M-->>U: 输出翻译结果与日志信息

Possibly related PRs

feat：增加 url 参数并更新文档 #2: 与本次改动共享 CLI 工具增强中的日志和重试机制，代码功能关联紧密。
build: 更新项目版本至 1.0.8 #8: 双方均涉及命令行参数和选项处理的改进，特别是新参数的引入。
ci: 添加翻译任务并优化 CI 工作流 #10: 两个 PR 均添加了翻译功能，涉及 OpenAI 模型的使用，具备直接的代码级联系。

Poem

我是一只跳跃的小兔，代码森林中漫步欢娱，
每一行改动如晨曦般闪耀，
CLI 工具翻译万语千言，
日志和选项齐整如同跳跃的音符，
环境配置指引前路，
多语注释让世界更加宽广，
我在代码的田野上欢唱着未来的梦想！

✨ Finishing Touches

📝 Generate Docstrings

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Generate unit testing code for this file.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai generate unit testing code for this file.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and generate unit testing code.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai plan to trigger planning for file edits and PR creation.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 2

🧹 Nitpick comments (9)

src/types/common.ts (1)
6-9: 消息角色枚举可以进一步优化

ChatData 接口定义了聊天数据的结构，但消息角色类型可以考虑使用枚举或单独的类型定义，提高代码的可维护性。
+export type ChatRole = 'developer' | 'user' | 'assistant';
+
 export interface ChatData {
   model: string;
-  messages: { role: 'developer' | 'user' | 'assistant'; content: string }[];
+  messages: { role: ChatRole; content: string }[];
 }
README-ko.md (1)
194-195: 示例输出缺少代码语言标记

示例输出的代码块缺少语言标识符，建议添加以提高语法高亮的准确性。
-```
+```text
 📂 디렉토리 구조: /path/to/src
🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

194-194: Fenced code blocks should have a language specified
null

(MD040, fenced-code-language)
src/cli/helper.ts (4)
14-21: 建议改进类型定义并考虑错误处理

函数实现基本正确，但有两点建议：

注释中提到了"TODO: specify type"，建议将any类型替换为更具体的类型，比如Record<string, unknown>或创建专门的接口

未对defaultApiKey为空的情况做处理，如果获取失败可能导致后续API调用出错
-export async function setDefault(argv: any) {
+export async function setDefault(argv: Record<string, unknown>) {
  // TODO: specify type
  const defaultApiKey = await getDefaultApiKey();

  argv['api-key'] = argv['api-key'] || process.env.API_KEY || defaultApiKey;
  argv['openai-url'] = argv['openai-url'] || process.env.OPENAI_URL || DEFAULT_OPENAI_URL;
  argv['model'] = argv['model'] || process.env.MODEL || DEFAULT_MODEL;
}
26-38: 参数验证逻辑合理，但类型需改进

验证逻辑确保了输入参数的正确性，包括必须提供input或url（但不能同时提供）以及url的有效性验证。建议将any类型替换为更具体的类型。
-export function checkArgument(argv: any) {
+export function checkArgument(argv: { input?: string; url?: string }): boolean {
  // TODO: specify type
  if (!argv.input && !argv.url) {
    throw new Error(t('cli.input.file.required'));
  }
  if (argv.input && argv.url) {
    throw new Error(t('cli.input.mutually.exclusive'));
  }
  if (argv.url && !isValidUrl(argv.url)) {
    throw new Error(t('cli.url.invalid'));
  }
  return true;
}
67-72: 避免在辅助函数中直接退出程序

在辅助函数中直接调用process.exit(0)会中断程序执行，阻止任何清理操作或其他未完成的任务。建议重构为返回版本信息，让调用者决定是否退出程序。
-export function showVersion() {
+export function showVersion(): string {
  const packageJsonPath = path.join(__dirname, '../..', 'package.json');
  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-  console.log(`version: ${packageJson.version}`);
-  process.exit(0);
+  return `version: ${packageJson.version}`;
}
79-112: 目录路径展示功能实现良好，但存在改进空间

函数实现了显示目录结构的功能，逻辑清晰

文件过滤器的实现简洁有效

同样存在直接调用process.exit(0)的问题

建议将退出程序的控制权交还给调用方，以便更好地管理程序流程。
export function showDirectoryPath(argv: CliOptions) {
  const pathToShow = path.resolve(argv.path);
  console.log(`\n📂 Directory structure: ${pathToShow}`);
  console.log('.');

  // 创建文件过滤器...

  printDirectoryStructure(
    // ...参数保持不变...
  );

  if (!argv.input && !argv.url) {
-    process.exit(0);
+    return true; // 表示完成并准备退出
  }
+  return false; // 表示继续执行
}
src/cli/main.ts (2)
15-43: CLI选项解析逻辑清晰，但类型转换可优化

解析逻辑首先处理locale参数，然后设置语言环境，这种方式很好。最后返回时的类型转换as unknown as CliOptions不够安全，可考虑使用类型守卫或验证函数确保返回值符合CliOptions接口。
export async function parseCliOptions(): Promise<CliOptions> {
  // ...代码保持不变...

  const argv = await yargsInstance.argv;

-  return argv as unknown as CliOptions;
+  // 验证argv是否符合CliOptions接口
+  const options = argv as Record<string, unknown>;
+  // 可以添加简单验证确保必要字段存在
+  return options as CliOptions;
}
48-62: 选项应用函数设计合理

applyOptions函数实现简洁明了，遍历OPTIONS对象应用到yargs实例。唯一的小问题是第55行的type: option.type as any类型转换，最好避免使用any。可以使用更具体的类型如yargs.OptionType或类似定义。
-      type: option.type as any,
+      type: option.type as yargs.Options['type'],
src/services/api.ts (1)
34-38: API选择逻辑的更新

API选择逻辑的更新现在检查options.openaiUrl是否包含OFFICIAL_OPENAI_URL_V1，这是一个更灵活的方法。不过，有一些被注释掉的条件检查代码（关于apiType的检查），这些代码应该被移除或取消注释。

建议修复如下：
  if (options.openaiUrl.includes(OFFICIAL_OPENAI_URL_V1)) {
-   // if (options.apiType === 'completions') {
    return translateTextWithCompletionsModule(options.apiKey, options.directoryOptions, data);
-   // }
  }
或者如果这是为未来的功能做准备，应添加清晰的TODO注释：
  if (options.openaiUrl.includes(OFFICIAL_OPENAI_URL_V1)) {
+   // TODO: 当支持多种API类型时取消注释此代码
    // if (options.apiType === 'completions') {
    return translateTextWithCompletionsModule(options.apiKey, options.directoryOptions, data);
    // }
  }

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0408a0d and 6425aa0.

⛔ Files ignored due to path filters (1)

package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (19)

.cursorrules (1 hunks)
README-ko.md (10 hunks)
example.env (1 hunks)
src/cli/helper.ts (1 hunks)
src/cli/index.ts (0 hunks)
src/cli/main.ts (1 hunks)
src/cli/options.ts (2 hunks)
src/cli/processor.ts (1 hunks)
src/config/constants.ts (1 hunks)
src/index.ts (1 hunks)
src/services/api.ts (2 hunks)
src/services/file.ts (1 hunks)
src/services/openai.ts (2 hunks)
src/types/common.ts (1 hunks)
src/types/index.ts (0 hunks)
src/types/option.ts (1 hunks)
src/utils/i18n.ts (2 hunks)
src/utils/logger.ts (1 hunks)
src/utils/validator.ts (1 hunks)

💤 Files with no reviewable changes (2)

src/cli/index.ts
src/types/index.ts

🧰 Additional context used

🧬 Code Definitions (7)

src/cli/helper.ts (5)

src/config/constants.ts (2)

DEFAULT_OPENAI_URL (18-18)

DEFAULT_MODEL (20-20)

src/utils/i18n.ts (1)

t (34-52)

src/utils/validator.ts (1)

isValidUrl (1-24)

src/types/option.ts (1)

CliOptions (21-45)

src/services/file.ts (1)

printDirectoryStructure (181-246)

src/types/option.ts (1)

src/types/common.ts (1)

ApiType (11-11)

src/index.ts (1)

src/config/constants.ts (1)

DEFAULT_LOG_DIR (14-14)

src/cli/main.ts (4)

src/utils/i18n.ts (1)

setLocale (12-18)

src/cli/helper.ts (2)

setDefault (14-21)

checkArgument (26-38)

src/types/option.ts (1)

CliOptions (21-45)

src/cli/options.ts (1)

OPTIONS (7-215)

src/services/api.ts (2)

src/config/constants.ts (2)

OFFICIAL_OPENAI_URL_V1 (19-19)

PROMPTS_DIR (11-11)

src/services/openai.ts (2)

translateTextWithCompletionsModule (35-53)

translateTextWithRestApi (55-89)

src/cli/options.ts (2)

src/types/option.ts (2)

CliOptions (21-45)

OptionDefinition (7-19)

src/config/constants.ts (3)

DEFAULT_LOG_FILE (15-15)

DEFAULT_LOG_DIR (14-14)

EXECUTE_PATH (13-13)

src/utils/i18n.ts (1)

src/config/i18n.ts (2)

SupportedLocale (9-9)

messages (11-145)

🪛 LanguageTool

README-ko.md

[duplication] ~21-~21: Possible typo: you repeated a word.
Context: ...# 기능 - OpenAI의 모델이 지원하는 모든 언어로 마크다운 파일 번역 - 번역 중 마크다운 구문 유지 - 재귀 디렉토리 번역 지원 - 실패한 번역에 ...

(ENGLISH_WORD_REPEAT_RULE)

[uncategorized] ~56-~56: Loose punctuation mark.
Context: ... 문제를 확인하기 위해 ESLint를 실행합니다. - lint:fix: TypeScript 파일에서 린트 문제를 자동으로 수정합니다. - `f...