Path templates - Hyperlocalise

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/cli/**/*.mdx",
  "to": "docs/{{localeDir}}/cli/**/*.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}}/cli/index.mdx to docs/cli/index.mdx
target=fr resolves docs/{{localeDir}}/cli/index.mdx to docs/fr/cli/index.mdx
target=es resolves docs/{{localeDir}}/cli/index.mdx to docs/es/cli/index.mdx
target=zh resolves docs/{{localeDir}}/cli/index.mdx to docs/zh/cli/index.mdx

Use this pattern when English source pages live under a product folder such as docs/cli/ and translated pages should be written into the same relative paths under each locale folder.

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:

confirm from resolves for source locale,
confirm to can be created for each target locale,
run hyperlocalise run --dry-run to inspect planned tasks.

Cloud path aliases

Use cloud_path when a file’s path in Hyperlocalise Cloud differs from its local path. For example, you can move files within your repository or share a config across several apps while keeping existing Cloud paths and translations.

buckets:
    web:
        files:
            - from: apps/web/locales/en.json
              to: apps/web/locales/{{target}}.json
              cloud_path: locales/en.json
    guides:
        files:
            - from: content/guides/en/**/*.md
              to: content/guides/{{target}}/**/*.md
              cloud_path: guides/en/**/*.md

In the web mapping, sync push reads apps/web/locales/en.json and uploads it as locales/en.json. For a French target, sync pull retrieves the translation for that Cloud path and writes it to apps/web/locales/fr.json. Recursive aliases preserve nested folders. The guides mapping uploads content/guides/en/setup/install.md as guides/en/setup/install.md. To reuse existing translations, keep the same Cloud project and set cloud_path to the file’s exact existing source path. Changed source content still follows your project’s normal translation workflow. If you omit cloud_path, sync uses the local source path relative to the config directory. Cloud path aliases follow these rules:

Use a relative path with forward slashes and no empty, . or .. segments.
Use {{source}} for the source locale; target locale placeholders are not supported.
Keep the source file extension and the same glob suffix as from.
Give distinct local files distinct Cloud paths. Sync rejects collisions before sending requests.

The from and to paths remain relative to your config directory. cloud_path only affects Cloud sync; local run, check, status, and pack commands keep using the local paths.

​Supported placeholders

​Examples

​JSON locale files

​Locale template with [locale] token

​Mintlify recursive mapping with globs

​Good patterns

​Anti-patterns

​Quick checks

​Cloud path aliases