`x-ibm-languages` 사용하여 다국어 API 및 제품 문서 작성

API및 제품 OpenAPI 정의에서 x-ibm-languages 확장을 사용하여 다국어 API및 제품 문서를 작성하십시오.

단일 API 정의를 유지하면서 API 이니셔티브를 글로벌 사용자 기반으로 확장할 수 있습니다. 번역은 사용자 정의 구성 및 제어로 이루어지므로 API 문서 및 API 이용자 모두에 맞게 사용자 조정할 수 있습니다. API Connect 에서 사용되는 확장은 x-ibm-languages로 YAML 파일에 직접 추가됩니다. 이러한 확장 기능은 이후 컨슈머 카탈로그에서 사용되므로, 컨슈머 카탈로그가 어떤 언어로 설정되어 있든 API 및 제품 정의에 포함된 번역 내용이 그대로 반영됩니다.

번역된 텍스트가 필요할 때마다 다음 구문을 API 또는 제품 YAML 파일에 추가하십시오.

x-ibm-languages:
  item_name:
    language_code: translated_text

여기서,

item_name은 번역할 항목의 이름입니다(예: summary).

language_code는 번역 언어의 ISO 코드입니다. ISO 코드와 함께 지원되는 언어가 다음 표에 나열되어 있습니다.

표 1. 지원되는 언어 코드 목록
언어	코드
중국어	`zh_cn`
대만어	`zh_tw`
네덜란드어	`nl`
영어	`en`
프랑스어	`fr`
독일어	`de`
이탈리아어	`it`
일본어	`ja`
한국어	`ko`
포르투갈어	`pt`
스페인어	`es`
터키어	`tr`

translated_text 는 개발자 포털에서 항목에 대해 표시할 변환된 텍스트입니다.

참고: Consumer Catalog 는 OpenAPI 정의의 기본 언어가 영어라고 자동으로 가정합니다. 정의에서 다른 기본 언어를 사용하려면, OpenAPI 정의의 확장 x-ibm-languages 섹션에 다음 구문을 사용하여 영어 번역과 기본 언어 텍스트를 모두 포함해야 합니다:

x-ibm-languages:
  item_name:
    en: English_translated_text
    default_language_code: default_language_text

기본 언어로 프랑스어를 사용하여 OpenAPI YAML 파일을 작성하는 방법에 대한 예제는 예제 절을 참조하십시오.

예

fr 언어 확장을 포함하는 API OpenAPI YAML 파일의 예입니다. 여기서 영어는 기본 언어입니다.

swagger: '2.0'
info:
  x-ibm-name: climbing-weather-api
  title: Climbing Weather API
  version: 1.0.0
  x-ibm-languages:
    title:
      fr: Climat d'escalade
schemes:
  - https
host: $(catalog.host)
consumes:
  - application/json
produces:
  - application/json
x-ibm-configuration:
  assembly:
    execute:
      - invoke:
          target-url: 'https://1234.com'
          title: 3 day forecast invocation
          cache-response: time-to-live
          cache-key: $(request.search)
  gateway: datapower-gateway
  enforced: true
  testable: true
  phase: realized
  cors:
    enabled: true
paths:
  /weather/forecast:
    get:
      summary: Retrieve the 3 day forecast for a location
      description: Retrieve the locations weather forecast descriptions for the next 3 days and nights
      operationId: getWeather
      x-ibm-languages:
        summary:
          fr: Récupérer la prévision de 3 jours pour un emplacement
        description:
          fr: Récupérer les descriptions des prévisions météo pour les 3 prochains jours et les nuits
      tags:
        - Weather
      parameters:
        - name: zip
          type: string
          in: query
          description: A 5 number zip code
          x-ibm-languages:
            description:
              fr: Un code postal à 5 numéros
        - name: country
          type: string
          in: query
          description: A 2 letter country code
          x-ibm-languages:
            description:
              fr: Un code de pays de 2 lettres
        - name: lat
          type: string
          in: query
          description: A latitude value between -90 and 90
          x-ibm-languages:
            description:
              fr: Une valeur de latitude entre -90 et 90          
        - name: lon
          type: string
          in: query
          description: A longitude value between -180 and 180
          x-ibm-languages:
            description:
              fr: Une valeur de longitude entre -180 et 180          
      responses:
        '200':
          description: Success
          x-ibm-languages:
            description:
              fr: Succès 
        '400':
          description: Bad Request
          x-ibm-languages:
            description:
              fr: Mauvaise Demande           
        '408':
          description: Request Timeout
          x-ibm-languages:
            description:
              fr: Délai de délai de demande           
        '500':
          description: Internal Server Error
          x-ibm-languages:
            description:
              fr: Erreur Interne du Serveur           
