Cara Melokalisasi Spesifikasi OpenAPI

Spesifikasi OpenAPI adalah tulang punggung dokumentasi API modern. Melokalisasi mereka dalam berbagai bahasa membantu pengembang di seluruh dunia memahami dan mengintegrasikan dengan API Anda. Namun, menerjemahkan spesifikasi OpenAPI tidaklah sederhana — Anda perlu mempertahankan struktur sambil melokalisasi konten yang dapat dibaca manusia.

Apa itu OpenAPI?

OpenAPI (sebelumnya Swagger) adalah format standar untuk mendeskripsikan REST API. Ini mencakup endpoint, skema permintaan/response, parameter, metode otentikasi, dan deskripsi yang detail. Spesifikasi ini mendukung alat seperti Swagger UI, Redoc, Scalar, dan generator kode — menjadikannya penting untuk pengalaman pengembang.

Tantangan Penerjemahan

Spesifikasi OpenAPI adalah file JSON atau YAML yang kompleks dengan struktur yang tepat. Alat penerjemahan 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 menangani mereka dengan perhatian khusus:

• Deteksi Otomatis: Layanan ini mengenali file OpenAPI dengan properti openapi dan mengaktifkan penanganan khusus.
• Validasi Struktur: Selama penerjemahan, skema divalidasi untuk memastikan itu adalah spesifikasi OpenAPI yang valid. Jika ada masalah struktural yang muncul, penerjemahan akan dicoba kembali untuk memperbaikinya.
• Penerjemahan Selektif: AI memahami perbedaan semantik antara pengidentifikasi teknis dan konten yang dapat dibaca manusia. Hanya field yang dapat dibaca manusia yang diterjemahkan sementara pengidentifikasi teknis tetap tidak tersentuh.

Contoh: Apa yang Diterjemahkan

Sebelum penerjemahan (Bahasa 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 penerjemahan ke dalam bahasa 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 kritis dari lokalisasi OpenAPI adalah mempertahankan tipe data JSON. Layanan ini memastikan bahwa:

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

Sebagai contoh, 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 yang diterjemahkan akan mempertahankan semua tipe ini dengan tepat — memastikan spesifikasi tetap valid dan dapat digunakan dengan aman di produksi tanpa merusak klien API atau generator dokumentasi.

Integrasi Tanpa Hambatan dengan VS Code

Menerjemahkan spesifikasi OpenAPI bekerja dengan lancar melalui ekstensi VS Code, memungkinkan Anda untuk melokalisasi 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 "Terjemahkan JSON"
3. Pilih bahasa target Anda (misalnya, Jepang, Jerman, Spanyol)
4. Ekstensi membuat versi terlokalisasi dengan semua deskripsi diterjemahkan sambil mempertahankan struktur yang tepat

Lihat Dalam Aksi

Berikut adalah contoh langsung menerjemahkan spesifikasi OpenAPI bahasa Inggris ke dalam 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 lainnya tanpa modifikasi.
• Tidak Ada Perbaikan Manual: Nama field, nilai enum, jalur $ref, dan tipe skema tidak pernah diubah — menghilangkan kebutuhan untuk pembersihan pasca-penerjemahan.
• Deskripsi yang Sadar Konteks: AI memahami konteks API Anda dan menerjemahkan deskripsi dengan terminologi teknis dan nada yang sesuai.

Kasus Penggunaan untuk Lokalisasi OpenAPI

Melokalisasi 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 mungkin untuk mengintegrasikan dengan API ketika dokumentasi ada dalam bahasa asli mereka.

Onboarding Pengembang

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

Tim Multibahasa

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

Memulai

Siap untuk melokalisasi spesifikasi OpenAPI Anda? Anda memiliki dua opsi: