OpenAPI 사양을 현지화하는 방법

OpenAPI 사양은 현대 API 문서의 중추입니다. 이를 여러 언어로 현지화하면 전 세계 개발자들이 귀하의 API를 이해하고 통합하는 데 도움이 됩니다. 그러나 OpenAPI 사양을 번역하는 것은 간단하지 않습니다. 구조를 유지하면서 사람이 읽을 수 있는 내용을 현지화해야 합니다.

OpenAPI란?

OpenAPI(구 Swagger)는 REST API를 설명하기 위한 표준 형식입니다. 여기에는 엔드포인트, 요청/응답 스키마, 매개변수, 인증 방법 및 자세한 설명이 포함됩니다. 이러한 사양은 Swagger UI, Redoc, Scalar 및 코드 생성기와 같은 도구를 지원하며, 개발자 경험에 매우 중요합니다.

번역 도전 과제

OpenAPI 사양은 정밀한 구조를 가진 복잡한 JSON 또는 YAML 파일입니다. 간단한 기계 번역 도구는 번역해야 할 것과 번역하지 말아야 할 것을 이해하지 못하기 때문에 이를 깨뜨릴 수 있습니다.

스마트 감지 및 검증

l10n.dev는 OpenAPI 사양을 자동으로 감지하고 특별한 주의로 처리합니다:

• 자동 감지: 서비스는 openapi 속성으로 OpenAPI 파일을 인식하고 전문 처리를 활성화합니다.
• 구조 검증: 번역 중에 스키마가 유효한 OpenAPI 사양인지 검증됩니다. 구조적 문제가 발생하면 이를 수정하기 위해 번역이 재시도됩니다.
• 선택적 번역: AI는 기술 식별자와 사람이 읽을 수 있는 내용 간의 의미적 차이를 이해합니다. 오직 사람이 읽을 수 있는 필드만 번역되고 기술 식별자는 그대로 유지됩니다.

예: 무엇이 번역되는가

번역 전 (영어):

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

일본어로 번역 후:

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

데이터 유형 보존

OpenAPI 현지화의 중요한 측면 중 하나는 JSON 데이터 유형을 유지하는 것입니다. 서비스는 다음을 보장합니다:

• 숫자는 숫자로 유지됩니다(문자열로 변환되지 않음)
• 부울 값은 true/false로 유지됩니다(단어로 번역되지 않음)
• null 값은 null로 유지됩니다(텍스트로 변환되지 않음)

예를 들어, 다양한 데이터 유형을 가진 이 스키마:

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

번역된 사양은 이러한 모든 유형을 정확하게 보존하여 사양이 유효하게 유지되고 API 클라이언트나 문서 생성기를 손상시키지 않고 안전하게 프로덕션에서 사용할 수 있도록 합니다.

VS Code와의 원활한 통합

OpenAPI 사양의 번역은 VS Code 확장을 통해 원활하게 작동하여 개발 환경에서 직접 API 문서를 현지화할 수 있습니다.

VS Code에서 작동하는 방법:

1. OpenAPI 사양 파일(openapi.json 또는 openapi.yaml)을 엽니다.
2. 편집기에서 마우스 오른쪽 버튼을 클릭하고 "JSON 번역"을 선택합니다.
3. 대상 언어를 선택합니다(예: 일본어, 독일어, 스페인어).
4. 확장은 모든 설명이 번역된 현지화된 버전을 생성하면서 정확한 구조를 유지합니다.

작동 모습 보기

다음은 VS Code 내에서 영어 OpenAPI 사양을 일본어로 번역하는 실시간 예제입니다:

개발자를 위한 이점

• 손상되지 않은 사양: 번역된 OpenAPI 파일은 100% 유효성을 유지하며 Swagger UI, Redoc, Scalar 또는 기타 OpenAPI 도구에서 수정 없이 사용할 수 있습니다.
• 수동 수정 없음: 필드 이름, 열거형 값, $ref 경로 및 스키마 유형은 절대 변경되지 않으며, 번역 후 정리의 필요성을 없앱니다.
• 맥락 인식 설명: AI는 귀하의 API 맥락을 이해하고 적절한 기술 용어와 어조로 설명을 번역합니다.

OpenAPI 현지화의 사용 사례

OpenAPI 사양을 현지화하는 것은 특히 다음과 같은 경우에 유용합니다:

공공 API 문서

전 세계 개발자를 위한 공공 API를 구축하는 경우, 여러 언어로 문서를 제공하면 채택이 크게 향상됩니다. 문서가 개발자의 모국어로 제공될 때 API와 통합할 가능성이 높아집니다.

개발자 온보딩

현지화된 API 사양은 국제 팀의 온보딩을 더 빠르게 만듭니다. 새로운 개발자는 언어 장벽 없이 엔드포인트, 매개변수 및 스키마를 이해할 수 있습니다.

다국어 팀

개발 팀이 여러 국가에 걸쳐 있는 경우, 각 팀원의 언어로 API 문서를 제공하면 협업이 개선되고 오해가 줄어듭니다.

시작하기

OpenAPI 사양을 현지화할 준비가 되셨나요? 두 가지 옵션이 있습니다: