Skip to content
Selu Docs

Agent Internationalization

Selu agents can provide localized experiences for users in different languages. This includes translated system prompts, UI text, tool descriptions, and approval messages.

Overview

Section titled “Overview”

Agent internationalization (i18n) works through:

  1. Localized system prompts — Different agent.md files per language
  2. Capability prompts — Localized prompt.md files for each capability
  3. UI localization bundles — YAML files with translated text for the interface
  4. Approval messages — Custom confirmation text in the user’s language

The Selu orchestrator automatically selects the appropriate content based on each user’s language preference, with fallbacks to ensure functionality even when translations are incomplete.

Language resolution

Section titled “Language resolution”

Selu uses a fallback chain to find the best available content:

  1. Requested language (e.g., user prefers de-AT)
  2. Base language (falls back to de if de-AT isn’t available)
  3. Agent’s default locale (specified in agent.yaml)
  4. English (universal fallback)

This means you can provide just German (de) translations and they’ll work for both de-DE and de-AT users.

Setting up localization

Section titled “Setting up localization”

1. Configure supported languages

Section titled “1. Configure supported languages”

In your agent.yaml, declare the languages you support:

agent.yaml
name: weather-assistant
i18n:
  default_locale: en
  supported_locales:
    - en
    - de
    - fr
# ... rest of your config

2. Create localized system prompts

Section titled “2. Create localized system prompts”

Add language-specific system prompt files:

agent.md
You are a helpful weather assistant. You can provide forecasts,
weather alerts, and climate information for any location worldwide.


When providing forecasts:
- Always include temperature in both Celsius and Fahrenheit
- Mention precipitation probability if above 30%
- Suggest appropriate clothing for the conditions

3. Localize capability prompts

Section titled “3. Localize capability prompts”

Each capability can have localized instruction text:

capabilities/weather/prompt.de.md
## Wetter-Fähigkeit


Diese Fähigkeit ermöglicht es dir, aktuelle Wetterdaten und Vorhersagen abzurufen.


Verwende `get_current_weather` für das aktuelle Wetter und `get_forecast` für
mehrtägige Vorhersagen. Achte darauf, Ortsangaben in ein standardisiertes Format
zu konvertieren (Stadt, Land).

4. Create localization bundles

Section titled “4. Create localization bundles”

The i18n/ directory contains YAML files with translated UI text:

i18n/de.yaml
agent:
  name: "Wetter-Assistent"
  description: "Hilft bei Wettervorhersagen und Wetterwarnungen"
  long_description: >
    Ein intelligenter Assistent für alle wetterbezogenen Anfragen.
    Kann Vorhersagen, Warnungen und Klimadaten für jeden Ort bereitstellen.


install_steps:
  api_key:
    label: "Wetter-API-Schlüssel"
    description: >
      Geben Sie Ihren API-Schlüssel von OpenWeatherMap ein.
      Einen kostenlosen Schlüssel erhalten Sie unter https://openweathermap.org/api


automation:
  schedules:
    morning_forecast:
      label: "Morgendliche Wettervorhersage"
      prompt: "Gib mir die Wettervorhersage für heute in München"
      cron_description: "Jeden Tag um 07:00 Uhr"


