Skip to main content

​
File overview

i18n.jsonc controls locales, file mapping, model profiles, and rule selection.

​
Locales

  • locales.source: source locale.
  • locales.targets: list of target locales.
  • optional locales.fallbacks: fallback order per locale.

​
Buckets

buckets map source files to target output templates. Each file mapping uses:
  • from: source path template
  • to: target path template
Use {{source}}, {{target}}, and {{localeDir}} in templates. {{localeDir}} resolves to an empty segment when target equals source, and to the target locale otherwise.

​
CSV file mapping patterns

Use bucket file mappings to model CSV workflows. Per-locale files: 
{
  "from": "translations/en.csv",
  "to": "translations/[locale].csv"
}
Shared multi-locale file: 
{
  "from": "translations/catalog.csv",
  "to": "translations/catalog.csv"
}
For shared multi-locale CSV files, keep one key column and one target locale column that run can update consistently.

​
Groups

groups.<name> defines what to process together.
  • targets: subset of locales.targets
  • buckets: list of bucket names

​
LLM profiles

llm.profiles.<name> fields:
  • provider: openai, azure_openai, anthropic, gemini, bedrock, lmstudio, groq, or ollama
  • model: provider model id
  • prompt: translation prompt template
Prompt variables:
  • {{source}}
  • {{target}}
  • {{input}}

​
Rules

llm.rules choose profile per group.
  • priority: higher wins
  • group: group name
  • profile: profile name

​
Starter config

hyperlocalise init
Then edit the generated i18n.jsonc for your project.

​
Validation tips

  • Keep group targets inside locales.targets.
  • Keep group buckets aligned with buckets keys.
  • Keep profile names consistent between profiles and rules.