Mehrsprachige Unterstützung

Wenn Ihre Dokumentation Nutzer in mehreren Sprachen erreichen soll, können Sie pro Sprache separate Navigationsstrukturen definieren und Lesern ermöglichen, über ein Dropdown in der oberen Leiste zu wechseln.

Konfiguration

Umschließen Sie Ihre Navigation mit einem languages-Array, wobei jede Sprache ihre eigene Navigationsstruktur enthält:

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "tabs": [
          {
            "tab": "Documentation",
            "groups": [
              {
                "group": "Getting Started",
                "pages": ["introduction", "quickstart"]
              }
            ]
          }
        ]
      },
      {
        "language": "es",
        "tabs": [
          {
            "tab": "Documentación",
            "groups": [
              {
                "group": "Comenzar",
                "pages": ["es/introduction", "es/quickstart"]
              }
            ]
          }
        ]
      }
    ]
  }
}

Unterstützte Sprachen

Verzeichnisstruktur

Organisieren Sie übersetzte Inhalte in sprachpräfigierten Verzeichnissen:

my-docs/
├── docs.json
├── introduction.mdx          # English (default)
├── quickstart.mdx
├── es/
│   ├── introduction.mdx      # Spanish
│   └── quickstart.mdx
├── fr/
│   ├── introduction.mdx      # French
│   └── quickstart.mdx
└── de/
    ├── introduction.mdx      # German
    └── quickstart.mdx

Verweisen Sie in der Navigation über den vollständigen Pfad auf Seiten, einschließlich des Sprachpräfixes:

{
  "language": "es",
  "tabs": [
    {
      "tab": "Documentación",
      "groups": [
        {
          "group": "Comenzar",
          "pages": ["es/introduction", "es/quickstart"]
        }
      ]
    }
  ]
}

Sprachspezifische Einstellungen

Jede Sprache kann eine eigene Konfiguration haben:

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "tabs": [...]
      },
      {
        "language": "es",
        "tabs": [...]
      }
    ]
  }
}

Navbar-Labels übersetzen

Links in der oberen Navigation und der primäre CTA akzeptieren ein optionales labels-Objekt mit sprachspezifischen Überschreibungen. Wenn sich der Leser auf einer sprachpräfigierten URL (z. B. /fr/...) befindet, wird die passende Überschreibung verwendet. Andernfalls wird das Standard-label angezeigt.

{
  "navbar": {
    "links": [
      {
        "label": "Blog",
        "labels": { "fr": "Blog", "es": "Blog" },
        "href": "/blog"
      },
      {
        "label": "Pricing",
        "labels": { "fr": "Tarifs", "es": "Precios" },
        "href": "/pricing"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "labels": { "fr": "Tableau de bord", "es": "Panel" },
      "href": "https://app.example.com"
    }
  }
}

Integrierte UI-Texte (die Schaltflächen Search, Ask AI und das Dropdown der More-Tabs) werden automatisch für jede unterstützte Sprache übersetzt. Sie müssen diese nicht konfigurieren.

Standardsprache

Die erste Sprache im Array ist die Standardsprache. Nutzer, die Ihre Dokumentation aufrufen, sehen zuerst diese Sprache. Mit dem Sprachumschalter können sie die Sprache ändern.

URL-Struktur

Sprachpräfixe erscheinen in URLs:

Unvollständige Übersetzungen

Sie müssen nicht jede Seite übersetzen. Wenn eine Seite in einer Sprache nicht existiert, sehen Nutzer eine Fallback-Nachricht mit einem Link zur englischen Version.

Für Seiten, die nicht übersetzt werden sollen (z. B. API-Referenzen), können Sie in allen Sprachen auf dieselbe Seite verweisen:

{
  "language": "es",
  "tabs": [
    {
      "tab": "API",
      "groups": [
        {
          "group": "Endpoints",
          "pages": ["api/users", "api/posts"]  // Same as English
        }
      ]
    }
  ]
}

OpenAPI-Spezifikationen übersetzen

Endpoint-Seiten, die von OpenAPI gesteuert werden (also Seiten mit einer openapi:-Direktive im Frontmatter), rendern Inhalte aus einer YAML- oder JSON-Spezifikationsdatei. Um die Endpoint-Zusammenfassung, Beschreibungen, Parameterhinweise und Beschreibungen von Schemafeldern zu übersetzen, stellen Sie eine sprachspezifische Spezifikationsdatei neben der englischen Datei bereit.

Dateibenennung

Legen Sie die übersetzte Spezifikation neben der Quelldatei ab und fügen Sie den Sprachcode vor der Erweiterung ein:

openapi/
├── api.yaml           # English (default)
├── api.fr.yaml        # French
├── api.es.yaml        # Spanish
└── api.zh.yaml        # Simplified Chinese

Eine Konfigurationsänderung oder Änderung an docs.json ist nicht erforderlich. Jamdesk ermittelt die passende Spezifikation beim Rendern anhand des Sprachpräfixes der URL. Eine Seite unter /fr/api-reference/create-ticket sucht zuerst nach api.fr.yaml und verwendet api.yaml, wenn keine Übersetzung vorhanden ist.

Was in der Spezifikation übersetzt werden soll

Übersetzen Sie menschenlesbare Prosa. Alle strukturellen Werte müssen in allen Sprachen identisch bleiben.

Fallback-Verhalten

Wenn eine Seite unter einer lokalisierten URL angefordert wird, aber keine übersetzte Spezifikation vorhanden ist, rendert Jamdesk die englische Spezifikation innerhalb der übersetzten Seitenhülle. Nutzer sehen einen Endpoint-Block mit gemischten Sprachen statt eines 404-Fehlers. Dies entspricht dem allgemeinen Verhalten für unvollständige Übersetzungen von MDX-Seiten.

Sprachspezifische Spezifikation entfernen

Wenn Sie api.<lang>.yaml löschen, fällt die Seite beim nächsten Rendern auf die englische Spezifikation zurück (ein erneuter Build ist nicht erforderlich). Um die Übersetzung von Grund auf neu zu erstellen, löschen Sie die Datei und generieren Sie sie erneut. Eine Änderung an docs.json ist nicht erforderlich – die Auflösung der Spezifikation basiert ausschließlich auf dem Dateinamen.

Beispiel

Quelldatei openapi/tickets.yaml:

info:
  title: Tickets API
  description: Manage support tickets.
paths:
  /tickets:
    post:
      summary: Create a ticket
      description: Create a new support ticket.
      operationId: createTicket

Französische Übersetzung openapi/tickets.fr.yaml:

info:
  title: API Tickets
  description: Gérez les tickets de support.
paths:
  /tickets:
    post:
      summary: Créer un ticket
      description: Créer un nouveau ticket de support.
      operationId: createTicket

Beachten Sie, dass /tickets, post und createTicket identisch bleiben. Nur die Prosa wird geändert.

Übersetzungsworkflow

RTL-Sprachen

Sprachen mit Schreibrichtung von rechts nach links wie Arabisch und Hebräisch werden unterstützt. Jamdesk wendet automatisch RTL-Stile an, wenn diese Sprachen aktiv sind.

Wie geht es weiter?