Come localizzare le specifiche OpenAPI

Le specifiche OpenAPI sono la spina dorsale della documentazione API moderna. 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: è necessario preservare la struttura mentre si localizza il contenuto leggibile dall'uomo.

Che cos'è OpenAPI?

OpenAPI (precedentemente Swagger) è un formato standard per descrivere le API REST. Include endpoint, schemi di richiesta/riposta, 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 degli sviluppatori.

La sfida della traduzione

Le specifiche OpenAPI sono file JSON o YAML complessi con una struttura precisa. I semplici strumenti di traduzione automatica li rompono perché non comprendono cosa debba e cosa non debba essere tradotto.

Rilevamento e validazione intelligenti

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

• Rilevamento automatico: Il servizio riconosce i file OpenAPI tramite la proprietà openapi e attiva una gestione specializzata.
• Validazione della struttura: Durante la traduzione, lo schema viene convalidato per garantire che sia una specifica OpenAPI valida. Se sorgono problemi strutturali, la traduzione viene ripetuta 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 è mantenere i tipi di dati JSON. Il servizio garantisce che:

• I numeri rimangono numeri (non convertiti in stringhe)
• I booleani rimangono true/false (non tradotti in parole)
• I valori null rimangono 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 preserva esattamente tutti questi tipi, garantendo che la specifica rimanga valida e possa essere utilizzata in sicurezza in produzione senza interrompere i client API o i generatori di documentazione.

Integrazione senza soluzione di continuità con VS Code

La traduzione delle specifiche OpenAPI funziona senza problemi tramite l'estensione di VS Code, consentendoti di localizzare la documentazione della tua 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 (ad es., giapponese, tedesco, spagnolo)
4. L'estensione crea una versione localizzata con tutte le descrizioni tradotte mantenendo esattamente la struttura

Guarda in azione

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

Vantaggi per gli sviluppatori

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

Casi d'uso per la localizzazione OpenAPI

Localizzare le tue specifiche OpenAPI è particolarmente prezioso per:

Documentazione API pubblica

Se stai costruendo 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 si estende su più paesi, avere la documentazione API nella lingua di ciascun membro del team migliora la collaborazione e riduce i malintesi.

Iniziare

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