Raster Colocado (doc-system)

Use quando um site doc-system colocaliza ativos específicos do idioma ao lado do markdown traduzido — nenhuma reescrita de URL é necessária. A predefinição do Docusaurus (docsOutput.style = "docusaurus") é a implementação de referência; outros geradores que usam "doc-system" com um localeSubpath personalizado seguem a mesma ideia: ativos em inglês ficam em um caminho de idioma de origem, ativos traduzidos ficam em {outputDir}/{locale}/[localeSubpath/]assets/.

Por que não há exemplo no repositório: As demonstrações do Docusaurus deste repositório (examples/docusaurus-docs, examples/nextjs-app) usam o layout pasta por localidade — consulte o guia de decisão. O ../assets/ colocalizado é o padrão recomendado para novos projetos; duplistatus é a referência de produção completa.

Estrutura de diretórios

Exemplo de árvore de diretórios de ativos colocados juntos (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

Todos os documentos em todas as localidades usam o mesmo caminho relativo:

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

Para a localidade em inglês (en-GB), ../assets/ é resolvido através do link simbólico para static/assets/. Para localidades traduzidas, é resolvido diretamente para o próprio diretório current/assets/ da localidade.

Contrato do script de captura de tela

O script deve gravar os arquivos PNG no diretório correto para cada localidade. A função getScreenshotDir codifica a divisão:

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

Veja uma implementação real em take-screenshots.ts do repositório duplistatus.

Configuração

Nenhuma regra regexAdjustments necessária para arquivos raster. translate-docs traduz o texto alternativo no markdown, mas a URL permanece inalterada:

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

Se o projeto também usa SVGs traduzidos, a tradução de SVG colocalizada os trata e eles são colocados junto com os PNGs em current/assets/ sem regex adicional.

Pré-requisitos

• O link simbólico docs/assets deve existir: ln -s ../static/assets documentation/docs/assets
• O webpack do Docusaurus segue links simbólicos por padrão (resolve.symlinks tem como padrão true nas compilações do Docusaurus)
• O link simbólico precisa existir apenas para o idioma de origem — compilações traduzidas não o utilizam

Exemplo de implementação

duplistatus — getScreenshotDir(locale) em take-screenshots.ts; a documentação em inglês faz referência a PNGs colocalizados (por exemplo, dashboard.md com ../assets/screen-dashboard-summary.png). SVGs colocalizados do mesmo projeto são colocados nos mesmos diretórios current/assets/ — veja SVG Colocalizado.