AutoLang - Automatic Minecraft Chat Translation

AutoLang is a sophisticated Minecraft plugin designed to break down language barriers by providing real-time, bi-directional chat translation. Built with performance and flexibility in mind, it seamlessly integrates with your existing server setup while providing extensive customization options for server administrators.

Table of Contents

1. Core Features
2. Installation Guide
3. Configuration Reference
4. Language Support
5. Command Reference
6. Advanced Usage
7. Troubleshooting
8. Performance Tuning
9. API Integration
10. Frequently Asked Questions

Core Features

Intelligent Language Detection

AutoLang employs a sophisticated two-tier detection system:

1. Primary Detection: Uses the Lingua library, a highly accurate language identification system that analyzes character patterns and statistical properties of text
2. Fallback Detection: Falls back to a lightweight heuristic-based detector if Lingua cannot be initialized or if performance is a concern

Translation Architecture

• Asynchronous Processing: All translation operations are performed asynchronously to prevent server lag
• Smart Caching Layer: Implements an LRU (Least Recently Used) cache with configurable size and TTL to minimize redundant translations
• Bidirectional Translation: Maintains message context for accurate bidirectional translations between any supported language pairs

Player Experience

• Seamless Integration: Works with existing chat plugins and permission systems
• Client-Language Awareness: Detects and respects player client language settings (Paper servers only)
• Non-Intrusive: Players can opt-out of translation or view original messages
• Context Preservation: Maintains formatting, colors, and clickable elements in translated messages

Installation Guide

System Requirements

• Minecraft Server: Paper/Spigot 1.21.1 or higher (recommended for full feature support)
• Java: Java 21 or later
• Memory: Minimum 4GB RAM (6GB+ recommended for larger servers)
• Storage: 1GB free space (more if using local translation models)

Step-by-Step Installation

1. Download the latest AutoLang JAR from the Modrinth releases page
2. Place the JAR file in your server's plugins/ directory
3. Start your server to generate the default configuration
4. Stop the server and edit plugins/AutoLang/config.yml to your preferences
5. Restart your server to apply changes

Initial Setup Recommendations

1. For New Servers:

   • Start with default settings
   • Test basic functionality with a few languages
   • Gradually enable additional features

2. For Existing Servers:

   • Test in a staging environment first
   • Consider starting with translation disabled (autodetect.enabled: false)
   • Gradually roll out to staff before enabling for all players

Configuration Reference

Core Settings

# Default server language (must be a configured language code)
default-language: "en"

# Maximum concurrent translation threads
max-translation-threads: 4

# Maximum time to wait for a translation (milliseconds)
translation-timeout-ms: 3000

# Enable debug logging (verbose)
debug: false

### Language Configuration

AutoLang provides flexible language management with support for automatic language discovery and manual overrides. The configuration is structured to be both powerful and easy to use.

