Multi-locale

Multilingual content in one roundtrip - how to fetch DE and EN at the same time, what permission is needed, and how fallbacks work.

The go~mus API is locale-aware: every translatable field (titles, descriptions, categories, language names) comes in the language you request - and on demand in several at once. This page shows how that works in practice.

Three modes

ModeCallWhen
Single locale (default)no locale parameterDefault language of the instance (typically de)
Single locale explicit?locale=enOne language, fixed
Multi locale?locale[]=de&locale[]=enMultiple languages in one response (API user with permission only)

Single locale

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

Translatable fields come flat as strings:

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

When a field has no translation in the requested locale, the server falls back automatically to the default locale - so you never see null strings for translated fields, but DE text in case of doubt.

Multi locale - several languages in one call

Useful when you build a bilingual website and want to pre-render both versions, or when your CMS caches translations and wants every language at once:

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

Translatable fields come as objects with locale keys:

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

Non-translatable fields (id, dates, numbers) stay flat. Only globalize fields turn into objects.

Important: multi-locale needs a permission

Multi-locale is only available with an API user token holding permission. Public, customer and reseller tokens cannot do it. In practice:

  • Multi-locale is for server-side CMS and sync tools, not for the frontend
  • The API user token must not be embedded in the frontend - relay it server-side
  • On missing permission the server returns 401/403 with a matching message

Query available locales

Before the first multi-locale call it pays off to look up which locales the instance supports at all:

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

Response:

{
  "locales": ["de", "en", "fr", "nl"],
  "locales_options": [
    { "id": 1, "locale": "de" },
    { "id": 2, "locale": "en" }
  ],
  "multi_locales": false,
  "current": "de"
}
  • locales - languages configured in this instance
  • locales_options - the same languages as id pairs (for filters like language_id on tours/events)
  • multi_locales - currently active? true only when the running call is itself multi-locale
  • current - the language the call currently responds in

Locale codes and fallbacks

go~mus accepts two-letter codes (de, en, fr, nl) and locale-with-region (de_AT, de_CH). Fallback chain:

1. Exact code (de_AT) - if maintained in the instance

2. Two-letter fallback (de) - the default for many houses

3. Instance default locale - when the code is not supported at all

If you request a locale unknown to the instance (e.g. ?locale=ja), the server returns 422 with "locale 'ja' not supported".

Pitfalls

  • Multi-locale is API-user only. Trying it from the frontend yields a permission error. Pattern: server-side call, cache locally, frontend gets pre-built JSON.
  • Single locale always falls back to default. If you expect an untranslated field (e.g. EN is missing for a German school event), the DE text shows up in the EN response. That is intentional - no null fields in the frontend - but do not rely on locale=en returning only EN strings automatically.
  • Order of locales determines the internal default. ?locale[]=de&locale[]=en uses de as the internal default locale (for sorting and I18n logic). ?locale[]=en&locale[]=de uses en. This affects, among other things, the order in category embeds.
  • Multi-locale needs the bracket form. Only ?locale[]=de&locale[]=en triggers the object form with locale keys. ?locale=de,en with a comma is parsed as a single locale string and falls back to the default language - the response comes back flat in one language.
  • Forgetting permissions. Without the multi-locale permission, the bracket form returns 401/403. Single-locale calls (?locale=en) keep working without that permission - the multi-locale permission gates only the bracket form.