basePath: /
tags:
  - name: Weather
    description: Sample API to get weather forecast data
    x-ibm-languages:
      description:
        fr: Exemple d'API pour obtenir des données météorologiques
securityDefinitions:
  client-secret:
    type: apiKey
    description: ''
    in: header
    name: X-IBM-Client-Secret
  client-id:
    type: apiKey
    description: ''
    in: header
    name: X-IBM-Client-Id
security:
  - client-secret: []
    client-id: []

fr 언어 확장을 포함하는 제품 OpenAPI YAML 파일의 예입니다. 여기서 영어는 기본 언어입니다.

product: 1.0.0
info:
  name: climbing-weather
  title: Climbing Weather
  version: 1.0.0
  description: This is a product about weather.
  x-ibm-languages:
    title:
      fr: Météo traduite
    description:
      fr: C'est un produit sur la météo.
    termsOfService:
      fr: Quid ergo aliud intellegetur en francais.
  contact:
    name: Ralph Renli
    email: ralph.renli@example.com
    url: 'https://weather.example.com/climbing/info'
  license:
    name: MIT License
    url: 'https://choosealicense.com/licenses/mit/'
    x-ibm-languages:
      name:
        fr: License de MIT
  termsOfService: Quid ergo aliud intellegetur nisi uti ne quae pars naturae neglegatur? Quis est tam dissimile homini. De quibus cupio scire quid sentias.
  categories:
    - Portal/Testing/Language
    - Portal/Testing/Language/UTF8
    - Portal/Testing/Weather
visibility:
  view:
    enabled: true
    type: public
    tags: []
    orgs: []
  subscribe:
    enabled: true
    type: authenticated
    tags: []
    orgs: []
apis:
  climbing-weather:
    id: 593f972be4b06fb4e0dce879
plans:
  a-call-a-day:
    title: A call a day
    description: "One call every day. That's it!"
    x-ibm-languages:
      title:
        fr: "Un appel par jour"
      description:
        fr: "Un appel tous les jours. C'est tout!"
    apis: {}
    rate-limits:
      One Call Per Day:
        hard-limit: true
        value: 1/1day
  ten-calls-per-day:
    title: 10 Calls a day
    description: '10 times more calls than the next best competitor plan!'
    x-ibm-languages:
      title:
        fr: "10 appels par jour"
      description:
        fr: "10 fois plus d'appels que le prochain meilleur plan concurrent!"
    apis: {}
    rate-limits:
      10 calls per day:
        hard-limit: true
        value: 10/1minute
  11-calls-every-day:
    title: 11 Calls a day
    description: 'Need just one more call? Then this is the plan for you!'
    x-ibm-languages:
      title:
        fr: "11 appels par jour"
      description:
        fr: "Vous n'avez besoin que d'un appel supplémentaire? Alors c'est le plan pour vous!"
    apis: {}
    rate-limits:
      11 calls per day:
        hard-limit: true
        value: 11/1day
  25-calls-per-day:
    title: 25 Calls per day
    description: So you want even more calls?
    apis: {}
    x-ibm-languages:
      title:
        fr: "25 appels par jour"
      description:
        fr: "Vous voulez donc encore plus d'appels?"
    rate-limits:
      25 calls per day:
        hard-limit: true
        value: 25/1day
  100-calls-per-day:
    title: 100 Calls every day
    description: 'You get 100 calls each and every day!'
    x-ibm-languages:
      title:
        fr: "100 appels par jour"
      description:
        fr: "Vous recevez 100 appels chaque jour"
    apis: {}
    rate-limits:
      100 Calls per day:
        hard-limit: true
        value: 100/1day

기본 언어로 프랑스어를 사용하여 OpenAPI YAML 파일을 작성하는 방법의 예는 다음과 같습니다.

info:
  name: climat-d-escalade
  title: Climat d'escalade
  version: 1.0.0
  x-ibm-languages:
    title:
      en: Climbing Weather API
      fr: Climat d'escalade
...

이 예제는 기본 프랑스어 및 영어 번역이 모두 x-ibm-languages 섹션에 제공됨을 보여줍니다.

x-ibm-languages 사용하여 다국어 API 및 제품 문서 작성

예

`x-ibm-languages` 사용하여 다국어 API 및 제품 문서 작성