Carpeta por configuración regional (reescritura de URL)

Úselo para README/USER-GUIDE con docsOutput.style = "flat", y para sitios de sistemas de documentación (docsOutput.style = "doc-system" o alias "docusaurus" / "astro-starlight") y para "vitepress" / otros ajustes preestablecidos de sistemas de documentación que sirven capturas de pantalla desde un árbol de URL estático compartido. Detalles de reescritura de enlaces para VitePress: Reescritura de enlaces — VitePress.

Estructura de directorios

Árbol de directorios de capturas de pantalla por configuración regional de ejemplo

images/screenshots/
├── en-GB/
│   ├── translate.png
│   └── settings.png
├── de/
│   ├── translate.png
│   └── settings.png
└── fr/
    ├── translate.png
    └── settings.png

El markdown fuente hace referencia al directorio del idioma fuente:

![Translate tab](images/screenshots/en-GB/translate.png)

Contrato del script de captura de pantalla

El script take-screenshots debe escribir archivos para cada configuración regional, no solo para la configuración regional de origen. El comando translate-docs reescribe las rutas, pero no crea archivos. Un asistente típico:

function getScreenshotDir(locale) {
  return `images/screenshots/${locale}`;
}

Vea un ejemplo simple de bash en el script de captura de pantalla en examples/nextjs-app, o un ejemplo más complejo en take-screenshots.ts del proyecto duplistatus (también utilizado en producción por Transrewrt).

Nota: Las cuatro subsecciones siguientes comparten el mismo intercambio de segmento de configuración regional regexAdjustments (screenshots/[^/]+/ → screenshots/${translatedLocale}/). Solo difieren el diseño de salida y si el reescritor de enlaces planos se ejecuta primero; salte a la subsección que coincida con su docsOutput.style.

Nota: regexAdjustments se ejecuta en el cuerpo completo de markdown traducido, incluidos los bloques de código cercados. Si una página de documentación incrusta un ejemplo de configuración que contiene una ruta coincidente (por ejemplo, screenshots/en-GB/), ese fragmento también se reescribirá en la salida traducida. Prefiera la forma genérica screenshots/[^/]+/ en ejemplos reutilizables.

Configuración - docsOutput.style = "flat"

El reescritor de enlaces planos se ejecuta primero cuando docsOutput.style = "flat" y antepone un prefijo de profundidad a las URL que no son de markdown. Para un README.md en la raíz del repositorio con outputDir: "translated-docs/", añade ../:

images/screenshots/en-GB/translate.png  →  ../images/screenshots/en-GB/translate.png

Luego, la regla regexAdjustments reemplaza el segmento de idioma dentro de esa URL ya con prefijo:

Ejemplo de ajustes de expresiones regulares para diseño plano

"docsOutput": {
  "style": "flat",
  "postProcessing": {
    "regexAdjustments": [
      {
        "description": "Per-locale screenshot folders",
        "search": "images/screenshots/[^/]+/",
        "replace": "images/screenshots/${translatedLocale}/"
      }
    ]
  }
}

Resultado: ../images/screenshots/de/translate.png — ruta relativa correcta desde translated-docs/README.de.md de vuelta a la raíz del repositorio.

El paso postProcessing se ejecuta después del reescritor de enlaces planos. Escriba expresiones regulares search que coincidan con el segmento de configuración regional en cualquier parte de la URL ya prefijada; no es necesario incluir el prefijo ../ en la expresión regular.

Ejemplo de implementación (producción): Transrewrt — URL de captura de pantalla en README.md (images/screenshots/en-GB/…), reescritura de configuración regional en ai-i18n-tools.config.json, script de captura basado en take-screenshots.ts de duplistatus (consulte el contrato del script de captura de pantalla anterior).

Ejemplo de implementación (configuración de demostración): examples/nextjs-app — segundo bloque docs[] en ai-i18n-tools.config.json (images/screenshots/[^/]+/ → ${translatedLocale}); script auxiliar screenshot-locales.sh.

Configuración - docsOutput.style = "doc-system"

