Usando x-ibm-languages para criar API multilíngue e documentação do produto

Editar online

Crie a documentação multilíngue da API e do Produto usando a extensão x-ibm-languages em suas definições de API e do produto OpenAPI

É possível escalar suas iniciativas de API para uma base do usuário global, enquanto ainda mantém uma única definição de API. As traduções são customizadas, configuradas e controladas para que possam ser adaptadas à documentação da API e ao consumidor da API. As extensões usadas no API Connect são incluídas diretamente no arquivo YAML como x-ibm-languages. Essas extensões são então utilizadas no Catálogo do Consumidor, de modo que, independentemente do idioma em que o Catálogo do Consumidor esteja configurado, ele reflita as traduções contidas nas definições da API e do produto.

Inclua a seguinte sintaxe no arquivo YAML da API ou Produto em cada ponto em que você requer algum texto traduzido:
x-ibm-languages:
  item_name:
    language_code: translated_text
Em que:
  • item_name é o nome do item que você deseja traduzir, por exemplo, summary.
  • language_code é o código ISO para o idioma de tradução. Idiomas suportados com seus códigos ISO estão listados na tabela a seguir.
    Tabela 1. Lista de códigos de idiomas suportados
    Idioma Código
    Chinês, simplificado zh_cn
    Chinês, tradicional zh_tw
    Holandês nl
    Inglês en
    Francês fr
    Alemão de
    Italiano it
    Japonês ja
    Coreano ko
    Português pt
    Espanhol es
    Turco tr
  • translated_text é o texto traduzido que você deseja exibir para o item no Portal do Desenvolvedor.
Observação: O Catálogo do Consumidor assume automaticamente que o idioma padrão na definição do ` OpenAPI ` é o inglês. Se você quiser usar um idioma padrão diferente na definição, deve fornecer tanto a tradução em inglês quanto o texto no idioma padrão nas seções x-ibm-languages de extensão da sua definição de ` OpenAPI `, utilizando a seguinte sintaxe:
x-ibm-languages:
  item_name:
    en: English_translated_text
    default_language_code: default_language_text
Para obter um exemplo de como gravar um arquivo YAML do OpenAPI com francês como o idioma padrão, consulte a seção Exemplos .

Exemplos

Um arquivo YAML de API OpenAPI de exemplo que contém a extensão de idioma fr , em que inglês é o idioma padrão:
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: []
Um arquivo YAML de exemplo do Produto OpenAPI que contém a extensão de idioma fr , em que inglês é o idioma padrão:
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
Um exemplo de como gravar um arquivo YAML OpenAPI com francês como o idioma padrão:
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
...
Este exemplo mostra que tanto o idioma francês padrão quanto a tradução do idioma inglês devem ser fornecidos na seção x-ibm-languages.