Comment localiser les spécifications OpenAPI

Les spécifications OpenAPI sont la colonne vertébrale de la documentation moderne des API. Les localiser en plusieurs langues aide les développeurs du monde entier à comprendre et à s'intégrer à votre API. Mais traduire les spécifications OpenAPI n'est pas simple — vous devez préserver la structure tout en localisant le contenu lisible par l'homme.

Qu'est-ce qu'OpenAPI ?

OpenAPI (anciennement Swagger) est un format standard pour décrire les API REST. Il comprend des points de terminaison, des schémas de requête/réponse, des paramètres, des méthodes d'authentification et des descriptions détaillées. Ces spécifications alimentent des outils comme Swagger UI, Redoc, Scalar et des générateurs de code — les rendant critiques pour l'expérience développeur.

Le défi de la traduction

Les spécifications OpenAPI sont des fichiers JSON ou YAML complexes avec une structure précise. Les outils de traduction automatique simples les casseront car ils ne comprennent pas ce qui doit et ne doit pas être traduit.

Détection et validation intelligentes

l10n.dev détecte automatiquement les spécifications OpenAPI et les traite avec une attention particulière :

• Détection automatique : Le service reconnaît les fichiers OpenAPI par la propriété openapi et active un traitement spécialisé.
• Validation de la structure : Lors de la traduction, le schéma est validé pour s'assurer qu'il s'agit d'une spécification OpenAPI valide. Si des problèmes structurels surviennent, la traduction est réessayée pour les corriger.
• Traduction sélective : L'IA comprend la différence sémantique entre les identifiants techniques et le contenu lisible par l'homme. Seuls les champs lisibles par l'homme sont traduits tandis que les identifiants techniques restent intacts.

Exemple : Ce qui est traduit

Avant la traduction (anglais) :

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

Après la traduction en japonais :

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

Préservation des types de données

Un aspect critique de la localisation OpenAPI est le maintien des types de données JSON. Le service s'assure que :

• Les nombres restent des nombres (non convertis en chaînes)
• Les booléens restent vrai/faux (non traduits en mots)
• Les valeurs nulles restent nulles (non converties en texte)

Par exemple, ce schéma avec divers types de données :

{
  "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 spécification traduite préservera tous ces types exactement — garantissant que la spécification reste valide et peut être utilisée en toute sécurité en production sans casser les clients API ou les générateurs de documentation.

Intégration transparente avec VS Code

La traduction des spécifications OpenAPI fonctionne parfaitement via l'extension VS Code, vous permettant de localiser votre documentation API directement dans votre environnement de développement.

Comment ça fonctionne dans VS Code :

1. Ouvrez votre fichier de spécification OpenAPI (openapi.json ou openapi.yaml)
2. Cliquez avec le bouton droit dans l'éditeur et sélectionnez "Traduire JSON"
3. Choisissez votre langue cible (par exemple, japonais, allemand, espagnol)
4. L'extension crée une version localisée avec toutes les descriptions traduites tout en préservant la structure exacte

Voyez-le en action

Voici un exemple en direct de la traduction d'une spécification OpenAPI anglaise en japonais dans VS Code :

Avantages pour les développeurs

• Pas de spécifications cassées : Le fichier OpenAPI traduit reste 100 % valide et peut être utilisé dans Swagger UI, Redoc, Scalar ou tout outil OpenAPI sans modifications.
• Pas de corrections manuelles : Les noms de champs, les valeurs d'énumération, les chemins $ref et les types de schéma ne sont jamais altérés — éliminant le besoin de nettoyage après traduction.
• Descriptions conscientes du contexte : L'IA comprend le contexte de votre API et traduit les descriptions avec la terminologie technique appropriée et le ton.

Cas d'utilisation pour la localisation OpenAPI

Localiser vos spécifications OpenAPI est particulièrement précieux pour :

Documentation API publique

Si vous construisez une API publique pour des développeurs du monde entier, fournir une documentation en plusieurs langues améliore considérablement l'adoption. Les développeurs sont plus susceptibles de s'intégrer aux API lorsque la documentation est dans leur langue maternelle.

Intégration des développeurs

Les spécifications API localisées rendent l'intégration plus rapide pour les équipes internationales. Les nouveaux développeurs peuvent comprendre les points de terminaison, les paramètres et les schémas sans barrières linguistiques.

Équipes multilingues

Si votre équipe de développement s'étend sur plusieurs pays, avoir la documentation API dans la langue de chaque membre de l'équipe améliore la collaboration et réduit les malentendus.

Commencer

Prêt à localiser vos spécifications OpenAPI ? Vous avez deux options :