A cross-platform natural language preference detection tool for AI assistants through MCP (Model Context Protocol).

• 🇺🇸 English ← Current
• 🇨🇳 简体中文

• 🤖 Automatic Language Detection: AI automatically communicates in your preferred language
• 🔌 MCP Integration: Seamless integration with Claude Code and Gemini CLI
• 🎯 Priority Chain Detection: 5-level detection priority system
• 🌍 70+ Languages: Comprehensive language and regional variant support
• 🔧 Multiple Detection Methods: Config files, environment variables, OS locale
• 📝 Full i18n: CLI output in 10 languages (en, zh, ja, ko, ru, pt, es, fr, de)
• 🧪 100% Tested: 100+ test cases, high coverage

# Install globally (recommended)
npm install -g @preferred-natural-language/cli

# Or use with npx (no installation)
npx @preferred-natural-language/cli detect

# Detect current language preference
pnl detect

# Set language preference
pnl set zh-CN

# Show detailed information
pnl show

# List all supported languages
pnl list

# Start MCP server (for programmatic use)
pnl mcp

1. Install the plugin:

   From Marketplaces:

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

   For Local Development:

   # Clone the repository
   git clone https://github.com/wakanachan/preferred-natural-language
   cd preferred-natural-language
   
   # Install as local marketplace
   /plugin marketplace add ./
   /plugin install preferred-natural-language@pnl-dev-marketplace

2. Restart Claude Code to load the plugin (required after installation)

3. Automatic Language Detection:

   • Claude Code automatically detects and uses your preferred language
   • Access language preference via MCP Resource: language://preference
   • Use MCP tools: detect-language, set-language, list-languages

4. Available Slash Commands:

   /pnl:detect-language   # Detect current language preference
   /pnl:set-language      # Set language preference (e.g., zh-CN, ja-JP)
   /pnl:list-languages    # List all 70+ supported languages
   

1. Install the extension:

   From Github:

   gemini extensions install https://github.com/wakanachan/preferred-natural-language

   For Local Development:

   # Clone the repository
   git clone https://github.com/wakanachan/preferred-natural-language
   cd preferred-natural-language
   
   # Install from local path (root directory contains gemini-extension.json)
   gemini extensions install .
   
   # Or use link command
   gemini extensions link .

2. Restart Gemini CLI to load the extension (changes only apply on restart)

3. Update Extension (when updates are available):

   # Update specific extension
   gemini extensions update preferred-natural-language
   
   # Or update all extensions at once
   gemini extensions update --all

4. Automatic Language Detection:

   • Gemini automatically detects your preferred language at session start
   • The extension provides context through GEMINI.md
   • MCP server provides language tools and resources

5. Available Slash Commands:

   /detect-language   # Detect current language preference
   /set-language      # Set language preference (e.g., zh-CN, ja-JP)
   /list-languages    # List all 70+ supported languages
   

For users who prefer not to install plugins, you can configure the MCP server manually in any MCP-compatible client.

Using npx

Add this configuration to your MCP client settings:

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

For Windows

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

Using Global Installation

If you have installed the package globally:

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

Then configure your MCP client with:

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

Standalone Usage

You can also run the MCP server directly for testing:

# Using npx (no installation required)
npx @preferred-natural-language/cli mcp

# Or if installed globally
pnl mcp

The server provides the same MCP capabilities via stdio communication:

• Resource: language://preference - Auto-loaded language preference
• Prompt: use-preferred-language - AI language instruction
• Tools: detect-language, set-language, list-languages

We support 70+ languages and regional variants, with full i18n output for 10 major languages:

View the complete list of 70+ supported languages →

The tool detects language preferences using a strict 5-level priority:

1. 🥇 Configuration File (.preferred-language.json) - Highest priority
2. 🥈 Custom Environment Variables
   • CLAUDE_CODE_NATURAL_LANGUAGE
   • GEMINI_CLI_NATURAL_LANGUAGE
3. 🥉 OS Locale Settings (via os-locale package)
4. 🏅 Standard Environment Variables
   • Priority: LANGUAGE > LC_ALL > LC_MESSAGES > LANG
5. 🌐 HTTP Accept-Language Header (for web environments)
6. 🏁 Fallback (en-US) - Lowest priority

Create .preferred-language.json in your project root:

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

# Platform-specific (priority 2)
export CLAUDE_CODE_NATURAL_LANGUAGE="zh-CN"
export GEMINI_CLI_NATURAL_LANGUAGE="ja-JP"
# others（coming soon）

