How to Localize OpenAPI Specifications

OpenAPI specifications are the backbone of modern API documentation. Localizing them in multiple languages helps developers worldwide understand and integrate with your API. But translating OpenAPI specs isn't straightforward — you need to preserve structure while localizing human-readable content.

What is OpenAPI?

OpenAPI (formerly Swagger) is a standard format for describing REST APIs. It includes endpoints, request/response schemas, parameters, authentication methods, and detailed descriptions. These specifications power tools like Swagger UI, Redoc, Scalar, and code generators — making them critical for developer experience.

The Translation Challenge

OpenAPI specifications are complex JSON or YAML files with a precise structure. Simple machine translation tools will break them because they don't understand what should and shouldn't be translated.

Smart Detection and Validation

l10n.dev automatically detects OpenAPI specifications and handles them with special care:

• Automatic Detection: The service recognizes OpenAPI files by the openapi property and activates specialized handling.
• Structure Validation: During translation, the schema is validated to ensure it's a valid OpenAPI spec. If any structural issues arise, the translation is retried to fix them.
• Selective Translation: AI understands the semantic difference between technical identifiers and human-readable content. Only human-readable fields are translated while technical identifiers remain untouched.

Example: What Gets Translated

Before translation (English):

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

After translation to Japanese:

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

Data Type Preservation

One critical aspect of OpenAPI localization is maintaining JSON data types. The service ensures that:

• Numbers stay numbers (not converted to strings)
• Booleans remain true/false (not translated to words)
• Null values stay null (not converted to text)

For example, this schema with various data types:

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

The translated spec will preserve all these types exactly — ensuring the specification remains valid and can be used safely in production without breaking API clients or documentation generators.

Seamless Integration with VS Code

Translating OpenAPI specs works seamlessly through the VS Code extension, allowing you to localize your API documentation directly in your development environment.

How It Works in VS Code:

1. Open your OpenAPI specification file (openapi.json or openapi.yaml)
2. Right-click in the editor and select "Translate JSON"
3. Choose your target language (e.g., Japanese, German, Spanish)
4. The extension creates a localized version with all descriptions translated while preserving the exact structure

See It in Action

Here's a live example of translating an English OpenAPI spec to Japanese inside VS Code:

Benefits for Developers

• No Broken Specs: The translated OpenAPI file remains 100% valid and can be used in Swagger UI, Redoc, Scalar, or any OpenAPI tooling without modifications.
• No Manual Fixes: Field names, enum values, $ref paths, and schema types are never altered — eliminating the need for post-translation cleanup.
• Context-Aware Descriptions: AI understands the context of your API and translates descriptions with appropriate technical terminology and tone.

Use Cases for OpenAPI Localization

Localizing your OpenAPI specifications is especially valuable for:

Public API Documentation

If you're building a public API for global developers, providing documentation in multiple languages dramatically improves adoption. Developers are more likely to integrate with APIs when documentation is in their native language.

Developer Onboarding

Localized API specs make onboarding faster for international teams. New developers can understand endpoints, parameters, and schemas without language barriers.

Multi-Language Teams

If your development team spans multiple countries, having API documentation in each team member's language improves collaboration and reduces miscommunication.

Getting Started

Ready to localize your OpenAPI specifications? You have two options: