So lokalisiert man OpenAPI-Spezifikationen

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

Was ist OpenAPI?

OpenAPI (früher Swagger) ist ein Standardformat zur Beschreibung von REST-APIs. Es umfasst Endpunkte, Anfrage-/Antwort-Schemas, Parameter, Authentifizierungsmethoden und detaillierte Beschreibungen. Diese Spezifikationen treiben Tools wie Swagger UI, Redoc, Scalar und Code-Generatoren an – was sie entscheidend für die Entwicklererfahrung macht.

Die Übersetzungsherausforderung

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

Intelligente Erkennung und Validierung

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

• Automatische Erkennung: Der Dienst erkennt OpenAPI-Dateien anhand der openapi-Eigenschaft und aktiviert die spezialisierte Behandlung.
• 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 erneut versucht, um sie zu beheben.
• Selektive Übersetzung: KI versteht den semantischen Unterschied zwischen technischen Identifikatoren und menschenlesbaren Inhalten. Nur menschenlesbare Felder werden übersetzt, während technische Identifikatoren unangetastet bleiben.

Beispiel: Was wird übersetzt

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": "ユーザーアカウントの現在のステータス"
      }
    }
  }
}

Erhaltung der Datentypen

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

• Zahlen bleiben Zahlen (werden nicht in Strings umgewandelt)
• Booleans bleiben true/false (werden nicht in Wörter übersetzt)
• Nullwerte bleiben null (werden nicht in Text umgewandelt)

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 wird all diese Typen genau beibehalten – wodurch sichergestellt wird, 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

Die Übersetzung von OpenAPI-Spezifikationen funktioniert nahtlos über die VS Code-Erweiterung, die es Ihnen ermöglicht, Ihre API-Dokumentation direkt in Ihrer Entwicklungsumgebung zu lokalisieren.

So funktioniert es in VS Code:

1. Öffnen Sie Ihre OpenAPI-Spezifikationsdatei (openapi.json oder openapi.yaml)
2. Klicken Sie mit der rechten Maustaste im Editor und wählen Sie "JSON übersetzen"
3. Wählen Sie Ihre Zielsprache (z. B. Japanisch, Deutsch, Spanisch)
4. Die Erweiterung erstellt eine lokalisierte Version mit allen übersetzten Beschreibungen, während die genaue Struktur beibehalten wird.

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 beschädigten Spezifikationen: Die übersetzte OpenAPI-Datei bleibt 100 % gültig und kann in Swagger UI, Redoc, Scalar oder jedem OpenAPI-Tool ohne Änderungen verwendet werden.
• Keine manuellen Korrekturen: Feldnamen, Enum-Werte, $ref-Pfade und Schema-Typen werden niemals verändert – was die Notwendigkeit für Nachbearbeitungen nach der Übersetzung beseitigt.
• Kontextbewusste Beschreibungen: KI versteht den Kontext Ihrer API und übersetzt Beschreibungen mit angemessener technischer Terminologie und Ton.

Anwendungsfälle für die 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 sind eher bereit, sich mit APIs zu integrieren, wenn die Dokumentation in ihrer Muttersprache verfasst ist.

Entwickler-Onboarding

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

Mehrsprachige Teams

Wenn Ihr Entwicklungsteam mehrere Länder umfasst, verbessert die Dokumentation der API in der Sprache jedes Teammitglieds die Zusammenarbeit und reduziert Missverständnisse.

Erste Schritte

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