Skip to main content

​
Supported placeholders

  • {{source}}: source locale
  • {{target}}: target locale
  • {{localeDir}}: empty for source locale output, otherwise target locale

​
Examples

​
JSON locale files

{
  "from": "packages/ui/lang/{{source}}.json",
  "to": "apps/web/lang/{{target}}.json"
}

​
Locale template with [locale] token

{
  "from": "lang/en.json",
  "to": "lang/[locale].json"
}

​
Mintlify recursive mapping with globs

{
  "from": "docs/**/*.mdx",
  "to": "docs/{{localeDir}}/**/*.mdx"
}
This keeps the source file structure and writes translated files into the same relative paths under each locale folder. With source=en and targets fr, es, and zh:
  • target=en resolves docs/{{localeDir}}/index.mdx to docs/index.mdx
  • target=fr resolves docs/{{localeDir}}/index.mdx to docs/fr/index.mdx
  • target=es resolves docs/{{localeDir}}/index.mdx to docs/es/index.mdx
  • target=zh resolves docs/{{localeDir}}/index.mdx to docs/zh/index.mdx
Use this pattern when your English source pages live directly under docs/ and translated pages should be written into locale folders.

​
Good patterns

  • Keep source and target trees separate.
  • Use stable bucket names by domain (ui, marketing, emails).
  • Keep one responsibility per file mapping.

​
Anti-patterns

  • Writing to paths back into source directories.
  • Reusing the same output path for multiple buckets.
  • Mixing locale tokens with ad-hoc string replacement outside templates.

​
Quick checks

Before running:
  1. confirm from resolves for source locale,
  2. confirm to can be created for each target locale,
  3. run hyperlocalise run --dry-run to inspect planned tasks.