Como Localizar Especificações OpenAPI

As especificações OpenAPI são a espinha dorsal da documentação de API moderna. Localizá-las em vários idiomas ajuda desenvolvedores em todo o mundo a entender e integrar sua API. Mas traduzir especificações OpenAPI não é simples — você precisa preservar a estrutura enquanto localiza o conteúdo legível por humanos.

O que é OpenAPI?

OpenAPI (anteriormente Swagger) é um formato padrão para descrever APIs REST. Inclui endpoints, esquemas de solicitação/resposta, parâmetros, métodos de autenticação e descrições detalhadas. Essas especificações impulsionam ferramentas como Swagger UI, Redoc, Scalar e geradores de código — tornando-as críticas para a experiência do desenvolvedor.

O Desafio da Tradução

As especificações OpenAPI são arquivos JSON ou YAML complexos com uma estrutura precisa. Ferramentas simples de tradução automática irão quebrá-los porque não entendem o que deve e o que não deve ser traduzido.

Detecção Inteligente e Validação

O l10n.dev detecta automaticamente especificações OpenAPI e as trata com cuidado especial:

• Detecção Automática: O serviço reconhece arquivos OpenAPI pela propriedade openapi e ativa o manuseio especializado.
• Validação de Estrutura: Durante a tradução, o esquema é validado para garantir que seja uma especificação OpenAPI válida. Se surgirem problemas estruturais, a tradução é tentada novamente para corrigi-los.
• Tradução Seletiva: A IA entende a diferença semântica entre identificadores técnicos e conteúdo legível por humanos. Apenas campos legíveis por humanos são traduzidos, enquanto identificadores técnicos permanecem intocados.

Exemplo: O que é traduzido

Antes da tradução (Inglês):

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

Após a tradução para japonês:

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

Preservação de Tipos de Dados

Um aspecto crítico da localização OpenAPI é manter os tipos de dados JSON. O serviço garante que:

• Números permaneçam números (não convertidos para strings)
• Booleanos permaneçam true/false (não traduzidos para palavras)
• Valores nulos permaneçam nulos (não convertidos para texto)

Por exemplo, este esquema com vários tipos de dados:

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

A especificação traduzida preservará todos esses tipos exatamente — garantindo que a especificação permaneça válida e possa ser usada com segurança em produção sem quebrar clientes de API ou geradores de documentação.

Integração Perfeita com o VS Code

Traduzir especificações OpenAPI funciona perfeitamente através da extensão do VS Code, permitindo que você localize sua documentação de API diretamente no seu ambiente de desenvolvimento.

Como funciona no VS Code:

1. Abra seu arquivo de especificação OpenAPI (openapi.json ou openapi.yaml)
2. Clique com o botão direito no editor e selecione "Translate JSON"
3. Escolha seu idioma de destino (por exemplo, japonês, alemão, espanhol)
4. A extensão cria uma versão localizada com todas as descrições traduzidas enquanto preserva a estrutura exata

Veja em Ação

Aqui está um exemplo ao vivo de tradução de uma especificação OpenAPI em inglês para japonês dentro do VS Code:

Benefícios para Desenvolvedores

• Sem Especificações Quebradas: O arquivo OpenAPI traduzido permanece 100% válido e pode ser usado no Swagger UI, Redoc, Scalar ou qualquer ferramenta OpenAPI sem modificações.
• Sem Correções Manuais: Nomes de campos, valores de enum, caminhos $ref e tipos de esquema nunca são alterados — eliminando a necessidade de limpeza pós-tradução.
• Descrições com Consciência de Contexto: A IA entende o contexto da sua API e traduz descrições com terminologia técnica e tom apropriados.

Casos de Uso para Localização OpenAPI

Localizar suas especificações OpenAPI é especialmente valioso para:

Documentação de API Pública

Se você está criando uma API pública para desenvolvedores globais, fornecer documentação em vários idiomas melhora drasticamente a adoção. Desenvolvedores são mais propensos a integrar APIs quando a documentação está em seu idioma nativo.

Onboarding de Desenvolvedores

Especificações de API localizadas tornam o onboarding mais rápido para equipes internacionais. Novos desenvolvedores podem entender endpoints, parâmetros e esquemas sem barreiras linguísticas.

Equipes Multilíngues

Se sua equipe de desenvolvimento abrange vários países, ter documentação de API no idioma de cada membro da equipe melhora a colaboração e reduz a falha de comunicação.

Primeiros Passos

Pronto para localizar suas especificações OpenAPI? Você tem duas opções: