English

العربية

English

العربية

Appearance

Translating a specification ​

This guide is for producing roles: a member of a backend team publishing from the browser, or a pipeline using the API-dex CLI. At the end, a consumer who switches the portal to another language reads your API's titles, summaries and descriptions in that language, and the specification you published stays byte-for-byte unchanged.

How translated specifications work ​

Translations live outside the specification. You publish one canonical specification as usual, plus one overlay file per language that holds only the translated text. An overlay is a standard OpenAPI Overlay 1.x document: a list of actions, each pointing at a location in the specification with a JSONPath target and supplying the text to update.

API-dex stores the overlays next to the specification and merges the matching one in when a consumer opens the specification. The stored specification is never modified.

  • Supported languages: en-GB, nl-NL, de-DE, fr-FR, es-ES, se-SE and ar-SA.
  • Translate descriptive text only: titles, summaries and descriptions of the API, its tags, operations, parameters, responses and schema properties. Leave paths, operation IDs, parameter names and schema structure untouched, so the documented API always matches the one you published.
  • Partial translations are fine. Anything an overlay does not translate keeps its original text. Nothing appears blank.

Write an overlay ​

One file per language. The example below translates a small pet-store API into Dutch.

yaml
overlay: 1.0.0
info:
  title: Dutch translation
  version: 1.0.0
actions:
  - target: $.info
    update:
      title: Huisdierenwinkel API
      description: Nederlandse beschrijving.
  - target: $.tags[0]
    update:
      description: Huisdier bewerkingen
  - target: $.paths['/pets'].get
    update:
      summary: Huisdieren weergeven
      description: Geeft alle huisdieren terug.
  - target: $.paths['/pets'].get.parameters[0]
    update:
      description: Hoeveel items te retourneren.
  - target: $.paths['/pets'].get.responses['200']
    update:
      description: Een lijst met huisdieren.
  - target: $.components.schemas.Pet.properties.name
    update:
      description: De naam van het huisdier.

API-dex validates each overlay on upload: it must be an object with an overlay version of 1.x, at least one action, and a JSONPath target plus update or remove on every action. JSON and YAML are both accepted.

Publish from the browser ​

1

Open Upload spec

Select the environment, open APIs and start an upload. The Upload spec page has four steps: Destination, Specification, Overlays, Review.

2

Choose the destination and the specification

Pick the product, or the category whose products share the specification, then drop the OpenAPI file.

3

Attach overlays

In the Overlays step, select Attach overlay for each language you have a file for. The step is optional: without overlays, every portal language shows the same specification. Overlays attached to a category specification apply to every product in that category.

To make translations mandatory for this upload, turn on Require an overlay for every portal language.

4

Review and publish

The Review step lists the destination, the file and the attached overlays. Select Publish.

WARNING

A new specification version does not inherit the previous version's overlays. When the specification already has translations, the Overlays step lists them and asks you to keep or replace each language. The upload is blocked while a published language would be dropped.

Publish from a pipeline ​

Declare the overlays in the API-dex CLI manifest, next to the specification they translate:

yaml
products:
  - name: pets-api
    openapi: openapi.yaml
    overlays:
      - locale: nl-NL
        path: overlays/nl-NL.yaml
      - locale: de-DE
        path: overlays/de-DE.yaml
categories:
  - name: payments
    openapi: payments.yaml
    overlays:            # applies to every product inheriting this spec
      - locale: nl-NL
        path: overlays/payments-nl-NL.yaml
    products:
      - name: refunds-api
        inheritSpec: true

Then run the usual upload:

bash
apidex-cli upload-spec --environment <environment-id> manifest.yaml

The CLI refuses an upload that would silently drop a translation the portal already has for that specification. Declare the overlay in the manifest, or remove the translations first (see below).

To check overlays before uploading, for example in the specification repository's CI:

bash
apidex-cli validate manifest.yaml --require-locales nl-NL,de-DE

This validates every overlay file and fails when a specification lacks an overlay for one of the required languages.

Remove translations ​

Administrators and CI/CD accounts remove all translations of a specification with the platform API:

bash
DELETE /api/specs/{specId}/overlays

The specification is served in its original language for every portal language from the next read. To replace a single language instead, upload a new overlay for that language; other languages are left alone.

What consumers see ​

  • The specification renders in the portal language the consumer has selected. Where no overlay exists for that language, API-dex falls back to the same language in another region (nl serves nl-NL), then to the original text.
  • Switching the portal language reloads the specification in place.
  • Downloading the specification gives the language on screen. Because only descriptive text is translated, the file still describes the same API and works in any OpenAPI tool.