AutoLang

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. Fallback 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

- Bidirectional Translation: All translation operations are performed asynchronously to prevent server lag - Bidirectional Translation: 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

- Context Preservation: Works with existing chat plugins and permission systems - Context Preservation: Detects and respects player client language settings (Paper servers only) - Context Preservation: 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

- Storage: Paper/Spigot 1.21.1 or higher (recommended for full feature support) - Storage: Java 21 or later - Storage: 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

```yaml

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

```yaml 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

- Optional: Java 21+ - Optional: 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.