El mismo enfoque de carpeta por configuración regional para cualquier sitio de sistema de documentos que haga referencia a capturas de pantalla a través de un prefijo de URL estático compartido. El reescritor de enlaces planos no se ejecuta; postProcessing reescribe el segmento de configuración regional en la URL original de markdown.

Ejemplo de ajustes de expresiones regulares para diseño de sistema de documentación

"docsOutput": {
  "style": "doc-system",
  "docsRoot": "docs",
  "localeSubpath": "your-generator/locale/content/path",
  "postProcessing": {
    "regexAdjustments": [
      {
        "description": "Per-locale screenshot folders in static assets",
        "search": "screenshots/[^/]+/",
        "replace": "screenshots/${translatedLocale}/"
      }
    ]
  }
}

Establezca localeSubpath para que coincida con el diseño de su generador entre {locale}/ y el archivo traducido, o use un alias preestablecido ("docusaurus", "astro-starlight") en lugar de "doc-system" cuando los valores predeterminados sean adecuados. El markdown fuente normalmente incluye la configuración regional fuente en la URL:

![Screenshot](/img/screenshots/en-GB/screenshot.png)

Incluya archivos PNG coincidentes en la misma ruta para cada configuración regional de destino (por ejemplo, static/img/screenshots/de/screenshot.png). Prefiera screenshots/[^/]+/ frente a codificar screenshots/en-GB/ para que la regla siga siendo válida tras un cambio en sourceLocale.

Preajuste - docsOutput.style = "docusaurus"

Igual que "doc-system" con localeSubpath = "docusaurus-plugin-content-docs/current" predeterminado. El reescritor de enlaces plano no se ejecuta. postProcessing ve la URL original del markdown. Las páginas en inglés normalmente usan una ruta absoluta con la configuración regional fuente:

![Screenshot](/img/screenshots/en-GB/screenshot.png)

Ejemplo de ajustes de expresiones regulares para el preajuste de Docusaurus

"docsOutput": {
  "style": "docusaurus",
  "postProcessing": {
    "regexAdjustments": [
      {
        "description": "Per-locale screenshot folders in docs-site static assets",
        "search": "screenshots/[^/]+/",
        "replace": "screenshots/${translatedLocale}/"
      }
    ]
  }
}

Incluya archivos PNG coincidentes en docs-site/static/img/screenshots/<locale>/screenshot.png. Para configuraciones independientes de la configuración regional fuente, prefiera screenshots/[^/]+/ frente a screenshots/en-GB/.

Ejemplo de implementación: examples/docusaurus-docs/docs/feature-showcase.md (/img/screenshots/en-GB/screenshot.png) con ai-i18n-tools.config.json.

Preajuste - docsOutput.style = "astro-starlight"

Igual que "doc-system" con localeSubpath: "" — las páginas traducidas se encuentran directamente debajo de {outputDir}/{locale}/. El mismo enfoque de carpeta por configuración regional que la configuración genérica del sistema de documentos anterior. El markdown de origen utiliza /img/screenshots/en-GB/screenshot.png:

Ejemplo de ajustes de expresiones regulares para el preajuste de Astro Starlight

"docsOutput": {
  "style": "astro-starlight",
  "postProcessing": {
    "regexAdjustments": [
      {
        "description": "Per-locale screenshot folders in public assets",
        "search": "screenshots/[^/]+/",
        "replace": "screenshots/${translatedLocale}/"
      }
    ]
  }
}

Envíe PNG en public/img/screenshots/<locale>/screenshot.png. El marcador de posición ${translatedLocale} utiliza su cadena de configuración regional (por ejemplo, pt-BR). El preajuste astro-starlight convierte a minúsculas las rutas de salida de la configuración regional de forma predeterminada (pt-br/), pero las carpetas de activos estáticos bajo public/img/screenshots/ deben coincidir con el segmento de configuración regional escrito en las URL de markdown; mantenga los directorios de capturas de pantalla alineados con ${translatedLocale}, no necesariamente con el uso de mayúsculas y minúsculas de la ruta de Astro.

Ejemplo de implementación: examples/astro-docs — feature-showcase.mdx y ai-i18n-tools.config.json (screenshots/[^/]+/).