优选自然语言

一个跨平台的自然语言偏好检测工具，通过MCP（模型上下文协议）为AI助手提供服务。

🌐 语言

• 🇺🇸 英语 ← 当前
• 🇨🇳 简体中文

✨ 主要功能

• 🤖 自动语言检测: AI自动以您偏好的语言进行交流
• 🔌 MCP集成: 与Claude Code和Gemini CLI无缝集成
• 🎯 优先级链检测: 5级检测优先级系统
• 🌍 70多种语言: 全面支持语言和地区变体
• 🔧 多种检测方法: 配置文件、环境变量、操作系统区域设置
• 📝 完整的i18n: CLI输出支持10种语言（en, zh, ja, ko, ru, pt, es, fr, de）
• 🧪 100%测试覆盖: 100多个测试用例，高覆盖率

🚀 快速开始

安装

bash

全局安装（推荐）

npm install -g @preferred-natural-language/cli

或者使用npx（无需安装）

npx @preferred-natural-language/cli detect

CLI使用

bash

检测当前语言偏好

pnl detect

设置语言偏好

pnl set zh-CN

显示详细信息

pnl show

列出所有支持的语言

pnl list

启动MCP服务器（用于编程使用）

pnl mcp

MCP集成

对于Claude Code

1. 安装插件：

   从市场安装：
   bash
   /plugin marketplace add wakanachan/preferred-natural-language
   /plugin install pnl@pnl-dev-marketplace

   本地开发：
   bash

   克隆仓库

   git clone https://github.com/wakanachan/preferred-natural-language
   cd preferred-natural-language

   作为本地市场安装

   /plugin marketplace add ./
   /plugin install preferred-natural-language@pnl-dev-marketplace

2. 重启Claude Code 以加载插件（安装后需要）

3. 自动语言检测：

   • Claude Code会自动检测并使用您的首选语言
   • 通过MCP资源访问语言偏好：language://preference
   • 使用MCP工具：detect-language、set-language、list-languages

4. 可用的斜杠命令：

   /pnl:detect-language # 检测当前语言偏好
   /pnl:set-language # 设置语言偏好（例如，zh-CN, ja-JP）
   /pnl:list-languages # 列出所有70多种支持的语言

对于Gemini CLI

1. 安装扩展：

   从GitHub安装：
   bash
   gemini extensions install https://github.com/wakanachan/preferred-natural-language

   本地开发：
   bash

   克隆仓库

   git clone https://github.com/wakanachan/preferred-natural-language
   cd preferred-natural-language

   从本地路径安装（根目录包含gemini-extension.json）

   gemini extensions install .

   或者使用链接命令

   gemini extensions link .

2. 重启Gemini CLI 以加载扩展（更改仅在重启后生效）

3. 更新扩展（当有更新可用时）：
   bash

   更新特定扩展

   gemini extensions update preferred-natural-language

   或者一次性更新所有扩展

   gemini extensions update --all

4. 自动语言检测：

   • Gemini会在会话开始时自动检测您的首选语言
   • 扩展通过GEMINI.md提供上下文
   • MCP服务器提供语言工具和资源

5. 可用的斜杠命令：

   /detect-language # 检测当前语言偏好
   /set-language # 设置语言偏好（例如，zh-CN, ja-JP）
   /list-languages # 列出所有70多种支持的语言#### 通用MCP服务器配置

对于不喜欢安装插件的用户，您可以在任何兼容MCP的客户端中手动配置MCP服务器。

使用npx

将以下配置添加到您的MCP客户端设置中：

json
{
"mcpServers": {
"pnl-mcp": {
"command": "npx",
"args": [
"@preferred-natural-language/cli",
"mcp"
],
"env": {}
}
}
}

对于Windows

json
{
"mcpServers": {
"pnl-mcp": {
"command": "cmd",
"args": [
"/c",
"npx",
"@preferred-natural-language/cli",
"mcp"
],
"env": {}
}
}
}

使用全局安装

如果您已全局安装了该包：

bash
npm install -g @preferred-natural-language/cli

然后用以下方式配置您的MCP客户端：

json
{
"mcpServers": {
"pnl-mcp": {
"command": "pnl",
"args": ["mcp"],
"env": {}
}
}
}

独立使用

您也可以直接运行MCP服务器进行测试：

bash

使用npx（无需安装）

npx @preferred-natural-language/cli mcp

或者如果已全局安装

pnl mcp

服务器通过标准输入输出提供了相同的MCP功能：

• 资源: language://preference - 自动加载的语言偏好
• 提示: use-preferred-language - AI语言指令
• 工具: detect-language, set-language, list-languages

🌍 支持的语言 (70+)

我们支持70多种语言和地区变体，并为10种主要语言提供完整的国际化输出：

CLI 输出语言（完整国际化）

语言	代码	本地名称
英语	en, en-US, en-GB	English
中文（简体）	zh-CN	简体中文
日语	ja-JP	日本語
韩语	ko-KR	한국어
俄语	ru-RU	Русский
葡萄牙语	pt-BR, pt-PT	Português
西班牙语	es-ES	Español
法语	fr-FR	Français
德语	de-DE	Deutsch

所有支持的语言

查看支持的70多种语言的完整列表 →

🔍 检测优先级链

该工具使用严格的五级优先级来检测语言偏好：

1. 🥇 配置文件 (.preferred-language.json) - 最高优先级
2. 🥈 自定义环境变量
   • CLAUDE_CODE_NATURAL_LANGUAGE
   • GEMINI_CLI_NATURAL_LANGUAGE
3. 🥉 操作系统区域设置 (通过os-locale包)
4. 🏅 标准环境变量
   • 优先级: LANGUAGE > LC_ALL > LC_MESSAGES > LANG
