Como Localizar Especificações OpenAPI

Especificações OpenAPI são a espinha dorsal da documentação moderna de APIs. Localizá-las em várias línguas 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 alimentam 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

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

Detecção e Validação Inteligente

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 da 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 intactos.

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

Depois da tradução para o 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 dos Tipos de Dados

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

• Números permanecem números (não convertidos em strings)
• Booleanos permanecem true/false (não traduzidos para palavras)
• Valores nulos permanecem nulos (não convertidos em 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 Sem Costura 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 em 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 "Traduzir JSON"
3. Escolha seu idioma-alvo (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 traduzir 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 Conscientes do Contexto: A IA entende o contexto da sua API e traduz descrições com a terminologia técnica e o 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á construindo uma API pública para desenvolvedores globais, fornecer documentação em várias línguas melhora dramaticamente a adoção. Desenvolvedores têm mais chances de integrar com APIs quando a documentação está em sua língua nativa.

Integração de Desenvolvedores

Especificações de API localizadas tornam a integração mais rápida 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 na língua de cada membro da equipe melhora a colaboração e reduz a desinformação.

Começando

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