Supporto multilingue

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

Configurazione

Racchiudi la navigazione in un array languages, con ogni lingua contenente la 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 (con 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 la propria configurazione:

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

Traduzione delle etichette della barra di navigazione

I link della barra di navigazione superiore e la CTA principale accettano un oggetto labels facoltativo 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; altrimenti 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 devi configurarle.

Lingua predefinita

La prima lingua nell'array è quella predefinita. Gli utenti che accedono alla documentazione vedono prima questa lingua. Il selettore della 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 visualizzano un messaggio di fallback con un link alla versione inglese.

Per le pagine che non devono essere tradotte (come i riferimenti API), puoi fare riferimento alla stessa pagina in tutte le 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 (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.

Denominazione dei file

Inserisci la specifica tradotta accanto a quella di origine, aggiungendo 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 risolve 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, quindi usa api.yaml se non trova alcuna 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 alcuna specifica tradotta, Jamdesk esegue il rendering della specifica inglese all'interno dell'interfaccia della pagina tradotta. Gli utenti visualizzano un blocco dell'endpoint in più lingue anziché un errore 404. Questo comportamento è coerente con quello 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 utilizzi la specifica inglese al rendering successivo (non è necessaria alcuna nuova build). Per ritradurre da zero, elimina il file e rigeneralo. Non è necessaria alcuna modifica a docs.json: la risoluzione della specifica si basa esclusivamente sul nome del file.

Esempio

File di origine 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 lavoro per la traduzione

Lingue RTL

Le lingue con scrittura 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?