5. 🌐 HTTP Accept-Language 头 (针对Web环境)
6. 🏁 回退 (en-US) - 最低优先级

📁 配置

配置文件（最高优先级）

在项目根目录创建.preferred-language.json：

json
{
"language": "zh-CN",
"fallback": "en-US"
}

环境变量

bash

平台特定（优先级2）

export CLAUDE_CODE_NATURAL_LANGUAGE="zh-CN"
export GEMINI_CLI_NATURAL_LANGUAGE="ja-JP"

其他（即将推出）

标准Unix变量（优先级4）

export LANGUAGE="zh_CN:en_US"
export LC_ALL="zh_CN.UTF-8"
export LANG="zh_CN.UTF-8"

使用CLI

bash

交互式创建配置文件

pnl set zh-CN

这将创建一个包含以下内容的.preferred-language.json：

{ "language": "zh-CN", "fallback": "en-US" }

🏗️ 架构

项目结构

preferred-natural-language/
├── src/ # 源代码
│ ├── languageDetector.ts # 核心五级优先级检测
│ ├── types.ts # 类型定义
│ ├── languageNames.ts # 70多种语言映射
│ ├── config.ts # 配置路径
│ ├── index.ts # 统一导出
│ ├── cli/ # CLI命令 (Commander.js)
│ │ ├── commands/ # detect, set, show, list, mcp
│ │ ├── utils/ # 显示工具
│ │ └── index.ts # CLI入口点
│ ├── i18n/ # 国际化
│ │ ├── index.ts # I18n类
│ │ └── locales/ # 10种语言文件
│ └── mcp/ # MCP服务器
│ └── server.ts # 资源 + 提示 + 工具
├── bin/
│ └── pnl.js # CLI入口点
├── tests/ # 测试套件
│ ├── unit/ # 单元测试
│ ├── integration/ # 集成测试
│ └── e2e/ # 端到端测试
├── .claude-plugin/ # Claude Code市场配置
│ └── marketplace.json # 指向./claude-code-plugin
├── claude-code-plugin/ # Claude Code插件
│ ├── .claude-plugin/plugin.json
│ ├── .mcp.json # MCP服务器配置
│ ├── agents/ # 代理定义
│ ├── commands/ # 斜杠命令
│ └── scripts/start-mcp.js # 智能MCP启动器
├── gemini-extension.json # Gemini CLI扩展清单
├── GEMINI.md # Gemini上下文文件
├── commands/ # Gemini斜杠命令 (.toml)
└── scripts/start-mcp.js # 共享MCP启动器### 设计理念

• 单一包: 所有代码都在 @preferred-natural-language/cli 中
• 轻量级插件: Claude/Gemini 集成是配置层
• 智能启动器: 插件通过智能启动器使用 pnl mcp 子命令
• 无代码重复: 插件层委托给 CLI 包

🧪 测试

运行测试

bash

所有测试 (单元 + 集成 + 端到端)

npm test

特定测试套件

npm run test:unit # 快速单元测试
npm run test:integration # 集成测试
npm run test:e2e # 端到端测试

开发

npm run test:watch # 监视模式
npm run test:coverage # 附带覆盖率报告
npm run test:ci # CI 模式 (无监视)

🛠️ 开发

设置

bash

克隆仓库

git clone https://github.com/wakanachan/preferred-natural-language.git
cd preferred-natural-language

安装依赖

npm install

构建

npm run build

运行测试

npm test

可用脚本

bash

构建

npm run build # 构建项目

测试

npm run test:unit # 单元测试
npm run test:integration # 集成测试
npm run test:e2e # 端到端测试
npm run test:coverage # 附带覆盖率
npm run test:pr # PR 验证 (单元 + 集成)

📖 API 参考

MCP 服务器 API

MCP 服务器提供：

资源 (自动加载):

• language://preference - 用户的语言偏好 (JSON)

提示:

• use-preferred-language - 为 AI 生成语言指令

工具:

• detect-language - 检测当前语言
• set-language(language, fallback?) - 设置语言偏好
• list-languages() - 列出所有 70 多种支持的语言

类型定义

typescript
interface LanguageDetectionResult {
language: string; // BCP-47 代码 (例如, 'zh-CN')
source: DetectionSource; // 检测源
confidence: 'high' | 'medium' | 'low';
}

type DetectionSource =
| config-file:${string} // 配置文件路径
| 'GEMINI_CLI_NATURAL_LANGUAGE'
| 'CLAUDE_CODE_NATURAL_LANGUAGE'
| 'os-locale'
| 'LANGUAGE' | 'LC_ALL' | 'LC_MESSAGES' | 'LANG'
| 'HTTP_ACCEPT_LANGUAGE'
| 'fallback';

🤝 贡献

我们欢迎贡献！请参阅我们的 贡献指南 以获取详细信息。

开发工作流程

1. 分叉仓库
2. 创建一个特性分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (推荐使用中文提交信息)
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

提交信息格式

bash
git commit -m "feat: 添加新功能描述

• 详细说明 1
• 详细说明 2

🤖 由 Claude Code 生成

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com"

📄 许可证

此项目根据 MIT 许可证发布 - 详情请参见 LICENSE 文件。

🙏 致谢

• Model Context Protocol (MCP) - 用于 AI 集成标准
• Anthropic - 用于 Claude Code 平台
• Google - 用于 Gemini CLI 平台
• os-locale - 用于跨平台区域设置检测
• Commander.js - 用于 CLI 框架
• TypeScript - 用于类型安全

📞 支持

• 🐛 报告 Bug
• 💡 请求功能
• 💬 讨论

---