```yaml
languages:
  # Auto-fetch supported languages from LibreTranslate
  # When enabled, the plugin will query your LibreTranslate instance for available languages
  auto-from-libretranslate: true
  
  # Whitelist specific language codes (case-insensitive)
  # Example: ["en", "es", "fr", "de", "ja"]
  # If empty, all languages from the source will be included
  include: []
  
  # Blacklist specific language codes
  # Example: ["zh-tw", "pt-br"] (to exclude specific regional variants)
  # These languages will be excluded even if included above or in static
  exclude: []
  
  # Static language definitions
  # These are used in three scenarios:
  # 1. As fallback if auto-fetching fails
  # 2. To add languages not provided by your LibreTranslate instance
  # 3. To override properties of auto-fetched languages
  static:
    - code: "en"
      name: "English"
    - code: "es"
      name: "Español"
  
  # Override display names for specific language codes
  # This only affects how languages are displayed to players
  # Format: {code: "display name"}
  overrides:
    - code: "zh"
      name: "简体中文"  # Simplified Chinese
    - code: "zh-tw"
      name: "繁體中文"  # Traditional Chinese
    - code: "pt-br"
      name: "Português (Brasil)"  # Brazilian Portuguese

# Language detection settings
detection:
  # Minimum confidence threshold (0.0 to 1.0)
  # Lower values may increase false positives
  # Higher values may fail to detect some languages
  confidence-threshold: 0.75
  
  # Number of messages to analyze before making a detection
  # More messages increase accuracy but delay detection
  min-messages: 3
  
  # Maximum message length to analyze (characters)
  # Longer messages provide more context but use more resources
  max-message-length: 1000

# Client language integration (Paper servers only)
client-locale:
  # Enable/disable client language detection
  enabled: true
  
  # Automatically set the detected language
  auto-accept: true
  
  # Notify players when their language is auto-detected
  notify-on-detect: true
  
  # Message format for language detection notification
  # Available placeholders: %player%, %lang%, %code%
  detection-message: "&aYour chat language has been set to %lang%"

# Formatting options for translated messages
formatting:
  # Format for translated messages
  # Available placeholders: 
  # %player% - Original message sender
  # %message% - Translated message
  # %original% - Original message (if show-original is true)
  # %lang% - Target language name
  # %code% - Target language code
  format: "&7[%lang%] &f%player%&7: &r%message%"
  
  # Show original message after translation
  show-original: false
  
  # Format for original message when show-original is true
  original-format: " &7(Original: %original%)"

# Message cooldown settings
cooldown:
  # Global cooldown between messages (seconds)
  global: 0.5
  
  # Per-player cooldown (seconds)
  per-player: 2.0
  
  # Message to show when cooldown is active
  # Available placeholders: %time%
  message: "&cPlease wait %time% seconds before sending another message."

# Anti-spam settings
anti-spam:
  # Enable/disable anti-spam
  enabled: true
  
  # Maximum similar messages allowed within time window
  max-similar: 3
  
  # Time window for similar message detection (seconds)
  time-window: 10
  
  # Message to show when anti-spam is triggered
  message: "&cPlease avoid sending similar messages in quick succession."

### Translation Engine Configuration

AutoLang supports multiple translation backends, each with its own configuration options. Choose the one that best fits your server's needs.

#### 1. LibreTranslate (Recommended)

LibreTranslate is an open-source translation API that supports over 100 languages. It can be self-hosted or used against public instances.

```yaml
libretranslate:
  # Enable/disable the LibreTranslate integration
  enabled: true
  
  # Base URL of your LibreTranslate instance
  # Examples:
  # - Local: "http://127.0.0.1:5000"
  # - Public: "https://libretranslate.com"
  base-url: "http://127.0.0.1:5000"
  
  # Required when connecting to non-localhost URLs
  allow-remote: false
  
  # Disable SSL certificate validation (for self-signed certificates)
  insecure-tls: false
  
  # API key if required by your LibreTranslate instance
  api-key: ""
  
  # Request timeout in seconds
  timeout: 30
  
  # Maximum retry attempts for failed requests
  max-retries: 3
  
  # Delay between retry attempts in seconds
  retry-delay: 2
  
  # Automatic Language Detection
  auto-detect: true
  
  # Preferred language pairs for better quality
  # Format: "source-target"
  preferred-pairs:
    - "en-es"
    - "es-en"
    - "fr-en"
    - "en-fr"
  
  # Managed LibreTranslate Server (Optional)
  # Auto-downloads and manages a local LibreTranslate instance
  managed:
    enabled: false
    
    # Command to start LibreTranslate
    # Examples:
    # - "libretranslate" (if installed via pip)
    # - "python -m libretranslate"
    # - "docker run -p 5000:5000 libretranslate/libretranslate"
    command: "libretranslate"
    
    # Port to run the server on
    port: 5000
    
    # Host to bind to (use 0.0.0.0 for network access)
    host: "127.0.0.1"
    
    # Limit loaded languages to reduce memory usage
    # Example: "en,es,fr,de,ru,zh,ja,ko"
    load-only: ""
    
    # Automatically download language models on first run
    download-models: true
    
    # Path to store models (default: ~/.local/share/libretranslate)
    models-path: ""
    
    # Additional command-line arguments
    # Example: "--load-only en,es --threads 4"
    extra-args: ""
    
    # Environment variables
    env:
      # Example: "CUDA_VISIBLE_DEVICES=0"
      # Example: "PUID=1000"
    
    # Health check settings
    health-check:
      # Enable health checks
      enabled: true
      
      # Health check interval in seconds
      interval: 30
      
      # Timeout for health check requests in seconds
      timeout: 5
      
      # Number of consecutive failures before considering the service unhealthy
      threshold: 3
    
    # Automatic restart settings
    auto-restart:
      # Enable automatic restart on failure
      enabled: true
      
      # Maximum restart attempts before giving up
      max-attempts: 5
      
      # Delay between restart attempts in seconds
      delay: 10
      
      # Maximum uptime in minutes (0 = no limit)
      max-uptime: 0

