Supporto multilingue

Se la documentazione deve raggiungere utenti che parlano più lingue, puoi definire alberi di navigazione separati per ogni lingua e consentire ai lettori di cambiare lingua con un menu a discesa nella barra superiore.

Configurazione

Racchiudi la navigazione in un array languages, dove ogni lingua contiene una propria struttura di navigazione:

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "tabs": [
          {
            "tab": "Documentation",
            "groups": [
              {
                "group": "Getting Started",
                "pages": ["introduction", "quickstart"]
              }
            ]
          }
        ]
      },
      {
        "language": "es",
        "tabs": [
          {
            "tab": "Documentación",
            "groups": [
              {
                "group": "Comenzar",
                "pages": ["es/introduction", "es/quickstart"]
              }
            ]
          }
        ]
      }
    ]
  }
}

Lingue supportate

Struttura delle directory

Organizza i contenuti tradotti in directory con prefisso della lingua:

my-docs/
├── docs.json
├── introduction.mdx          # English (default)
├── quickstart.mdx
├── es/
│   ├── introduction.mdx      # Spanish
│   └── quickstart.mdx
├── fr/
│   ├── introduction.mdx      # French
│   └── quickstart.mdx
└── de/
    ├── introduction.mdx      # German
    └── quickstart.mdx

Fai riferimento alle pagine nella navigazione usando il percorso completo, incluso il prefisso della lingua:

{
  "language": "es",
  "tabs": [
    {
      "tab": "Documentación",
      "groups": [
        {
          "group": "Comenzar",
          "pages": ["es/introduction", "es/quickstart"]
        }
      ]
    }
  ]
}

Impostazioni specifiche per lingua

Ogni lingua può avere una propria configurazione:

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "tabs": [...]
      },
      {
        "language": "es",
        "tabs": [...]
      }
    ]
  }
}

Traduzione delle etichette della barra di navigazione

I link della navigazione superiore e la CTA principale accettano un oggetto labels opzionale con override per ogni lingua. Quando il lettore si trova su un URL con prefisso della lingua (ad esempio /fr/...), viene usato l'override corrispondente; in caso contrario, viene mostrata l'etichetta predefinita label.

{
  "navbar": {
    "links": [
      {
        "label": "Blog",
        "labels": { "fr": "Blog", "es": "Blog" },
        "href": "/blog"
      },
      {
        "label": "Pricing",
        "labels": { "fr": "Tarifs", "es": "Precios" },
        "href": "/pricing"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "labels": { "fr": "Tableau de bord", "es": "Panel" },
      "href": "https://app.example.com"
    }
  }
}

Le stringhe dell'interfaccia integrate (il pulsante Search, il pulsante Ask AI e il menu a discesa delle schede More) vengono tradotte automaticamente per ogni lingua supportata. Non è necessario configurarle.

Lingua predefinita

La prima lingua nell'array è quella predefinita. Gli utenti che accedono alla documentazione vedono prima questa lingua. Il selettore di lingua consente loro di cambiarla.

Struttura degli URL

I prefissi della lingua compaiono negli URL:

Traduzioni parziali

Non è necessario tradurre ogni pagina. Se una pagina non esiste in una lingua, gli utenti vedono un messaggio di fallback con un link alla versione inglese.

Per le pagine che non devono essere tradotte, come il riferimento API, puoi usare la stessa pagina per più lingue:

{
  "language": "es",
  "tabs": [
    {
      "tab": "API",
      "groups": [
        {
          "group": "Endpoints",
          "pages": ["api/users", "api/posts"]  // Same as English
        }
      ]
    }
  ]
}

Traduzione delle specifiche OpenAPI

Le pagine degli endpoint basate su OpenAPI, ovvero quelle con una direttiva openapi: nel frontmatter, mostrano contenuti provenienti da un file di specifica YAML o JSON. Per tradurre il riepilogo dell'endpoint, le descrizioni, i suggerimenti sui parametri e le descrizioni dei campi dello schema, fornisci un file di specifica specifico per la lingua accanto a quello inglese.

Nomi dei file

Posiziona la specifica tradotta accanto all'originale, inserendo il codice della lingua prima dell'estensione:

openapi/
├── api.yaml           # English (default)
├── api.fr.yaml        # French
├── api.es.yaml        # Spanish
└── api.zh.yaml        # Simplified Chinese

Non è necessaria alcuna modifica alla configurazione o a docs.json. Jamdesk individua la specifica corrispondente al momento del rendering in base al prefisso della lingua nell'URL. Una pagina all'indirizzo /fr/api-reference/create-ticket cerca prima api.fr.yaml, usando api.yaml come fallback se non esiste una traduzione.

Cosa tradurre nella specifica

Traduci la prosa leggibile dagli utenti. Mantieni identici tutti i valori strutturali nelle diverse lingue.

Comportamento di fallback

Se una pagina viene richiesta tramite un URL localizzato ma non esiste una specifica tradotta, Jamdesk mostra la specifica inglese all'interno dell'involucro della pagina tradotta. Gli utenti vedono un blocco dell'endpoint in più lingue anziché un errore 404. Questo comportamento è coerente con il funzionamento generale delle traduzioni parziali per le pagine MDX.

Rimozione di una specifica specifica per lingua

L'eliminazione di api.<lang>.yaml fa sì che la pagina usi la specifica inglese come fallback al rendering successivo, senza richiedere una nuova build. Per ritradurre da zero, elimina il file e rigeneralo. Non è necessaria alcuna modifica a docs.json: la risoluzione delle specifiche si basa esclusivamente sul nome del file.

Esempio

Sorgente openapi/tickets.yaml:

info:
  title: Tickets API
  description: Manage support tickets.
paths:
  /tickets:
    post:
      summary: Create a ticket
      description: Create a new support ticket.
      operationId: createTicket

Traduzione francese openapi/tickets.fr.yaml:

info:
  title: API Tickets
  description: Gérez les tickets de support.
paths:
  /tickets:
    post:
      summary: Créer un ticket
      description: Créer un nouveau ticket de support.
      operationId: createTicket

Nota che /tickets, post e createTicket rimangono identici. Cambia solo la prosa.

Flusso di traduzione

Lingue RTL

Le lingue da destra a sinistra, come l'arabo e l'ebraico, sono supportate. Jamdesk applica automaticamente lo stile RTL quando queste lingue sono attive.

Qual è il prossimo passo?