Saltar al contenido principal
La internacionalización (i18n) es el proceso de diseñar software o contenido para que funcione en distintos idiomas y configuraciones regionales. Esta guía explica cómo estructurar archivos, configurar la navegación y mantener las traducciones de forma eficiente, para que puedas ayudar a los usuarios a acceder a tu documentación en su idioma preferido y mejorar tu alcance global.

​
Estructura de archivos

Organiza el contenido traducido en directorios específicos por idioma para mantener tu documentación organizada y estructurar la navigation por idioma. Crea un directorio separado para cada idioma usando los códigos de idioma ISO 639-1. Coloca los archivos traducidos en estos directorios con la misma estructura que tu idioma predeterminado.
Example file structure
docs/
├── index.mdx                    # Inglés (predeterminado)
├── quickstart.mdx
├── fr/
│   ├── index.mdx               # Francés
│   ├── quickstart.mdx
├── es/
│   ├── index.mdx               # Español
│   ├── quickstart.mdx
└── zh/
    ├── index.mdx               # Chino
    └── quickstart.mdx
Mantén los mismos nombres de archivo y la misma estructura de directorios en todos los idiomas. Esto facilita el mantenimiento de las traducciones y la identificación del contenido faltante.

​
Configurar el selector de idioma

Para añadir un selector de idioma a tu documentación, configura el array languages en la propiedad navigation de tu docs.json.
docs.json
{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [
          {
            "group": "Primeros pasos",
            "pages": ["index", "quickstart"]
          }
        ]
      },
      {
        "language": "es",
        "groups": [
          {
            "group": "Comenzando",
            "pages": ["es/index", "es/quickstart"]
          }
        ]
      }
    ]
  }
}
Cada entrada de idioma en el array languages requiere:
  • language: código de idioma ISO 639-1
  • Estructura completa de navigation
  • Rutas de los archivos traducidos
La estructura de navigation puede diferir entre idiomas para adaptarse a las necesidades de contenido específicas de cada idioma.

​
Establecer el idioma predeterminado

El primer idioma del arreglo languages se usa automáticamente como idioma predeterminado. Para establecer otro idioma como predeterminado, reordena el arreglo o agrega la propiedad default:
docs.json
{
  "navigation": {
    "languages": [
      {
        "language": "es",
        "groups": [...]
      },
      {
        "language": "en",
        "groups": [...]
      }
    ]
  }
}
Alternativamente, usa la propiedad default para modificar el orden:
docs.json
{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [...]
      },
      {
        "language": "es",
        "default": true,
        "groups": [...]
      }
    ]
  }
}

​
Documentación en un solo idioma

Si solo quieres tener un único idioma disponible sin un selector de idioma, elimina el campo languages de tu configuración de navigation. En su lugar, define directamente tu estructura de navigation:
docs.json
{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentación",
        "groups": [
          {
            "group": "Primeros pasos",
            "pages": ["index", "quickstart"]
          }
        ]
      }
    ]
  }
}
Esto muestra la documentación en un solo idioma sin la interfaz de usuario del selector de idioma.
Traduce las etiquetas de navegación, como los nombres de grupos o Tabs, para que coincidan con el idioma del contenido. Esto crea una experiencia completamente localizada para tus usuarios.
Para añadir elementos de navegación global que aparezcan en todos los idiomas, configura el objeto global dentro de la navigation de tu docs.json.
docs.json
{
  "navigation": {
    "global": {
      "anchors": [
        {
          "anchor": "Documentación",
          "href": "https://example.com/docs"
        },
        {
          "anchor": "Blog",
          "href": "https://example.com/blog"
        }
      ]
    },
    "languages": [
      // Language-specific navigation
    ]
  }
}

​
Mantén las traducciones

Mantén las traducciones precisas y sincronizadas con tu contenido original.

​
Flujo de trabajo de traducción

  1. Actualiza el contenido original en tu idioma principal.
  2. Identifica el contenido modificado.
  3. Traduce el contenido modificado.
  4. Revisa las traducciones para comprobar su precisión.
  5. Actualiza los archivos traducidos.
  6. Verifica que la navegación y los enlaces funcionen.

​
Traducciones automatizadas

Para soluciones de traducción automática, ponte en contacto con el equipo de ventas de Mintlify.

​
Imágenes y recursos multimedia

Guarda las imágenes traducidas en directorios específicos para cada idioma. 
images/
├── dashboard.png          # Versión en inglés
├── fr/
│   └── dashboard.png     # Versión en francés
└── es/
    └── dashboard.png     # Versión en español
Referencia las imágenes usando rutas relativas en tu contenido traducido.
es/index.mdx
![Captura de pantalla del dashboard](/images/es/dashboard.png)

​
SEO para sitios multilingües

Optimiza cada versión en cada idioma para los motores de búsqueda.

​
Metadata de la página

Incluye la metadata traducida en el frontmatter de cada archivo:
fr/index.mdx
---
title: "Comenzar"
description: "Aprenda a comenzar con nuestro producto."
keywords: ["inicio", "tutorial", "guía"]
---

​
Mejores prácticas

​
Formatos de fecha y número

Ten en cuenta los formatos específicos de cada región para fechas y números.
  • Formatos de fecha: MM/DD/YYYY vs DD/MM/YYYY
  • Formatos numéricos: 1,000.00 vs 1.000,00
  • Símbolos de moneda: $100.00 vs 100,00€
Incluye ejemplos en el formato apropiado para cada idioma o utiliza formatos universalmente comprensibles.

​
Mantén la consistencia

  • Mantén el mismo contenido en todos los idiomas para garantizar que cada usuario reciba la misma calidad de información.
  • Crea un glosario de traducción para los términos técnicos.
  • Conserva la misma estructura de contenido en todos los idiomas.
  • Haz que el tono y el estilo coincidan con los de tu contenido original.
  • Usa branches de Git para gestionar el trabajo de traducción por separado de las actualizaciones del contenido principal.

​
Diferencias de diseño

Algunos idiomas requieren más o menos espacio que el inglés. Prueba tu contenido traducido en diferentes tamaños de pantalla para asegurarte de que:
  • La navegación quepa correctamente.
  • Los bloques de código no se desborden.
  • Las tablas y otros textos con formato sigan siendo legibles.
  • Las imágenes se escalen adecuadamente.

​
Codificación de caracteres

Asegúrate de que tanto tu entorno de desarrollo como tu pipeline de implementación sean compatibles con la codificación UTF-8 para mostrar correctamente todos los caracteres de idiomas con alfabetos distintos y caracteres especiales.