# Alternative Translation Backend
# Uncomment and configure if not using LibreTranslate
#
# local-model:
#   # Enable local model translation
#   enabled: false
#   
#   # Path to your local translation command/script
#   # The command should accept text via STDIN and output translation to STDOUT
#   command: "/path/to/translator"
#   
#   # Working directory for the command
#   working-directory: "/path/to/working/directory"
#   
#   # Command-line arguments
#   # Use placeholders: {from} {to} for language codes
#   args: "--from {from} --to {to}"
#   
#   # Environment variables
#   env:
#     MODEL_PATH: "/path/to/model"
#     DEVICE: "cuda"  # or "cpu"
#   
#   # Timeout in seconds
#   timeout: 30
#   
#   # Maximum concurrent translations
#   max-concurrent: 2
#   
#   # Input/output encoding (default: UTF-8)
#   encoding: "UTF-8"
#   
#   # Error handling
#   error-handling:
#     # Maximum retry attempts
#     max-retries: 3
#     
#     # Delay between retries in seconds
#     retry-delay: 2
#     
#     # Fallback language when translation fails
#     fallback-language: "en"
#
# External API (Example for Google Translate)
#
# google-translate:
#   enabled: false
#   api-key: "your-api-key"
#   project-id: "your-project-id"
#   location: "global"
#   model: "projects/{project-id}/locations/{location}/models/general/nmt"

### Detection Settings
```yaml
detector:
  # "lingua" (more accurate) or "heuristic" (lighter)
  type: "lingua"

# Auto-detection settings
autodetect:
  enabled: true
  # Minimum messages before attempting detection
  min-messages-before-detect: 3
  # Confidence threshold (0.0-1.0)
  confidence-threshold: 0.80

# Client language detection (requires Paper)
client-locale:
  enabled: true
  # Auto-set language on first join
  auto-accept: true
  # Prompt on client language change
  on-change: true

Storage

storage:
  # "sqlite" or "yaml"
  type: "sqlite"
  # Only for SQLite
  sqlite-file: "plugins/AutoLang/languages.db"

# Cache settings
cache:
  enabled: true
  # Maximum cached translations
  size: 500
  # Time-to-live in seconds (0 = no expiration)
  ttl-seconds: 0

Commands & Permissions

Commands

• /lang - Show current language
• /lang set <code> - Set your language
• /lang list - List available languages
• /lang reload - Reload configuration
• /lang health - Check LibreTranslate status

Permissions

• autolang.use - Allow using language commands (default: true)
• autolang.admin - Allow admin commands like reload (default: op)
• autolang.bypass - Bypass translation (see all messages in original language)

Language Support

AutoLang supports all languages available in your LibreTranslate instance (100+ languages by default). The plugin automatically fetches and caches the available languages on startup.

Common Language Codes

• en - English
• es - Spanish
• fr - French
• de - German
• ru - Russian
• zh - Chinese (Simplified)
• ja - Japanese
• ar - Arabic
• pt - Portuguese
• hi - Hindi

Installation

1. Download the latest version from Modrinth
2. Place the JAR in your server's plugins/ folder
3. Start your server to generate the config
4. Edit plugins/AutoLang/config.yml to your preferences
5. Run /reload or restart your server

🔧 Troubleshooting

LibreTranslate Connection Issues

• Ensure allow-remote: true if using a remote server
• For HTTPS with self-signed certs, enable insecure-tls: true
• Check server logs for connection errors

Language Detection

• Lingua detector requires at least 2 languages configured
• More messages improve detection accuracy
• Try the heuristic detector if Lingua causes performance issues

Performance

• Adjust max-translation-threads based on your server's CPU
• Enable caching to reduce API calls
• Consider a local LibreTranslate instance for better performance

Dependencies

• Required: Java 21+
• Recommended: Paper/Spigot 1.21.1+ (for full feature support)
• Optional: LibreTranslate server (local or remote)

License

AutoLang is licensed under the MIT License.

Support

Found a bug or have a feature request? Open an issue on GitHub.

Metrics

AutoLang uses bStats for anonymous usage statistics. You can opt out in the bStats/config.yml file.