Wie man OpenAPI-Spezifikationen lokalisiert

OpenAPI-Spezifikationen sind das Rückgrat moderner API-Dokumentation. Sie in mehreren Sprachen zu lokalisieren, hilft Entwicklern weltweit, Ihre API zu verstehen und zu integrieren. Aber das Übersetzen von OpenAPI-Spezifikationen ist nicht einfach – Sie müssen die Struktur beibehalten, während Sie menschenlesbare Inhalte lokalisieren.

Was ist OpenAPI?

OpenAPI (früher Swagger) ist ein Standardformat zur Beschreibung von REST-APIs. Es enthält Endpunkte, Anfrage-/Antwort-Schemata, Parameter, Authentifizierungsmethoden und detaillierte Beschreibungen. Diese Spezifikationen unterstützen Tools wie Swagger UI, Redoc, Scalar und Codegeneratoren – was sie für die Entwicklererfahrung entscheidend macht.

Die Übersetzungsherausforderung

OpenAPI-Spezifikationen sind komplexe JSON- oder YAML-Dateien mit einer präzisen Struktur. Einfache maschinelle Übersetzungstools machen sie kaputt, weil sie nicht verstehen, was übersetzt werden sollte und was nicht.

Intelligente Erkennung und Validierung

l10n.dev erkennt OpenAPI-Spezifikationen automatisch und behandelt sie mit besonderer Sorgfalt:

• Automatische Erkennung: Der Service erkennt OpenAPI-Dateien anhand der openapi-Eigenschaft und aktiviert eine spezialisierte Handhabung.
• Strukturvalidierung: Während der Übersetzung wird das Schema validiert, um sicherzustellen, dass es eine gültige OpenAPI-Spezifikation ist. Wenn strukturelle Probleme auftreten, wird die Übersetzung wiederholt, um sie zu beheben.
• Selektive Übersetzung: Die KI versteht den semantischen Unterschied zwischen technischen Identifikatoren und menschenlesbaren Inhalten. Nur menschenlesbare Felder werden übersetzt, während technische Identifikatoren unberührt bleiben.

Beispiel: Was übersetzt wird

Vor der Übersetzung (Englisch):

{
  "paths": {
    "/users/{userId}/profile": {
      "parameters": [
        {
          "name": "userId",
          "in": "path",
          "description": "The unique identifier of the user",
          "schema": { "type": "string" }
        }
      ]
    }
  },
  "components": {
    "schemas": {
      "UserStatus": {
        "type": "string",
        "enum": ["active", "inactive", "pending"],
        "description": "The current status of the user account"
      }
    }
  }
}

Nach der Übersetzung ins Japanische:

{
  "paths": {
    "/users/{userId}/profile": {
      "parameters": [
        {
          "name": "userId",
          "in": "path",
          "description": "ユーザーの一意の識別子",
          "schema": { "type": "string" }
        }
      ]
    }
  },
  "components": {
    "schemas": {
      "UserStatus": {
        "type": "string",
        "enum": ["active", "inactive", "pending"],
        "description": "ユーザーアカウントの現在のステータス"
      }
    }
  }
}

Beibehaltung von Datentypen

Ein kritischer Aspekt der OpenAPI-Lokalisierung ist die Beibehaltung von JSON-Datentypen. Der Service stellt sicher, dass:

• Zahlen Zahlen bleiben (nicht in Zeichenfolgen konvertiert)
• Booleans true/false bleiben (nicht in Wörter übersetzt)
• Null-Werte null bleiben (nicht in Text konvertiert)

Zum Beispiel dieses Schema mit verschiedenen Datentypen:

{
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 123
          },
          "price": {
            "type": "number",
            "example": 29.99
          },
          "inStock": {
            "type": "boolean",
            "example": true
          },
          "discount": {
            "type": "number",
            "nullable": true,
            "example": null
          }
        }
      }
    }
  }
}

Die übersetzte Spezifikation bewahrt all diese Typen exakt – was sicherstellt, dass die Spezifikation gültig bleibt und sicher in der Produktion verwendet werden kann, ohne API-Clients oder Dokumentationsgeneratoren zu beschädigen.

Nahtlose Integration mit VS Code

Das Übersetzen von OpenAPI-Spezifikationen funktioniert nahtlos über die VS Code-Erweiterung, sodass Sie Ihre API-Dokumentation direkt in Ihrer Entwicklungsumgebung lokalisieren können.

Wie es in VS Code funktioniert:

1. Öffnen Sie Ihre OpenAPI-Spezifikationsdatei (openapi.json oder openapi.yaml)
2. Klicken Sie mit der rechten Maustaste in den Editor und wählen Sie "Translate JSON"
3. Wählen Sie Ihre Zielsprache (z. B. Japanisch, Deutsch, Spanisch)
4. Die Erweiterung erstellt eine lokalisierte Version, in der alle Beschreibungen übersetzt sind, während die exakte Struktur erhalten bleibt

Sehen Sie es in Aktion

Hier ist ein Live-Beispiel für die Übersetzung einer englischen OpenAPI-Spezifikation ins Japanische innerhalb von VS Code:

Vorteile für Entwickler

• Keine defekten Spezifikationen: Die übersetzte OpenAPI-Datei bleibt zu 100 % gültig und kann ohne Änderungen in Swagger UI, Redoc, Scalar oder anderen OpenAPI-Tools verwendet werden.
• Keine manuellen Korrekturen: Feldnamen, Enum-Werte, $ref-Pfade und Schematypen werden niemals geändert – was eine Nachbearbeitung überflüssig macht.
• Kontextbewusste Beschreibungen: Die KI versteht den Kontext Ihrer API und übersetzt Beschreibungen mit angemessener technischer Terminologie und Tonfall.

Anwendungsfälle für OpenAPI-Lokalisierung

Die Lokalisierung Ihrer OpenAPI-Spezifikationen ist besonders wertvoll für:

Öffentliche API-Dokumentation

Wenn Sie eine öffentliche API für globale Entwickler erstellen, verbessert die Bereitstellung von Dokumentationen in mehreren Sprachen die Akzeptanz erheblich. Entwickler integrieren APIs eher, wenn die Dokumentation in ihrer Muttersprache vorliegt.

Entwickler-Onboarding

Lokalisierte API-Spezifikationen machen das Onboarding für internationale Teams schneller. Neue Entwickler können Endpunkte, Parameter und Schemata ohne Sprachbarrieren verstehen.

Mehrsprachige Teams

Wenn Ihr Entwicklungsteam über mehrere Länder verteilt ist, verbessert die API-Dokumentation in der Sprache jedes Teammitglieds die Zusammenarbeit und reduziert Missverständnisse.

Erste Schritte

Bereit, Ihre OpenAPI-Spezifikationen zu lokalisieren? Sie haben zwei Optionen: