Cómo localizar especificaciones de OpenAPI

Las especificaciones de OpenAPI son la columna vertebral de la documentación de API moderna. Localizarlas en varios idiomas ayuda a los desarrolladores de todo el mundo a comprender e integrarse con su API. Pero traducir especificaciones de OpenAPI no es sencillo: debe preservar la estructura mientras localiza el contenido legible por humanos.

¿Qué es OpenAPI?

OpenAPI (anteriormente Swagger) es un formato estándar para describir API REST. Incluye puntos finales, esquemas de solicitud/respuesta, parámetros, métodos de autenticación y descripciones detalladas. Estas especificaciones impulsan 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 los romperán porque no entienden qué se debe traducir y qué no.

Detección y validación inteligentes

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

• Detección automática: El servicio reconoce los archivos OpenAPI por la propiedad openapi y activa un manejo especializado.
• Validación de estructura: Durante la traducción, se valida el esquema para garantizar que sea una especificación OpenAPI válida. Si surge algún problema estructural, se vuelve a intentar la traducción para corregirlo.
• Traducción selectiva: La IA comprende 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 garantiza que:

• Los números sigan siendo números (no convertidos a cadenas)
• Los booleanos sigan siendo true/false (no traducidos a palabras)
• Los valores nulos sigan siendo null (no convertidos a 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 siga siendo válida y pueda usarse de forma segura en producción sin romper los clientes de API o los generadores de documentación.

Integración perfecta con VS Code

La traducción de especificaciones de OpenAPI funciona a la perfección a través de la extensión de VS Code, lo que le permite localizar la documentación de su API directamente en su entorno de desarrollo.

Cómo funciona en VS Code:

1. Abra su archivo de especificación OpenAPI (openapi.json u openapi.yaml)
2. Haga clic derecho en el editor y seleccione "Traducir JSON"
3. Elija su idioma de destino (p. ej., 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

Véalo en acción

Aquí hay un ejemplo en vivo de cómo traducir una especificación OpenAPI en inglés al japonés dentro de VS Code:

Beneficios para desarrolladores

• Sin especificaciones rotas: El archivo OpenAPI traducido sigue siendo 100% válido y puede usarse en Swagger UI, Redoc, Scalar o cualquier herramienta de OpenAPI sin modificaciones.
• Sin correcciones manuales: Los nombres de campos, valores de enumeración, rutas $ref y tipos de esquema nunca se alteran, eliminando la necesidad de una limpieza posterior a la traducción.
• Descripciones con conciencia del contexto: La IA comprende el contexto de su API y traduce las descripciones con la terminología técnica y el tono adecuados.

Casos de uso para la localización de OpenAPI

Localizar sus especificaciones de OpenAPI es especialmente valioso para:

Documentación de API pública

Si está creando una API pública para desarrolladores globales, proporcionar documentación en varios idiomas mejora drásticamente la adopción. Es más probable que los desarrolladores se integren con API cuando la documentación está en su idioma nativo.

Incorporación de desarrolladores

Las especificaciones de API localizadas hacen que la incorporación sea más rápida para los equipos internacionales. Los nuevos desarrolladores pueden comprender los puntos finales, los parámetros y los esquemas sin barreras lingüísticas.

Equipos multilingües

Si su equipo de desarrollo abarca varios países, tener la documentación de la API en el idioma de cada miembro del equipo mejora la colaboración y reduce la falta de comunicación.

Primeros pasos

¿Listo para localizar sus especificaciones de OpenAPI? Tiene dos opciones: