Multi-Locale

Die go~mus API ist locale-aware: alle übersetzbaren Felder (Titel, Beschreibungen, Kategorien, Sprachnamen) kommen in der Sprache, die du anfordern - und auf Wunsch in mehreren gleichzeitig. Diese Seite zeigt, wie das praktisch geht.

Drei Modi

Modus	Aufruf	Wann
Single Locale (Default)	kein `locale`-Parameter	Default-Sprache der Instance (typisch `de`)
Single Locale explicit	`?locale=en`	Eine Sprache, eindeutig festgelegt
Multi Locale	`?locale[]=de&locale[]=en`	Mehrere Sprachen in einer Response (nur API-User mit Permission)

Single Locale

curl "https://demo.gomus.de/api/v4/events/843?locale=en"

Die übersetzbaren Felder kommen flach als String:

{
  "event": {
    "id": 843,
    "title": "Sunday tour through the collection",
    "description": "Discover the highlights of our permanent collection..."
  }
}

Wenn ein Feld in der angefragten Sprache nicht übersetzt ist, fällt der Server automatisch auf die Default-Sprache zurück - du bekommst also nie null-Strings für übersetzte Felder, sondern im Zweifel den DE-Text.

Multi Locale - mehrere Sprachen in einem Call

Praktisch, wenn du eine zweisprachige Webseite baut und beide Versionen vorrendern wollt - oder wenn dein CMS die Übersetzungen selbst zwischenspeichert und alle Sprachen auf einmal will:

curl "https://demo.gomus.de/api/v4/events/843?locale[]=de&locale[]=en" \
  -H "Authorization: Bearer YOUR_API_USER_TOKEN"

Die übersetzbaren Felder kommen als Objekt mit Locale-Keys:

{
  "event": {
    "id": 843,
    "title": {
      "de": "Sonntagsführung durch die Sammlung",
      "en": "Sunday tour through the collection"
    },
    "description": {
      "de": "Entdeckst du die Höhepunkte unserer Sammlung...",
      "en": "Discover the highlights of our permanent collection..."
    }
  }
}

Nicht-übersetzbare Felder (id, Datums-Werte, Zahlen) bleiben flach. Nur die Globalize-Felder werden zu Objekten.

Wichtig: Multi-Locale braucht Permission

Multi-Locale ist nur mit einem API-User-Token mit Permission möglich. Public-Token, Customer-Token und Reseller-Token können das nicht. Praktisch heißt das:

Multi-Locale ist für serverseitige CMS- und Sync-Tools gedacht, nicht fürs Frontend
Der API-User-Token darf nicht im Frontend einbettet werden - serverseitig durchreichen
Bei fehlender Permission antwortet der Server mit 401/403 und einer entsprechenden Fehler-Message

Verfügbare Locales abfragen

Vor dem ersten Multi-Locale-Call lohnt sich ein Lookup, welche Locales deine Instance überhaupt unterstützt:

curl "https://demo.gomus.de/api/v4/locales"

Antwort:

{
  "locales": ["de", "en", "fr", "nl"],
  "locales_options": [
    { "id": 1, "locale": "de" },
    { "id": 2, "locale": "en" }
  ],
  "multi_locales": false,
  "current": "de"
}

locales - die in dieser Instance konfigurierten Sprachen
locales_options - dieselben Sprachen als ID-Paare (für Filter wie language_id auf Tours/Events)
multi_locales - aktuell aktiv? wahr nur, wenn der gerade laufende Call selbst multi-locale ist
current - in welcher Sprache der Call gerade antwortet

Locale-Codes und Fallbacks

go~mus akzeptiert Zwei-Buchstaben-Codes (de, en, fr, nl) und Locale-mit-Region (de_AT, de_CH). Fallback-Kette:

1. Genauer Code (de_AT) - falls in der Instance gepflegt

2. Zwei-Buchstaben-Fallback (de) - der Default für viele Houses

3. Default-Locale der Instance - wenn der Code gar nicht unterstützt ist

Wenn du eine in der Instance unbekannte Locale anfragt (z.B. ?locale=ja), antwortet der Server mit 422 und der Message "locale 'ja' not supported".

Stolperdrahte

Multi-Locale ist API-User-only. Wer das im Frontend versucht, bekommt einen Permission-Error. Pattern: serverseitiger Call, lokal Cachen, Frontend bekommt vorgefertigtes JSON.
Single-Locale fällt immer auf Default zurück. Wenn du ein nicht-übersetztes Feld erwartet (z.B. EN fehlt für ein deutsches Schul-Event), kommt der DE-Text in der EN-Antwort. Das ist Absicht - keine null-Felder im Frontend - aber du solltest dir nicht darauf verlassen, dass locale=en automatisch nur EN-Strings liefert.
Reihenfolge der Locales bestimmt den Default. Bei ?locale[]=de&locale[]=en wird de als interne Default-Locale verwendet (für Sortierung und I18n-Logik). Bei ?locale[]=en&locale[]=de ist es en. Das beeinflusst u.a. die Reihenfolge in category-Embeds.
Multi-Locale braucht die Bracket-Form. Nur ?locale[]=de&locale[]=en triggert die Objekt-Form mit Sprach-Keys. ?locale=de,en mit Komma wird als einzelner Locale-String ausgewertet und fällt auf die Default-Sprache zurück - die Antwort kommt dann flach in einer Sprache.
Permissions vergessen. Wenn ein API-User die Multi-Locale-Permission nicht hat, kommt die Bracket-Form mit 401/403 zurück. Single-Locale-Calls (?locale=en) funktionieren weiterhin ohne Permission - die Multi-Locale-Permission gilt ausschließlich für die Bracket-Form.