capabilities:
  weather:
    tools:
      get_current_weather:
        display_name: "Aktuelles Wetter"
        description: "Ruft das aktuelle Wetter für einen bestimmten Ort ab"
        input:
          location:
            description: "Stadt und Land, z.B. 'Berlin, Deutschland'"
          units:
            description: "Einheiten: 'metric' für Celsius, 'imperial' für Fahrenheit"


    credentials:
      WEATHER_API_KEY:
        description: >
          API-Schlüssel für OpenWeatherMap (https://openweathermap.org/api).
          Benötigt für alle Wettervorhersagen.


approval:
  tools:
    weather__get_current_weather:
      label: "Wetter abrufen"
      message: "Ich möchte das aktuelle Wetter für den angegebenen Ort abrufen."

Localization bundle structure

Section titled “Localization bundle structure”

The localization YAML files support these sections:

Agent metadata

Section titled “Agent metadata”
agent:
  name: "Translated agent name"
  description: "Short description for marketplace"
  long_description: "Detailed description for agent setup"

Install steps

Section titled “Install steps”
install_steps:
  step_id:  # matches the step ID in agent.yaml
    label: "Translated step label"
    description: "Translated help text"

Automation presets

Section titled “Automation presets”
automation:
  schedules:
    schedule_id:  # matches preset ID in agent.yaml
      label: "Translated schedule name"
      prompt: "Localized prompt text"
      cron_description: "Human-readable timing description"

Capability tools and credentials

Section titled “Capability tools and credentials”
capabilities:
  capability_id:  # matches capability ID
    tools:
      tool_name:
        display_name: "Tool display name"
        description: "What the tool does"
        input:
          field_name:
            description: "Parameter description"


    credentials:
      credential_name:
        description: "Where to get this credential and what it's for"

Approval messages

Section titled “Approval messages”
approval:
  tools:
    capability_id__tool_name:  # namespaced tool identifier
      label: "Action label for approval prompt"
      message: "Custom confirmation message in natural language"

Best practices

Section titled “Best practices”

Keep prompts consistent

Section titled “Keep prompts consistent”

When translating system prompts and capability instructions:

  • Maintain the same structure and information
  • Keep technical instructions accurate (API usage, field names, etc.)
  • Adapt examples and references to be culturally relevant
  • Preserve the agent’s personality across languages

Write natural approval messages

Section titled “Write natural approval messages”

Instead of technical descriptions, write approval messages as the agent would naturally ask:

# Good - natural language
approval:
  tools:
    email__send_message:
      message: "Ich möchte eine E-Mail an {{recipient}} mit dem Betreff '{{subject}}' senden."


# Avoid - technical descriptions
approval:
  tools:
    email__send_message:
      message: "Tool will execute send_message with recipient and subject parameters."

Provide helpful credential descriptions

Section titled “Provide helpful credential descriptions”

Be specific about where users can obtain credentials:

credentials:
  GITHUB_TOKEN:
    description: >
      Personal Access Token von GitHub. Erstellen Sie einen unter:
      https://github.com/settings/personal-access-tokens


      Benötigte Berechtigung: 'repo' für private Repositories,
      'public_repo' für öffentliche Repositories.

Test with partial translations

Section titled “Test with partial translations”

Your agent should work even when some translations are missing. Always test with:

  • Complete translations
  • Partial translations (some keys missing)
  • No translations (fallback to default locale)

Runtime behavior

Section titled “Runtime behavior”

At runtime, Selu uses localized content in several places:

  • System prompts — The appropriate agent.<locale>.md is injected into LLM context
  • Tool names and descriptions — Shown in permission settings and admin interfaces
  • Approval prompts — Sent to users when tools require confirmation
  • Setup wizards — Install step labels and credential descriptions
  • Automation — Schedule labels and descriptions in the Schedules UI

The localization system is designed to degrade gracefully — if any translation is missing, the system falls back to the next available option in the language chain.

Example agent with full i18n

Section titled “Example agent with full i18n”

Here’s a complete example of a bilingual weather agent:

weather-agent/
├── agent.yaml              # Declares supported locales
├── agent.md                # English system prompt
├── agent.de.md            # German system prompt
├── i18n/
│   └── de.yaml            # German UI translations
└── capabilities/
    └── weather/
        ├── manifest.yaml
        ├── prompt.md       # English capability instructions
        └── prompt.de.md   # German capability instructions

This structure provides German users with:

  • German system prompts sent to the LLM
  • German tool names and descriptions in the UI
  • German approval messages when tools need confirmation
  • German setup instructions and credential descriptions

While English users (or users of unsupported languages) automatically get the default English experience.

Next steps

Section titled “Next steps”