Comment localiser les spécifications OpenAPI

Les spécifications OpenAPI sont l'épine dorsale de la documentation API moderne. Les localiser dans plusieurs langues aide les développeurs du monde entier à comprendre et à s'intégrer à votre API. Mais traduire des 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 inclut 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 des développeurs.

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 briseront car ils ne comprennent pas ce qui doit et ne doit pas être traduit.

Détection intelligente et validation

l10n.dev détecte automatiquement les spécifications OpenAPI et les traite avec un soin particulier :

• Détection automatique : Le service reconnaît les fichiers OpenAPI par la propriété openapi et active une gestion spécialisée.
• Validation de la structure : Pendant 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 relancé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 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 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 garantit que :

• Les nombres restent des nombres (non convertis en chaînes)
• Les booléens restent true/false (non traduits en mots)
• Les valeurs null restent null (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 exactement tous ces types — garantissant que la spécification reste valide et puisse être utilisée en toute sécurité en production sans briser les clients API ou les générateurs de documentation.

Intégration transparente avec VS Code

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

Comment cela fonctionne dans VS Code :

1. Ouvrez votre fichier de spécification OpenAPI (openapi.json ou openapi.yaml)
2. Faites un clic droit dans l'éditeur et sélectionnez "Translate JSON"
3. Choisissez votre langue cible (par ex., 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

• Aucune spécification brisée : Le fichier OpenAPI traduit reste valide à 100 % et peut être utilisé dans Swagger UI, Redoc, Scalar ou tout outil OpenAPI sans modifications.
• Aucune correction manuelle : Les noms de champs, les valeurs d'énumération, les chemins $ref et les types de schéma ne sont jamais modifié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 une terminologie technique et un ton appropriés.

Cas d'utilisation pour la localisation OpenAPI

La localisation de vos spécifications OpenAPI est particulièrement précieuse pour :

Documentation API publique

Si vous construisez une API publique pour des développeurs mondiaux, fournir une documentation dans 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.

Onboarding des développeurs

Les spécifications API localisées rendent l'onboarding 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 une documentation API dans la langue de chaque membre de l'équipe améliore la collaboration et réduit les erreurs de communication.

Démarrage

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