Solución de problemas

Los enlaces de anclaje de sección no funcionan en los documentos traducidos

Un enlace como [label](other.md#section-id) puede abrir el archivo traducido correcto, pero no desplazarse hasta el encabezado deseado, o bien puede saltar a una sección incorrecta. El fragmento #… ya no coincide con ningún encabezado id en esa configuración regional.

Causas comunes:

• Los encabezados de origen nunca tuvieron identificadores de anclaje explícitos; el sitio genera los slugs a partir del texto visible del encabezado, que cambia tras la traducción.
• Ha cambiado el nombre de un encabezado en el origen, pero la línea <a id="…"></a> anterior falta o aún contiene el ID antiguo.
• Los enlaces de anclaje usan un fragmento #… adivinado a partir de palabras en inglés en lugar del ID que generaría write-heading-ids.

Solución

1. Ejecute ai-i18n-tools write-heading-ids en su .md / .mdx de origen (el mismo docs[] / contentPaths que translate-docs). Por defecto, inserta <a id="slug"></a> antes de cada encabezado ATX, o actualiza un ancla existente cuando el texto del encabezado ya no coincide con el slug actual. Para los ID de comentarios MDX de Docusaurus, use --slug-style mdx-comment.
2. Apunte los enlaces de anclaje a esos ID, por ejemplo, [setup](guide.md#first-run), donde #first-run coincide con la línea de anclaje encima del encabezado de destino, no con un slug inferido solo del título en inglés.
3. Vuelva a ejecutar translate-docs (o sync --force-update) para que cada copia local incluya las líneas de anclaje actualizadas.

Utilice --dry-run en write-heading-ids primero para previsualizar los cambios. Consulte Enlaces de anclaje para ver el patrón completo.

Enlaces de imagen o recursos con error 404 en documentos traducidos

Un enlace de Markdown o ![alt](url) funciona en inglés, pero devuelve un error 404 en las copias traducidas, a menudo porque la URL sigue apuntando a la carpeta de la configuración regional de origen o a una ruta estática solo en inglés.

Solución

1. Confirma que el diseño de tus recursos coincide con tu docsOutput.style (plano frente a sistema de documentos). Consulta Reescritura de enlaces e Imágenes y capturas de pantalla.
2. Agrega o ajusta docsOutput.postProcessing.regexAdjustments para intercambiar segmentos de configuración regional o unir rutas absolutas de /img/…. Para un diseño plano, recuerda que el reescritor de enlaces planos se ejecuta antes de regexAdjustments; haz coincidir los patrones con la URL ya prefijada.
3. Asegúrate de que los archivos de recursos específicos de la configuración regional existan en las rutas a las que hace referencia el Markdown reescrito (translate-docs reescribe las URL, pero no copia los archivos ráster).

La salida en hindi, árabe, CJK o cirílico está romanizada (letras latinas)

Algunos modelos traducen el significado, pero escriben el resultado en letras latinas/romanas (por ejemplo, hindi como Namaste en lugar de नमस्ते). hi a secas significa devanagari; usa hi-Latn solo cuando quieras hindi romanizado.

Solución

1. Confirme que el código de configuración regional coincide con el script que desea (hi frente a hi-Latn, zh-Hans frente a zh-Hant, sr frente a sr-Latn).
2. Vuelva a ejecutar la traducción para que se rechacen las filas de caché de script incorrectas: translate-ui --force para cadenas de interfaz de usuario, o translate-docs --check-cache / sync --check-cache (la omisión a nivel de archivo se omite solo para configuraciones regionales con un script esperado; la caché de segmento válida aún se reutiliza). --force-update reprocesa cada configuración regional.
3. Si un modelo sigue fallando la verificación de script, agregue una entrada localeModels para esa configuración regional para que se intente primero un modelo más fuerte; consulte Proveedores y modelos.