Soporte Multilingüe

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

Configuración

Envuelve tu navegación en un array languages, con cada idioma conteniendo 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

Organiza 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

Referencia 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",
        "banner": {
          "content": "Version 2.0 is now live! See our [changelog](/changelog).",
          "dismissible": true
        },
        "tabs": [...]
      },
      {
        "language": "es",
        "banner": {
          "content": "¡La versión 2.0 está disponible! Ver [registro de cambios](/es/changelog).",
          "dismissible": true
        },
        "tabs": [...]
      }
    ]
  }
}

Traducir las etiquetas de la barra de navegación

Los enlaces de la barra superior y el botón CTA principal aceptan un objeto labels opcional con traducciones por idioma. Cuando el lector está en una URL con prefijo (p. ej. /fr/...), se utiliza la traducció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 etiquetas integradas — el botón Search, el botón Ask AI y el menú desplegable More — se traducen automáticamente para cada idioma admitido. No se requiere configuración.

Idioma Predeterminado

El primer idioma en el array es el predeterminado. Los usuarios que llegan a tu documentación ven este idioma primero. El selector de idioma les permite cambiar.

Estructura de URL

Los prefijos de idioma aparecen en las URLs:

Traducciones Parciales

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

Para páginas que no deberían traducirse (como la referencia de API), puedes referenciar la misma página en varios idiomas:

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

Traducción de Especificaciones OpenAPI

Las páginas de endpoint basadas en OpenAPI (aquellas con una directiva de frontmatter openapi:) renderizan contenido desde un archivo de especificación YAML o JSON. Para traducir el resumen del endpoint, las descripciones, las sugerencias de parámetros y las descripciones de campos de esquema, proporciona un archivo de especificación específico por idioma junto al inglés.

Nomenclatura de archivos

Coloca 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 ningún cambio de configuración ni en docs.json. Jamdesk resuelve la especificación correspondiente en el momento de la renderización según el prefijo de idioma de la URL. Una página en /fr/api-reference/create-ticket busca primero api.fr.yaml, recurriendo a api.yaml si no existe ninguna traducción.

Qué traducir en la especificación

Traduce la prosa legible por humanos. Mantén todos los valores estructurales idénticos entre idiomas.

Comportamiento de respaldo

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

Eliminar una especificación específica por idioma

Eliminar api.<lang>.yaml hace que la página recurra a la especificación en inglés en la próxima renderización (no se requiere reconstrucción). Para volver a traducir desde cero, elimina el archivo y vuelve a generarlo. No se necesita ningún cambio en docs.json — la resolución de especificaciones se basa puramente 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

Observa que /tickets, post y createTicket permanecen idénticos. Solo cambia la prosa.

Flujo de Trabajo 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?