Colocated raster (doc-system)

Use when a doc-system site colocates locale-specific assets beside translated markdown — no URL rewriting is needed. The Docusaurus preset (docsOutput.style = "docusaurus") is the reference implementation; other generators using "doc-system" with a custom localeSubpath follow the same idea: English assets live at a source-locale path, translated assets live under {outputDir}/{locale}/[localeSubpath/]assets/.

Why no in-repo example: This repository's Docusaurus demos (examples/docusaurus-docs, examples/nextjs-app) use per-locale folder layout instead — see the decision guide. Colocated ../assets/ is the recommended greenfield pattern; duplistatus is the full production reference.

Directory layout

Example colocated asset directory tree (Docusaurus)

documentation/
├── static/
│   └── assets/
│       ├── screen-dashboard.png   ← en-GB screenshots (source locale)
│       └── screen-toolbar.png
├── docs/
│   └── assets → ../static/assets  ← symlink; webpack follows it
└── i18n/
    ├── de/
    │   └── docusaurus-plugin-content-docs/current/assets/
    │       ├── screen-dashboard.png   ← de screenshots
    │       └── screen-toolbar.png
    └── fr/
        └── docusaurus-plugin-content-docs/current/assets/
            ├── screen-dashboard.png
            └── screen-toolbar.png

All docs in every locale use the same relative path:

![Dashboard](../assets/screen-dashboard.png)

For the English (en-GB) locale, ../assets/ resolves via the symlink to static/assets/. For translated locales it resolves directly to the locale's own current/assets/ directory.

Screenshot script contract

The script must write PNGs to the correct directory for each locale. The getScreenshotDir function encodes the split:

function getScreenshotDir(locale) {
  if (locale === 'en-GB') return 'documentation/static/assets';
  return `documentation/i18n/${locale}/docusaurus-plugin-content-docs/current/assets`;
}

See a real-world implementation in take-screenshots.ts from the duplistatus repository.

Config

No regexAdjustments rule needed for raster files. translate-docs translates alt text in the markdown but the URL stays unchanged:

{
  "docsOutput": {
    "style": "docusaurus",
    "docsRoot": "documentation/docs"
  }
}

If the project also uses translated SVGs, colocated SVG translation handles them and they land alongside the PNGs in current/assets/ with no extra regex.

Prerequisites

• The docs/assets symlink must exist: ln -s ../static/assets documentation/docs/assets
• Docusaurus webpack follows symlinks by default (resolve.symlinks defaults to true in Docusaurus builds)
• The symlink only needs to exist for the source locale — translated builds do not use it

Implementation example

duplistatus — getScreenshotDir(locale) in take-screenshots.ts; English docs reference colocated PNGs (e.g. dashboard.md with ../assets/screen-dashboard-summary.png). Colocated SVGs from the same project land in the same current/assets/ directories — see Colocated SVG.