@preferred-natural-language/cli

Preferred Natural Language

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

🌐 Languages

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

✨ Key Features

• 🤖 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

🚀 Quick Start

Installation

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

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

CLI Usage

# 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

MCP Integration

For Claude Code

• Install the plugin:

  From Marketplaces:

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

  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 ./.claude-plugin
  /plugin install preferred-natural-language@pnl-dev-marketplace
  

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

• 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

• 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 Gemini CLI

• Install the extension:

  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 .
  

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

• 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
  

• 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

• 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
  

🌍 Supported Languages (70+)

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

CLI Output Languages (Full i18n)

Language	Code	Native Name
English	en, en-US, en-GB	English
Chinese (Simplified)	zh-CN	简体中文
Japanese	ja-JP	日本語
Korean	ko-KR	한국어
Russian	ru-RU	Русский
Portuguese	pt-BR, pt-PT	Português
Spanish	es-ES	Español
French	fr-FR	Français
German	de-DE	Deutsch

All Supported Languages

View the complete list of 70+ supported languages →

🔍 Detection Priority Chain

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

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

📁 Configuration

Configuration File (Highest Priority)

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

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

Environment Variables

# Platform-specific (priority 2)
export CLAUDE_CODE_NATURAL_LANGUAGE="zh-CN"
export GEMINI_CLI_NATURAL_LANGUAGE="ja-JP"

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

Using CLI

# Create config file interactively
pnl set zh-CN

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

🏗️ Architecture

Project Structure

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 plugin (marketplace)
│   ├── marketplace.json          # Marketplace config
│   └── pnl/                      # Plugin root
│       ├── .claude-plugin/plugin.json
│       ├── .mcp.json             # MCP server config
│       ├── 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

Design Philosophy

• 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

🧪 Testing

Run Tests

# 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)

🛠️ Development

Setup

# 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

Available Scripts

# 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)

📖 API Reference

Programmatic Usage

import { LanguageDetector, SUPPORTED_LANGUAGES } from '@preferred-natural-language/cli';

// Detect language
const detector = new LanguageDetector();
const result = await detector.detect();
// { language: 'zh-CN', source: 'os-locale', confidence: 'high' }

// List supported languages
console.log(SUPPORTED_LANGUAGES);
// { 'en': 'English', 'zh-CN': 'Chinese (Simplified)', ... }

MCP Server API

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

Type Definitions

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';

🤝 Contributing

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

Development Workflow

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

Commit Message Format

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

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

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.5 <[e-mail]>"

📄 License

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

🙏 Acknowledgments

• 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

📞 Support

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

Made with ❤️ for the AI community

Supporting Claude Code and Gemini CLI