Agent-Internationalisierung

Selu-Agenten können lokalisierte Erfahrungen für Benutzer in verschiedenen Sprachen bereitstellen. Dies umfasst übersetzte System-Prompts, UI-Text, Tool-Beschreibungen und Bestätigungsnachrichten.

Überblick

Agent-Internationalisierung (i18n) funktioniert durch:

1. Lokalisierte System-Prompts — Verschiedene agent.md-Dateien pro Sprache
2. Fähigkeits-Prompts — Lokalisierte prompt.md-Dateien für jede Fähigkeit
3. UI-Lokalisierungspakete — YAML-Dateien mit übersetztem Text für die Benutzeroberfläche
4. Bestätigungsnachrichten — Angepasster Bestätigungstext in der Sprache des Benutzers

Der Selu-Orchestrator wählt automatisch den passenden Inhalt basierend auf der Sprachpräferenz jedes Benutzers aus, mit Fallbacks um Funktionalität auch bei unvollständigen Übersetzungen zu gewährleisten.

Sprachauflösung

Selu verwendet eine Fallback-Kette, um den besten verfügbaren Inhalt zu finden:

1. Angeforderte Sprache (z.B. Benutzer bevorzugt de-AT)
2. Basissprache (fällt auf de zurück, wenn de-AT nicht verfügbar ist)
3. Standard-Locale des Agenten (spezifiziert in agent.yaml)
4. Englisch (universeller Fallback)

Das bedeutet, Sie können nur deutsche (de) Übersetzungen bereitstellen und sie funktionieren sowohl für de-DE als auch de-AT Benutzer.

Lokalisierung einrichten

1. Unterstützte Sprachen konfigurieren

In Ihrer agent.yaml deklarieren Sie die Sprachen, die Sie unterstützen:

agent.yaml

name: weather-assistant
i18n:
  default_locale: en
  supported_locales:
    - en
    - de
    - fr
# ... Rest Ihrer Konfiguration

2. Lokalisierte System-Prompts erstellen

Fügen Sie sprachspezifische System-Prompt-Dateien hinzu:

Englisch (Standard)

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

Deutsch

agent.de.md

Du bist ein hilfreicher Wetter-Assistent. Du kannst Vorhersagen,
Wetterwarnungen und Klimainformationen für jeden Ort weltweit bereitstellen.

Bei Vorhersagen:
- Immer Temperatur in Celsius und Fahrenheit angeben
- Niederschlagswahrscheinlichkeit erwähnen, wenn über 30%
- Passende Kleidung für die Bedingungen vorschlagen

3. Fähigkeits-Prompts lokalisieren

Jede Fähigkeit kann lokalisierten Anweisungstext haben:

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. Lokalisierungspakete erstellen

Das i18n/-Verzeichnis enthält YAML-Dateien mit übersetztem 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."

Struktur der Lokalisierungspakete

Die Lokalisierungs-YAML-Dateien unterstützen diese Abschnitte:

Agent-Metadaten

agent:
  name: "Übersetzter Agent-Name"
  description: "Kurze Beschreibung für den Marktplatz"
  long_description: "Detaillierte Beschreibung für Agent-Setup"

Installationsschritte

install_steps:
  step_id:  # entspricht der Schritt-ID in agent.yaml
    label: "Übersetztes Schritt-Label"
    description: "Übersetzter Hilfetext"

Automatisierungs-Presets

automation:
  schedules:
    schedule_id:  # entspricht der Preset-ID in agent.yaml
      label: "Übersetzter Zeitplan-Name"
      prompt: "Lokalisierter Prompt-Text"
      cron_description: "Menschenlesbare Zeitbeschreibung"

Fähigkeits-Tools und Anmeldedaten

capabilities:
  capability_id:  # entspricht der Fähigkeits-ID
    tools:
      tool_name:
        display_name: "Tool-Anzeigename"
        description: "Was das Tool macht"
        input:
          field_name:
            description: "Parameterbeschreibung"

    credentials:
      credential_name:
        description: "Wo man diese Anmeldedaten erhält und wofür sie sind"

Bestätigungsnachrichten