# Standard Unix variables (priority 4)
export LANGUAGE="zh_CN:en_US"
export LC_ALL="zh_CN.UTF-8"
export LANG="zh_CN.UTF-8"

# Create config file interactively
pnl set zh-CN

# This creates .preferred-language.json with:
# { "language": "zh-CN", "fallback": "en-US" }

preferred-natural-language/
├── src/                          # Source code
│   ├── languageDetector.ts       # Core 5-level priority detection
│   ├── types.ts                  # Type definitions
│   ├── languageNames.ts          # 70+ language mappings
│   ├── config.ts                 # Configuration paths
│   ├── index.ts                  # Unified exports
│   ├── cli/                      # CLI commands (Commander.js)
│   │   ├── commands/             # detect, set, show, list, mcp
│   │   ├── utils/                # Display utilities
│   │   └── index.ts              # CLI entry point
│   ├── i18n/                     # Internationalization
│   │   ├── index.ts              # I18n class
│   │   └── locales/              # 10 language files
│   └── mcp/                      # MCP server
│       └── server.ts             # Resource + Prompt + Tools
├── bin/
│   └── pnl.js                    # CLI entry point
├── __tests__/                    # Test suites
│   ├── unit/                     # Unit tests
│   ├── integration/              # Integration tests
│   └── e2e/                      # End-to-end tests
├── .claude-plugin/               # Claude Code marketplace config
│   └── marketplace.json          # Points to ./claude-code-plugin
├── claude-code-plugin/           # Claude Code plugin
│   ├── .claude-plugin/plugin.json
│   ├── .mcp.json                 # MCP server config
│   ├── agents/                   # Agent definitions
│   ├── commands/                 # Slash commands
│   └── scripts/start-mcp.js      # Smart MCP launcher
├── gemini-extension.json         # Gemini CLI extension manifest
├── GEMINI.md                     # Gemini context file
├── commands/                     # Gemini slash commands (.toml)
└── scripts/start-mcp.js          # Shared MCP launcher

• Single Package: All code in @preferred-natural-language/cli
• Lightweight Plugins: Claude/Gemini integrations are configuration layers
• Smart Launchers: Plugins use pnl mcp subcommand via smart launchers
• No Code Duplication: Plugin layers delegate to CLI package

# All tests (unit + integration + e2e)
npm test

# Specific test suites
npm run test:unit           # Fast unit tests
npm run test:integration    # Integration tests
npm run test:e2e            # End-to-end tests

# Development
npm run test:watch          # Watch mode
npm run test:coverage       # With coverage report
npm run test:ci             # CI mode (no watch)

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

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Building
npm run build              # Build project

# Testing
npm run test:unit          # Unit tests
npm run test:integration   # Integration tests
npm run test:e2e           # E2E tests
npm run test:coverage      # With coverage
npm run test:pr            # PR validation (unit + integration)

The MCP server provides:

Resource (auto-loaded):

• language://preference - User's language preference (JSON)

Prompt:

• use-preferred-language - Generates language instruction for AI

Tools:

• detect-language - Detect current language
• set-language(language, fallback?) - Set language preference
• list-languages() - List all 70+ supported languages

interface LanguageDetectionResult {
  language: string;           // BCP-47 code (e.g., 'zh-CN')
  source: DetectionSource;    // Detection source
  confidence: 'high' | 'medium' | 'low';
}

type DetectionSource =
  | `config-file:${string}`  // Config file path
  | 'GEMINI_CLI_NATURAL_LANGUAGE'
  | 'CLAUDE_CODE_NATURAL_LANGUAGE'
  | 'os-locale'
  | 'LANGUAGE' | 'LC_ALL' | 'LC_MESSAGES' | 'LANG'
  | 'HTTP_ACCEPT_LANGUAGE'
  | 'fallback';

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (Chinese commit messages preferred)
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

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

- 详细说明 1
- 详细说明 2

🤖 Generated with Claude Code

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

This project is licensed under the MIT License - see the LICENSE file for details.

• Model Context Protocol (MCP) - For AI integration standards
• Anthropic - For Claude Code platform
• Google - For Gemini CLI platform
• os-locale - For cross-platform locale detection
• Commander.js - For CLI framework
• TypeScript - For type safety

• 🐛 Report a Bug
• 💡 Request a Feature
• 💬 Discussions