Come localizzare le specifiche OpenAPI

Le specifiche OpenAPI sono la spina dorsale della moderna documentazione API. Localizzarle in più lingue aiuta gli sviluppatori di tutto il mondo a comprendere e integrarsi con la tua API. Ma tradurre le specifiche OpenAPI non è semplice: devi preservare la struttura mentre localizzi i contenuti leggibili dall'uomo.

Cos'è OpenAPI?

OpenAPI (precedentemente Swagger) è un formato standard per descrivere API REST. Include endpoint, schemi di richiesta/risposta, parametri, metodi di autenticazione e descrizioni dettagliate. Queste specifiche alimentano strumenti come Swagger UI, Redoc, Scalar e generatori di codice, rendendoli critici per l'esperienza dello sviluppatore.

La sfida della traduzione

Le specifiche OpenAPI sono file JSON o YAML complessi con una struttura precisa. Gli strumenti di traduzione automatica semplici li romperanno perché non capiscono cosa dovrebbe e cosa non dovrebbe essere tradotto.

Rilevamento intelligente e convalida

l10n.dev rileva automaticamente le specifiche OpenAPI e le gestisce con particolare attenzione:

• Rilevamento automatico: Il servizio riconosce i file OpenAPI dalla proprietà openapi e attiva una gestione specializzata.
• Convalida della struttura: Durante la traduzione, lo schema viene convalidato per garantire che sia una specifica OpenAPI valida. Se sorgono problemi strutturali, la traduzione viene riprovata per correggerli.
• Traduzione selettiva: L'IA comprende la differenza semantica tra identificatori tecnici e contenuti leggibili dall'uomo. Solo i campi leggibili dall'uomo vengono tradotti, mentre gli identificatori tecnici rimangono intatti.

Esempio: cosa viene tradotto

Prima della traduzione (inglese):

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

Dopo la traduzione in giapponese:

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

Preservazione dei tipi di dati

Un aspetto critico della localizzazione OpenAPI è il mantenimento dei tipi di dati JSON. Il servizio garantisce che:

• I numeri rimangano numeri (non convertiti in stringhe)
• I booleani rimangano true/false (non tradotti in parole)
• I valori null rimangano null (non convertiti in testo)

Ad esempio, questo schema con vari tipi di dati:

{
  "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 specifica tradotta preserverà esattamente tutti questi tipi, garantendo che la specifica rimanga valida e possa essere utilizzata in sicurezza in produzione senza rompere i client API o i generatori di documentazione.

Integrazione fluida con VS Code

La traduzione delle specifiche OpenAPI funziona perfettamente tramite l'estensione VS Code, consentendoti di localizzare la documentazione API direttamente nel tuo ambiente di sviluppo.

Come funziona in VS Code:

1. Apri il tuo file di specifica OpenAPI (openapi.json o openapi.yaml)
2. Fai clic con il tasto destro nell'editor e seleziona "Traduci JSON"
3. Scegli la tua lingua di destinazione (es. giapponese, tedesco, spagnolo)
4. L'estensione crea una versione localizzata con tutte le descrizioni tradotte preservando la struttura esatta

Vedi in azione

Ecco un esempio dal vivo della traduzione di una specifica OpenAPI dall'inglese al giapponese all'interno di VS Code:

Vantaggi per gli sviluppatori

• Nessuna specifica interrotta: Il file OpenAPI tradotto rimane valido al 100% e può essere utilizzato in Swagger UI, Redoc, Scalar o qualsiasi strumento OpenAPI senza modifiche.
• Nessuna correzione manuale: Nomi di campi, valori enum, percorsi $ref e tipi di schema non vengono mai alterati, eliminando la necessità di pulizia post-traduzione.
• Descrizioni consapevoli del contesto: L'IA comprende il contesto della tua API e traduce le descrizioni con terminologia tecnica e tono appropriati.

Casi d'uso per la localizzazione OpenAPI

Localizzare le tue specifiche OpenAPI è particolarmente utile per:

Documentazione API pubblica

Se stai creando un'API pubblica per sviluppatori globali, fornire documentazione in più lingue migliora drasticamente l'adozione. Gli sviluppatori sono più propensi a integrarsi con le API quando la documentazione è nella loro lingua madre.

Onboarding degli sviluppatori

Le specifiche API localizzate rendono l'onboarding più veloce per i team internazionali. I nuovi sviluppatori possono comprendere endpoint, parametri e schemi senza barriere linguistiche.

Team multilingue

Se il tuo team di sviluppo copre più paesi, avere la documentazione API nella lingua di ciascun membro del team migliora la collaborazione e riduce le incomprensioni.

Per iniziare

Pronto a localizzare le tue specifiche OpenAPI? Hai due opzioni: