Soporte multilingüe

Si su documentación necesita llegar a usuarios en más de un idioma, puede definir árboles de navegación independientes por configuración regional y permitir que los lectores cambien de idioma mediante un menú desplegable en la barra superior.

Configuración

Envuelva su navegación en un array languages, donde cada idioma contiene su propia estructura de navegación:

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

Idiomas admitidos

Estructura de directorios

Organice el contenido traducido en directorios con prefijo de idioma:

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

Haga referencia a las páginas en la navegación usando su ruta completa (con el prefijo de idioma):

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

Configuración específica por idioma

Cada idioma puede tener su propia configuración:

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

Traducir las etiquetas de la barra de navegación

Los enlaces de la barra de navegación superior y el CTA principal aceptan un objeto labels opcional con anulaciones por idioma. Cuando el lector está en una URL con prefijo de idioma (por ejemplo, /fr/...), se usa la anulación correspondiente; en caso contrario, se muestra el label predeterminado.

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

Las cadenas de interfaz integradas (el botón Search, el botón Ask AI y el menú desplegable More de las pestañas) se traducen automáticamente para cada idioma admitido. No necesita configurarlas.

Idioma predeterminado

El primer idioma del array es el predeterminado. Los usuarios que llegan a su documentación ven primero este idioma. El selector de idioma les permite cambiarlo.

Estructura de URL

Los prefijos de idioma aparecen en las URL:

Enrutamiento automático de idioma

De forma predeterminada, todos llegan a su idioma predeterminado y cambian manualmente. Active localization.autoRedirect para enviar a los visitantes que llegan por primera vez directamente a su propio idioma:

{
  "localization": {
    "autoRedirect": true
  }
}

Un visitante cuyo navegador solicita francés obtiene /fr en lugar de /. Su idioma se recuerda durante un año, por lo que solo se detecta una vez, y si elige un idioma en el selector, esa elección prevalece a partir de entonces.

Solo la raíz de su sitio se redirige alguna vez. Todo lo demás se deja exactamente como lo pidió el visitante:

• Una URL de idioma siempre se abre en ese idioma. /fr/guides/authentication — o simplemente /fr — sirve francés a todos, sea lo que sea que pida su navegador. Alguien eligió esa URL, así que un enlace que pegue en un ticket o en un resultado de búsqueda abre la misma página para quien haga clic en él.
• Los enlaces profundos nunca se redirigen. /guides/authentication sirve esa página a todos.
• Los rastreadores nunca se redirigen. Google y otros bots siguen viendo su idioma predeterminado en la raíz, y sus etiquetas hreflang siguen decidiendo qué se indexa.
• Nunca inventa un idioma. Si el navegador del visitante solicita un idioma que usted no publica, no sucede nada: permanece en su raíz predeterminada.

llms.txt para cada idioma

Cada idioma que publique obtiene su propio índice llms.txt y su propio archivo de contenido completo, para que una herramienta de IA pueda leer su documentación en un idioma sin cargar los demás:

La raíz docs.example.com/llms.txt sirve el mismo archivo que /en/llms.txt. La raíz docs.example.com/llms-full.txt sigue conteniendo todos los idiomas. Un idioma obtiene sus propios archivos en cuanto tiene al menos una página. Sitios multilingües →

Traducciones parciales

No es necesario traducir todas las páginas. Si una página no existe en un idioma, los usuarios ven un mensaje alternativo con un enlace a la versión en inglés.

Para las páginas que no deben traducirse (como la referencia de la API), puede hacer referencia a la misma página en todos los idiomas:

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

Traducir especificaciones de OpenAPI

Las páginas de endpoint controladas por OpenAPI (las que tienen una directiva de frontmatter openapi:) renderizan el contenido a partir de un archivo de especificación YAML o JSON. Para traducir el resumen del endpoint, las descripciones, las indicaciones de los parámetros y las descripciones de los campos del esquema, proporcione un archivo de especificación específico para el idioma junto al archivo en inglés.

Nomenclatura de archivos

Coloque la especificación traducida junto a la fuente, insertando el código de idioma antes de la extensión:

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

No se requiere ninguna configuración ni cambio en docs.json. Jamdesk resuelve la especificación correspondiente en el momento del renderizado, según el prefijo de idioma de la URL. Una página en /fr/api-reference/create-ticket busca primero api.fr.yaml, y recurre a api.yaml si no existe traducción.

Qué traducir en la especificación

Traduzca el texto legible por humanos. Mantenga cada valor estructural idéntico en todos los idiomas.

Comportamiento de reserva

Si se solicita una página bajo una URL localizada pero no existe una especificación traducida, Jamdesk renderiza la especificación en inglés dentro de la estructura de la página traducida. Los usuarios ven un bloque de endpoint en idioma mixto en lugar de un error 404. Esto coincide con el comportamiento más general de las traducciones parciales para páginas MDX.

Eliminar una especificación específica de un idioma

Eliminar api.<lang>.yaml hace que la página recurra a la especificación en inglés en el siguiente renderizado (no se requiere una nueva compilación). Para retraducir desde cero, elimine el archivo y vuelva a generarlo. No se necesita ningún cambio en docs.json: la resolución de la especificación se basa únicamente en el nombre del archivo.

Ejemplo

Fuente 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

Traducción al francés 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

Observe que /tickets, post y createTicket permanecen idénticos. Solo cambia el texto.

Flujo de traducción

Idiomas RTL

Los idiomas de derecha a izquierda, como el árabe y el hebreo, son compatibles. Jamdesk aplica automáticamente el estilo RTL cuando estos idiomas están activos.

¿Qué sigue?