Cómo localizar especificaciones de OpenAPI

Las especificaciones de OpenAPI son la columna vertebral de la documentación moderna de APIs. Localizarlas en múltiples idiomas ayuda a desarrolladores de todo el mundo a entender e integrar tu API. Pero traducir las especificaciones de OpenAPI no es sencillo: necesitas preservar la estructura mientras localizas el contenido legible por humanos.

¿Qué es OpenAPI?

OpenAPI (anteriormente Swagger) es un formato estándar para describir APIs REST. Incluye endpoints, esquemas de solicitud/respuesta, parámetros, métodos de autenticación y descripciones detalladas. Estas especificaciones alimentan herramientas como Swagger UI, Redoc, Scalar y generadores de código, lo que las hace críticas para la experiencia del desarrollador.

El desafío de la traducción

Las especificaciones de OpenAPI son archivos JSON o YAML complejos con una estructura precisa. Las herramientas de traducción automática simples las romperán porque no entienden qué debe y qué no debe ser traducido.

Detección y validación inteligentes

l10n.dev detecta automáticamente especificaciones de OpenAPI y las maneja con especial cuidado:

• Detección automática: El servicio reconoce archivos de OpenAPI por la propiedad openapi y activa un manejo especializado.
• Validación de estructura: Durante la traducción, el esquema se valida para asegurar que sea una especificación de OpenAPI válida. Si surgen problemas estructurales, se reintenta la traducción para solucionarlos.
• Traducción selectiva: La IA entiende la diferencia semántica entre identificadores técnicos y contenido legible por humanos. Solo se traducen los campos legibles por humanos mientras que los identificadores técnicos permanecen intactos.

Ejemplo: Qué se traduce

Antes de la traducción (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"
      }
    }
  }
}

Después de la traducción al 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": "ユーザーアカウントの現在のステータス"
      }
    }
  }
}

Preservación de tipos de datos

Un aspecto crítico de la localización de OpenAPI es mantener los tipos de datos JSON. El servicio asegura que:

• Los números permanecen como números (no se convierten en cadenas)
• Los booleanos permanecen como verdadero/falso (no se traducen a palabras)
• Los valores nulos permanecen nulos (no se convierten en texto)

Por ejemplo, este esquema con varios tipos de datos:

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

La especificación traducida preservará todos estos tipos exactamente, asegurando que la especificación permanezca válida y pueda ser utilizada de forma segura en producción sin romper clientes de API o generadores de documentación.

Integración sin problemas con VS Code

Traducir especificaciones de OpenAPI funciona sin problemas a través de la extensión de VS Code, permitiéndote localizar tu documentación de API directamente en tu entorno de desarrollo.

Cómo funciona en VS Code:

1. Abre tu archivo de especificación de OpenAPI (openapi.json o openapi.yaml)
2. Haz clic derecho en el editor y selecciona "Traducir JSON"
3. Elige tu idioma objetivo (por ejemplo, japonés, alemán, español)
4. La extensión crea una versión localizada con todas las descripciones traducidas mientras preserva la estructura exacta

Velo en acción

Aquí tienes un ejemplo en vivo de traducir una especificación de OpenAPI en inglés a japonés dentro de VS Code:

Beneficios para desarrolladores

• Sin especificaciones rotas: El archivo de OpenAPI traducido permanece 100% válido y puede ser utilizado en Swagger UI, Redoc, Scalar o cualquier herramienta de OpenAPI sin modificaciones.
• Sin arreglos manuales: Los nombres de campos, valores de enum, rutas $ref y tipos de esquema nunca son alterados, eliminando la necesidad de limpieza posterior a la traducción.
• Descripciones conscientes del contexto: La IA entiende el contexto de tu API y traduce descripciones con la terminología técnica y el tono apropiados.

Casos de uso para la localización de OpenAPI

Localizar tus especificaciones de OpenAPI es especialmente valioso para:

Documentación de API pública

Si estás construyendo una API pública para desarrolladores globales, proporcionar documentación en múltiples idiomas mejora drásticamente la adopción. Los desarrolladores son más propensos a integrar APIs cuando la documentación está en su idioma nativo.

Integración de desarrolladores

Las especificaciones de API localizadas hacen que la integración sea más rápida para equipos internacionales. Los nuevos desarrolladores pueden entender endpoints, parámetros y esquemas sin barreras idiomáticas.

Equipos multilingües

Si tu equipo de desarrollo abarca múltiples países, tener documentación de API en el idioma de cada miembro del equipo mejora la colaboración y reduce la mala comunicación.

Comenzando

¿Listo para localizar tus especificaciones de OpenAPI? Tienes dos opciones: