Typemark Documentation

Idiomas

Publica tu documentación en varios idiomas, cada uno en su propia dirección, con un selector de idioma para los lectores. En todos los planes.

Actualizado el 19 nov 20267 min de lectura

Publica tu sitio en más de un idioma. Cada traducción es un archivo MDX junto a la página que traduce, los lectores cambian de idioma desde el encabezado del sitio y los motores de búsqueda encuentran cada versión. Los idiomas están disponibles en todos los planes. En Pro y Enterprise, la IA puede escribir las traducciones y mantenerlas actualizadas.

Añade tus idiomas

En Settings > Languages, el propietario del proyecto establece el idioma en el que están escritas tus páginas y luego añade los demás:

  1. En Default language, marca el código y el nombre del idioma en el que están tus páginas. Un sitio sin idiomas está en inglés.
  2. Haz clic en Add a language y escribe su código, por ejemplo fr. Typemark rellena su nombre en ese mismo idioma, que puedes cambiar.
  3. En Translated by, elige AI para que la IA traduzca cada página (Pro y Enterprise), o Your team para escribir las traducciones tú mismo.
  4. Haz clic en Save languages. Typemark guarda la lista en typemark.json y vuelve a generar tu sitio.

El código de un idioma guardado no se puede cambiar: elimina el idioma y vuelve a añadirlo. Eliminar un idioma despublica sus traducciones, y sus archivos permanecen en tu repositorio.

Settings escribe la lista languages en typemark.json, y también puedes editarla allí, con primero el idioma en el que están escritas tus páginas:

"languages": [
  { "code": "en", "name": "English" },
  { "code": "fr", "name": "Français" },
  { "code": "pt-BR", "name": "Português (Brasil)" }
]
ClaveQué hace
codeEl código de idioma, como fr, pt-BR o zh-Hans. Forma parte de la dirección: /fr/quickstart.
nameLo que ven los lectores en el selector de idioma, hasta 50 caracteres. Escríbelo en el propio idioma, como Français.
defaulttrue en el idioma en el que están escritas tus páginas. Si no se indica, el primer idioma es el predeterminado.
translate"ai" para que la IA traduzca cada página a este idioma (Pro y Enterprise). "manual", el valor predeterminado, deja las traducciones en tus manos. Consulta Traducciones con IA.

Puedes listar hasta 30 idiomas. Los códigos se comparan exactamente como están escritos, así que usa el mismo código en typemark.json y en los nombres de tus carpetas. mcp y ai-search no pueden ser códigos, porque todos los sitios ya usan esas direcciones. Una entrada que Typemark no puede usar, como un código repetido o un idioma sin nombre, se omite, y la publicación la indica como advertencia en la vista general de tu proyecto.

Edita typemark.json en tu repositorio conectado, o con la CLI en un proyecto alojado por Typemark. Settings > Languages muestra como advertencias las entradas que no puede usar, y al guardar las elimina.

El idioma predeterminado

Tus páginas existentes están en el idioma predeterminado. Conservan sus direcciones, como /quickstart, y nada cambia en ellas.

Un sitio sin languages está en inglés. Un sitio que lista un solo idioma está íntegramente en ese idioma: el atributo lang de la página y la búsqueda lo usan, y no hay selector de idioma.

Dónde van las traducciones

Una traducción tiene la misma ruta que la página que traduce, dentro de una carpeta con el nombre del código de idioma:

PáginaTraducción al francésDirección
quickstart.mdxfr/quickstart.mdx/fr/quickstart
guides/authentication.mdxfr/guides/authentication.mdx/fr/guides/authentication

Con un docs_root, las carpetas de idioma van dentro de él: docs/fr/quickstart.mdx. La página de inicio del idioma es /fr.

Una traducción es una página completa, con su propio frontmatter (un title y una description traducidos) y su cuerpo en ese idioma. Para empezar una a mano, copia el archivo de la página a la carpeta del idioma y tradúcelo, en tu repositorio o con la CLI. En el editor, el selector de idioma abre las traducciones que ya tiene una página.

