Cara Melokalkan Spesifikasi OpenAPI

Spesifikasi OpenAPI adalah tulang punggung dokumentasi API modern. Melokalkannya ke dalam berbagai bahasa membantu pengembang di seluruh dunia memahami dan berintegrasi dengan API Anda. Namun, menerjemahkan spesifikasi OpenAPI tidaklah mudah — Anda perlu mempertahankan struktur sambil melokalkan konten yang dapat dibaca manusia.

Apa itu OpenAPI?

OpenAPI (sebelumnya Swagger) adalah format standar untuk mendeskripsikan REST API. Ini mencakup endpoint, skema permintaan/respons, parameter, metode autentikasi, dan deskripsi terperinci. Spesifikasi ini mendukung alat seperti Swagger UI, Redoc, Scalar, dan pembuat kode — menjadikannya sangat penting untuk pengalaman pengembang.

Tantangan Terjemahan

Spesifikasi OpenAPI adalah file JSON atau YAML yang kompleks dengan struktur yang tepat. Alat terjemahan mesin sederhana akan merusaknya karena mereka tidak memahami apa yang harus dan tidak boleh diterjemahkan.

Deteksi dan Validasi Cerdas

l10n.dev secara otomatis mendeteksi spesifikasi OpenAPI dan menanganinya dengan perhatian khusus:

• Deteksi Otomatis: Layanan ini mengenali file OpenAPI berdasarkan properti openapi dan mengaktifkan penanganan khusus.
• Validasi Struktur: Selama terjemahan, skema divalidasi untuk memastikan bahwa itu adalah spesifikasi OpenAPI yang valid. Jika muncul masalah struktural, terjemahan dicoba ulang untuk memperbaikinya.
• Terjemahan Selektif: AI memahami perbedaan semantik antara pengenal teknis dan konten yang dapat dibaca manusia. Hanya bidang yang dapat dibaca manusia yang diterjemahkan sementara pengenal teknis tetap tidak tersentuh.

Contoh: Apa yang Diterjemahkan

Sebelum terjemahan (Inggris):

{
  "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"
      }
    }
  }
}

Setelah terjemahan ke Jepang:

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

Pelestarian Tipe Data

Salah satu aspek penting dari lokalisasi OpenAPI adalah mempertahankan tipe data JSON. Layanan ini memastikan bahwa:

• Angka tetap angka (tidak dikonversi menjadi string)
• Boolean tetap true/false (tidak diterjemahkan menjadi kata-kata)
• Nilai null tetap null (tidak dikonversi menjadi teks)

Misalnya, skema ini dengan berbagai tipe data:

{
  "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
          }
        }
      }
    }
  }
}

Spesifikasi terjemahan akan mempertahankan semua tipe ini dengan tepat — memastikan spesifikasi tetap valid dan dapat digunakan dengan aman dalam produksi tanpa merusak klien API atau pembuat dokumentasi.

Integrasi Mulus dengan VS Code

Menerjemahkan spesifikasi OpenAPI bekerja dengan mulus melalui ekstensi VS Code, memungkinkan Anda melokalkan dokumentasi API Anda langsung di lingkungan pengembangan Anda.

Cara Kerjanya di VS Code:

1. Buka file spesifikasi OpenAPI Anda (openapi.json atau openapi.yaml)
2. Klik kanan di editor dan pilih "Translate JSON"
3. Pilih bahasa target Anda (misalnya, Jepang, Jerman, Spanyol)
4. Ekstensi membuat versi lokal dengan semua deskripsi diterjemahkan sambil mempertahankan struktur yang tepat

Lihat Beraksi

Berikut adalah contoh langsung menerjemahkan spesifikasi OpenAPI bahasa Inggris ke bahasa Jepang di dalam VS Code:

Manfaat bagi Pengembang

• Tidak Ada Spesifikasi yang Rusak: File OpenAPI yang diterjemahkan tetap 100% valid dan dapat digunakan di Swagger UI, Redoc, Scalar, atau alat OpenAPI apa pun tanpa modifikasi.
• Tidak Ada Perbaikan Manual: Nama bidang, nilai enum, jalur $ref, dan tipe skema tidak pernah diubah — menghilangkan kebutuhan untuk pembersihan pasca-terjemahan.
• Deskripsi Sadar Konteks: AI memahami konteks API Anda dan menerjemahkan deskripsi dengan terminologi teknis dan nada yang sesuai.

Kasus Penggunaan untuk Lokalisasi OpenAPI

Melokalkan spesifikasi OpenAPI Anda sangat berharga untuk:

Dokumentasi API Publik

Jika Anda membangun API publik untuk pengembang global, menyediakan dokumentasi dalam berbagai bahasa secara dramatis meningkatkan adopsi. Pengembang lebih cenderung berintegrasi dengan API jika dokumentasi dalam bahasa asli mereka.

Onboarding Pengembang

Spesifikasi API lokal membuat onboarding lebih cepat untuk tim internasional. Pengembang baru dapat memahami endpoint, parameter, dan skema tanpa hambatan bahasa.

Tim Multi-Bahasa

Jika tim pengembangan Anda mencakup beberapa negara, memiliki dokumentasi API dalam bahasa setiap anggota tim meningkatkan kolaborasi dan mengurangi miskomunikasi.

Memulai

Siap melokalkan spesifikasi OpenAPI Anda? Anda memiliki dua opsi: