Skip to main content

​
File overview

i18n.yml controls locales, file mapping, model profiles, and optional advanced routing. i18n.jsonc is still supported for compatibility.

​
Starter config

locales:
  source: en-US
  targets:
    - es-ES

buckets:
  ui:
    files:
      - from: packages/ui/lang/{{source}}.json
        to: apps/web/lang/{{target}}.json

llm:
  profiles:
    default:
      provider: openai
      model: gpt-5.2
This is the shape written by hyperlocalise init. When groups is omitted, Hyperlocalise automatically uses one implicit default group with:
  • all locales from locales.targets
  • all bucket names from buckets

​
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
groups is optional for beginner configs. Add it when you want to split execution by locale or file set.

​
LLM profiles

llm.profiles.<name> fields:
  • provider: openai, azure_openai, anthropic, gemini, bedrock, lmstudio, groq, mistral, or ollama
  • model: provider model id
  • system_prompt (optional): explicit system-message template
  • user_prompt (optional): explicit user-message template
  • prompt (deprecated, optional): legacy prompt template used as system fallback
Prompt variables:
  • {{source}}
  • {{target}}
  • {{input}}

​
Rules

llm.rules choose profile per group.
  • priority: higher wins
  • group: group name
  • profile: profile name
llm.rules is optional. When no rule matches a group, Hyperlocalise falls back to llm.profiles.default.

​
Cache

cache configures the remote caching client.
  • enabled (optional): enable remote caching for run.
  • endpoint (optional unless enabled=true): remote cache service endpoint.
  • project_key_env (optional unless enabled=true): environment variable that contains the project cache key.
  • timeout_seconds (optional): remote cache request timeout in seconds.

​
Advanced example

locales:
  source: en-US
  targets:
    - fr-FR
    - es-ES
  fallbacks:
    fr-FR:
      - es-ES
      - en-US

buckets:
  ui:
    files:
      - from: packages/ui/lang/{{source}}.json
        to: apps/web/lang/{{target}}.json
  docs:
    files:
      - from: docs/{{source}}/**/*.mdx
        to: docs/{{target}}/**/*.mdx

groups:
  app:
    targets:
      - fr-FR
      - es-ES
    buckets:
      - ui
  docs:
    targets:
      - fr-FR
    buckets:
      - docs

llm:
  profiles:
    default:
      provider: openai
      model: gpt-5.2
    docs_review:
      provider: openai
      model: gpt-5.2
      system_prompt: You are a senior technical translator.
      user_prompt: |-
        Translate from {{source}} to {{target}}.

        Keep Markdown and MDX syntax intact.

        {{input}}
  context_memory:
    provider: openai
    model: gpt-5.2
  rules:
    - priority: 100
      group: docs
      profile: docs_review

cache:
  enabled: true
  endpoint: dns:///cache.internal:443
  project_key_env: HYPERLOCALISE_CACHE_PROJECT_KEY
  timeout_seconds: 5

​
Generate a starter

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

​
Validation tips

  • If you omit groups, every bucket runs for every target locale.
  • Keep group targets inside locales.targets.
  • Keep group buckets aligned with buckets keys.
  • Keep profile names consistent between profiles and rules.