Lo que ven los lectores

  • Un selector de idioma en el encabezado del sitio muestra tus idiomas y abre la página en la que están en el idioma elegido. Typemark nunca elige un idioma según la configuración del navegador.
  • La misma navegación en todos los idiomas. Las pestañas, los grupos y su orden vienen de tu navigation, con el título de cada página en el idioma del lector cuando tiene traducción, y con los nombres de pestañas y grupos traducidos cuando les das una traducción.
  • El propio sitio en su idioma. "On this page", la búsqueda, el menú de acciones de la página, Ask AI, "Was this page helpful?", anterior y siguiente, las fechas y la página 404 aparecen en el idioma del lector. Consulta Las palabras del propio sitio.
  • Todas las páginas en todos los idiomas. Una página sin traducción muestra la página del idioma predeterminado en la dirección del idioma, así que /fr/billing funciona antes de traducirla, y la navegación nunca tiene huecos.
  • Enlaces en el idioma del lector. En una página en francés, un enlace a /quickstart lleva a /fr/quickstart una vez que esa página tiene una traducción al francés publicada, y a /quickstart hasta entonces. Escribe los enlaces a las direcciones predeterminadas como siempre: Typemark los ajusta al servir la página, y tus archivos no cambian. Las anclas, los enlaces a otros sitios, archivos como /llms.txt y los enlaces que ya indican un idioma (/de/setup) se mantienen tal como están escritos.
  • Búsqueda en el idioma del lector. Buscar en una página en francés encuentra las traducciones al francés y las páginas del idioma predeterminado que aún no tienen traducción. La búsqueda usa las reglas de palabras de cada idioma cuando Typemark las tiene, de modo que coinciden distintas formas de una palabra, y para los demás busca las palabras tal como están escritas, como en japonés, chino y coreano.
  • Redirecciones en todos los idiomas. Una redirección de /old a /new también envía /fr/old a /fr/new.

Las palabras del propio sitio

Todo lo que el sitio dice de sí mismo aparece en el idioma del lector en una página traducida: la tabla de contenidos, la búsqueda, el menú de acciones de la página, la tarjeta "Use these docs with AI", el panel de Ask AI, el widget de opinión, anterior y siguiente, las fechas "Updated" y el tiempo de lectura, el menú móvil, "Powered by Typemark", la página 404 y el formulario de inicio de sesión de un sitio privado.

Typemark tiene estas palabras en inglés, alemán, francés, español, portugués y japonés. Un código regional usa las palabras de su idioma, así que pt-BR usa portugués y es-419 español. Los demás idiomas las muestran en inglés. Los nombres de productos, MCP, llms.txt y Markdown se mantienen tal cual.

Traduce los nombres de pestañas, grupos y enlaces

Los nombres de pestañas y grupos, los enlaces de la navegación superior y los enlaces del pie vienen de tu typemark.json. Dales una traducción por idioma en translations.labels, con la clave en el nombre tal como lo escribiste:

"translations": {
  "labels": {
    "fr": { "Get started": "Premiers pas", "Guides": "Guides", "Status": "État du service" },
    "de": { "Get started": "Erste Schritte" }
  }
}

Un nombre sin traducción se muestra tal como está escrito, y las páginas del idioma predeterminado siempre muestran los nombres como están escritos. Como las traducciones se indexan por nombre, mover un grupo conserva su traducción; cambiarle el nombre requiere una nueva. Para un idioma que traduce la IA, la IA completa los nombres que no hayas traducido y nunca cambia los que tú escribiste.

Motores de búsqueda

  • Cada página establece su idioma en <html lang>.
  • Cada página enumera sus versiones en otros idiomas con enlaces hreflang, más x-default para el idioma predeterminado. Solo se listan los idiomas en los que la página tiene traducción propia, y las páginas ocultas no listan ninguna.
  • El sitemap incluye cada traducción, con las mismas alternativas.
  • Una página mostrada en el idioma predeterminado en la dirección de una traducción indica a los motores de búsqueda que la página predeterminada es su URL canónica, para que el mismo texto no se indexe dos veces.

Lo que se mantiene en el idioma predeterminado

En el editor

En un sitio con más de un idioma, la barra superior del editor tiene un selector de idioma junto a Visual y Source. Abre la página en la que estás en otro idioma. Los idiomas en los que la página aún no tiene traducción aparecen en gris. Una traducción se guarda como cualquier otra página.

Cambia el nombre, mueve y elimina las páginas en el idioma predeterminado. Para renombrar o eliminar una traducción, cambia su archivo en tu repositorio o con la CLI.

El editor muestra los enlaces tal como los escribiste. Preview abre la página en tu sitio, con los enlaces en el idioma de la página.

Comprueba antes de publicar

typemark check lee languages del mismo modo que una publicación, y trata un enlace a /fr/<page> como un enlace a esa página:

ReglaGravedadQué significa
config-languagesErrorUna entrada de idioma que Typemark omite, como un código que no es un código de idioma o que aparece dos veces
config-translationsWarningUn translate distinto de "ai" o "manual", un translations.do_not_translate que no es una lista, o translations.labels que no es un objeto con nombres por idioma
languages-singleWarninglanguages lista un solo idioma, así que todo el sitio está en él y no hay selector. Lista primero el idioma predeterminado y luego los demás.
language-folderWarningUna página de navigation está en la carpeta de un idioma, como fr/intro. Los lectores no pueden llegar a ella, ya que /fr/intro es la versión francesa de intro. Sácala de la carpeta.
translation-unlistedWarningUna traducción de una página que no está en navigation, así que no se publica