approval:
  tools:
    capability_id__tool_name:  # namespaced Tool-Identifikator
      label: "Aktions-Label für Bestätigungsprompt"
      message: "Angepasste Bestätigungsnachricht in natürlicher Sprache"

Bewährte Praktiken

Prompts konsistent halten

Beim Übersetzen von System-Prompts und Fähigkeitsanweisungen:

• Die gleiche Struktur und Information beibehalten
• Technische Anweisungen genau halten (API-Nutzung, Feldnamen, etc.)
• Beispiele und Referenzen kulturell anpassen
• Die Persönlichkeit des Agenten sprachübergreifend bewahren

Natürliche Bestätigungsnachrichten schreiben

Anstatt technischer Beschreibungen, schreiben Sie Bestätigungsnachrichten so, wie der Agent natürlich fragen würde:

# Gut - natürliche Sprache
approval:
  tools:
    email__send_message:
      message: "Ich möchte eine E-Mail an {{recipient}} mit dem Betreff '{{subject}}' senden."

# Vermeiden - technische Beschreibungen
approval:
  tools:
    email__send_message:
      message: "Tool wird send_message mit recipient und subject Parametern ausführen."

Hilfreiche Anmeldedaten-Beschreibungen bereitstellen

Seien Sie spezifisch darüber, wo Benutzer Anmeldedaten erhalten können:

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.

Mit partiellen Übersetzungen testen

Ihr Agent sollte auch funktionieren, wenn einige Übersetzungen fehlen. Testen Sie immer mit:

• Vollständigen Übersetzungen
• Partiellen Übersetzungen (einige Schlüssel fehlen)
• Ohne Übersetzungen (Fallback zur Standard-Locale)

Tipp

Beginnen Sie mit dem wichtigsten Text zuerst: Agent-Name, Beschreibung und Tool-Labels. Sie können detailliertere Übersetzungen schrittweise hinzufügen.

Laufzeitverhalten

Zur Laufzeit verwendet Selu lokalisierten Inhalt an mehreren Stellen:

• System-Prompts — Das passende agent.<locale>.md wird in den LLM-Kontext eingefügt
• Tool-Namen und Beschreibungen — Angezeigt in Berechtigungseinstellungen und Admin-Oberflächen
• Bestätigungsprompts — An Benutzer gesendet, wenn Tools Bestätigung benötigen
• Setup-Assistenten — Installationsschritt-Labels und Anmeldedaten-Beschreibungen
• Automatisierung — Zeitplan-Labels und Beschreibungen in der Zeitplan-UI

Das Lokalisierungssystem ist darauf ausgelegt, elegant zu degradieren — wenn eine Übersetzung fehlt, fällt das System auf die nächste verfügbare Option in der Sprachkette zurück.

Beispiel-Agent mit vollständiger i18n

Hier ist ein vollständiges Beispiel eines zweisprachigen Wetter-Agenten:

weather-agent/
├── agent.yaml              # Deklariert unterstützte Locales
├── agent.md                # Englischer System-Prompt
├── agent.de.md            # Deutscher System-Prompt
├── i18n/
│   └── de.yaml            # Deutsche UI-Übersetzungen
└── capabilities/
    └── weather/
        ├── manifest.yaml
        ├── prompt.md       # Englische Fähigkeitsanweisungen
        └── prompt.de.md   # Deutsche Fähigkeitsanweisungen

Diese Struktur bietet deutschen Benutzern:

• Deutsche System-Prompts, die an das LLM gesendet werden
• Deutsche Tool-Namen und Beschreibungen in der UI
• Deutsche Bestätigungsnachrichten, wenn Tools Bestätigung benötigen
• Deutsche Setup-Anweisungen und Anmeldedaten-Beschreibungen

Während englische Benutzer (oder Benutzer nicht unterstützter Sprachen) automatisch die Standard-englische Erfahrung erhalten.

Nächste Schritte

• Siehe die agent.yaml-Referenz für i18n-Konfigurationsoptionen
• Schauen Sie sich den Paketstruktur-Leitfaden für Dateiorganisation an
• Erfahren Sie mehr über Tool-Richtlinien, um zu verstehen, wie Bestätigungsnachrichten verwendet werden