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. 편집기에서 마우스 오른쪽 버튼을 클릭하고 "Translate JSON"을 선택합니다.
3. 대상 언어를 선택합니다(예: 일본어, 독일어, 스페인어).
4. 확장 프로그램은 정확한 구조를 보존하면서 모든 설명이 번역된 현지화된 버전을 만듭니다.

실제 작동 모습 보기

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

개발자를 위한 혜택

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

OpenAPI 현지화 사용 사례

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

공용 API 문서

글로벌 개발자를 위한 공용 API를 구축하는 경우 여러 언어로 문서를 제공하면 채택률이 크게 향상됩니다. 개발자는 문서가 모국어로 되어 있을 때 API를 통합할 가능성이 더 높습니다.

개발자 온보딩

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

다국어 팀

개발 팀이 여러 국가에 걸쳐 있는 경우 각 팀원의 언어로 API 문서를 보유하면 협업이 개선되고 의사소통 오류가 줄어듭니다.

시작하기

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