Mehrsprachige Unterstützung

Wenn Ihre Dokumentation Nutzer in mehr als einer Sprache erreichen soll, können Sie pro Locale separate Navigationsbäume definieren und Leser über ein Dropdown in der oberen Leiste wechseln lassen.

Konfiguration

Schließen Sie Ihre Navigation in ein languages-Array ein. Jede Sprache enthält dabei ihre eigene Navigationsstruktur:

{
  "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äfigsierten 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": [...]
      }
    ]
  }
}

Übersetzen von Navbar-Bezeichnungen

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äfigsierten 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äche Search, die Schaltfläche 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 diese Sprache zuerst. Über den Sprachumschalter können sie die Sprache wechseln.

URL-Struktur

Sprachpräfixe erscheinen in URLs:

Teilübersetzungen

Sie müssen nicht jede Seite übersetzen. Wenn eine Seite in einer Sprache nicht vorhanden ist, 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
        }
      ]
    }
  ]
}

Übersetzen von OpenAPI-Spezifikationen

Von OpenAPI gesteuerte Endpoint-Seiten (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 zur Renderzeit 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 lesbare 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 dann einen mehrsprachigen Endpoint-Block statt eines 404-Fehlers. Dies entspricht dem allgemeinen Verhalten bei Teilübersetzungen von MDX-Seiten.

Entfernen einer sprachspezifischen Spezifikation

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

Beispiel

Quelle 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 eine RTL-Formatierung an, wenn diese Sprachen aktiv sind.

Wie geht es weiter?