Localization

Passage supports localization for disconnect messages. When a player is disconnected, Passage displays the message in the player’s client language.

Configuration

Localization is a per-route adapter configured in routes[].localization:

routes:
- hostname: "mc.example.net"
  localization:
    type: fixed
    default_locale: "en_US"
    warn_unknown_keys: true
    messages:
      en:
        locale: "English"
        disconnect_timeout: '{"text":"Connection timed out","color":"red"}'
        disconnect_no_target: '{"text":"No server available","color":"yellow"}'
        disconnect_unauthenticated: '{"text":"Authentication failed","color":"red"}'
      de:
        locale: "Deutsch"
        disconnect_timeout: '{"text":"Verbindung getrennt: Keine Antwort vom Client","color":"red"}'
        disconnect_no_target: '{"text":"Kein verfügbarer Server","color":"yellow"}'
        disconnect_unauthenticated: '{"text":"Authentifizierung fehlgeschlagen","color":"red"}'

Adapter Types

Type	Description
fixed (default)	Returns messages from a static configuration map
grpc	Delegates to an external gRPC service

Fixed Adapter Fields

Field	Type	Default	Description
default_locale	string	"en_US"	Fallback locale when the client’s locale has no messages
warn_unknown_keys	bool	true	Log warnings for unrecognized message keys
messages	map	(built-in defaults)	Locale-keyed map of message key-value pairs

gRPC Adapter

For dynamic localization logic, delegate to a gRPC service:

localization:
  type: grpc
  address: "http://localization-service:50051"

See the gRPC Protocol Reference for the service definition.

---

Built-in Defaults

If you don’t configure localization, Passage provides default messages in six languages:

Locale Key	Language
en	English
es	Spanish
fr	French
de	German
zh-CN	Chinese (Simplified)
ru	Russian

Locale Key Format

Passage uses short locale keys like en, de, es — not full codes like en_US or de_DE. The exception is regional variants like zh-CN.

---

Message Keys

Passage uses three built-in message keys:

disconnect_timeout

Shown when the connection times out during handshake (keep-alive timeout).

disconnect_no_target

Shown when no backend server is available — either discovery returns zero targets, or all targets are filtered out by the actions pipeline.

disconnect_unauthenticated

Shown when player authentication fails.

Custom Keys

gRPC adapters (Authentication and DiscoveryAction) can return custom localization keys to reject connections. These keys are resolved through the localization adapter:

messages:
  en:
    disconnect_queue_full: '{"text":"Queue is full. Please try again later.","color":"yellow"}'
    disconnect_banned: '{"text":"You are banned from this server.","color":"red"}'

---

Message Format

Messages use Minecraft’s JSON text component format:

Basic Text

disconnect_timeout: '{"text":"Connection timeout"}'

Colored Text

disconnect_timeout: '{"text":"Connection timeout","color":"red"}'

Available colors: black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white

Formatted Text

disconnect_timeout: '{"text":"Connection timeout","bold":true,"color":"red"}'

Formatting options: bold, italic, underlined, strikethrough, obfuscated

Multi-line Messages

disconnect_no_target: '{"text":"","extra":[{"text":"No server available\n","color":"yellow","bold":true},{"text":"Please try again later","color":"gray"}]}'

---

Example: Multi-Language Setup

routes:
- hostname: "mc.example.net"
  localization:
    type: fixed
    default_locale: "en_US"
    messages:
      en:
        locale: "English"
        disconnect_timeout: '{"text":"Disconnected: Connection timed out","color":"red"}'
        disconnect_no_target: '{"text":"Disconnected: No server available","color":"yellow"}'
        disconnect_unauthenticated: '{"text":"Disconnected: Authentication failed","color":"red"}'
      es:
        locale: "Español"
        disconnect_timeout: '{"text":"Desconectado: Tiempo de espera agotado","color":"red"}'
        disconnect_no_target: '{"text":"Desconectado: No hay servidor disponible","color":"yellow"}'
        disconnect_unauthenticated: '{"text":"Desconectado: No se pudo autenticar","color":"red"}'
      fr:
        locale: "Français"
        disconnect_timeout: '{"text":"Déconnecté : Délai de connexion dépassé","color":"red"}'
        disconnect_no_target: '{"text":"Déconnecté : Aucun serveur disponible","color":"yellow"}'
        disconnect_unauthenticated: '{"text":"Déconnecté : Échec de l''authentification","color":"red"}'
      de:
        locale: "Deutsch"
        disconnect_timeout: '{"text":"Getrennt: Verbindungszeitüberschreitung","color":"red"}'
        disconnect_no_target: '{"text":"Getrennt: Kein Server verfügbar","color":"yellow"}'
        disconnect_unauthenticated: '{"text":"Getrennt: Authentifizierung fehlgeschlagen","color":"red"}'

---

How Locale Selection Works

1. The Minecraft client sends its configured language to Passage
2. Passage looks up messages matching the client’s locale key (e.g., de)
3. If no match, falls back to the default_locale messages
4. If that also has no match, returns the raw key string

To test: Change your Minecraft language in Options > Language, then reconnect.

---

Best Practices

• Always configure messages for your default_locale (usually en)
• Add locales for your primary player base’s languages
• Keep messages clear, concise, and actionable
• Use colors consistently: red for errors, yellow for warnings
• Test messages with native speakers where possible