HitKeep Dashboard Localization and Translation Guide

The HitKeep dashboard is fully translated into English, German, Spanish, French, Italian, Dutch, and Portuguese out of the box. No plugins are required. The selected language is stored in the database and follows the user across sessions and devices.

If you use an AI assistant for dashboard copy work, invoke the canonical contributor skill hitkeep-i18n from .agents/skills and follow the local development and contribution guide. It points the assistant at current locale files and patterns while delegating live validation to hk. The separate HitKeep Analytics Agent Skills are for end-user analytics and production MCP, not repository localization.

Related implementation details live in the main repository under frontend/dashboard/public/i18n/ and frontend/dashboard/src/app/core/i18n/. For product behavior, see Facts and Limits and Teams and Data Isolation.

Supported Languages

Language	Code	Translation file
English	`en`	`frontend/dashboard/public/i18n/en.json`
German	`de`	`frontend/dashboard/public/i18n/de.json`
Spanish	`es`	`frontend/dashboard/public/i18n/es.json`
French	`fr`	`frontend/dashboard/public/i18n/fr.json`
Italian	`it`	`frontend/dashboard/public/i18n/it.json`
Dutch	`nl`	`frontend/dashboard/public/i18n/nl.json`
Portuguese	`pt`	`frontend/dashboard/public/i18n/pt.json`

How Language Selection Works

Users change the interface language in Settings → Preferences. The selected locale is saved to user_preferences.default_locale in the database — it is not a browser-only cookie, so the choice persists when the user logs in from a different device.

Switching language is instant: the dashboard re-renders without a page reload, powered by Transloco.

Numbers and dates automatically reformat to match the locale (e.g. 1.234,56 in German, 1,234.56 in English) via @jsverse/transloco-locale.

Translation File Format

Each locale is a single JSON file with nested keys. en.json is the reference — all other files must contain the same key structure with translated values.

{
  "nav": {
    "dashboard": "Dashboard",
    "utm": "UTM",
    "utmBuilder": "UTM Builder"
  },
  "common": {
    "actions": {
      "save": "Save",
      "cancel": "Cancel",
      "clearAll": "Clear all"
    }
  },
  "dashboard": {
    "title": "Dashboard",
    "noData": "No data for this period."
  }
}

The top-level namespaces map to feature areas:

Namespace	Contents
`admin`	Admin panel: users, sites, IP exclusions
`common`	Shared buttons, column headers, empty states, filters
`dashboard`	Dashboard page and chart labels
`funnels`	Funnel analytics
`goals`	Goal tracking
`integration`	API clients and API reference pages
`login`	Login and setup screens
`nav`	Sidebar navigation labels and ARIA strings
`preferences`	Language and theme settings
`settings`	Profile, security (2FA, passkeys), email reports
`share`	Public shared dashboard
`sites`	Site management
`utm`	UTM analytics page
`utmBuilder`	UTM link builder tool

Interpolation

Some strings contain runtime variables wrapped in {{ }}. Leave the variable names exactly as-is — translate only the surrounding text.

// ✅ Correct
"filters": {
  "referrer": "Referred by {{ value }}"
}

// ❌ Wrong — variable name changed
"filters": {
  "referrer": "Verwiesen von {{ wert }}"
}

Pluralisation

Transloco uses ICU-style plural rules for strings that differ by count. When present, they look like:

"itemCount": "{ count, plural, =0 {No items} =1 {One item} other {# items} }"

Translate the label text inside each plural branch; keep the count, plural, branch keys, and # placeholder unchanged.

Contributing a Translation

Adding a New Language

1. Fork and clone the repository.

git clone https://github.com/pascalebeier/hitkeep.git
cd hitkeep
./hk setup

2. Copy the English reference file.

cp frontend/dashboard/public/i18n/en.json \
   frontend/dashboard/public/i18n/{lang}.json

Replace {lang} with a BCP 47 base tag, for example sv for Swedish or ja for Japanese.

3. Translate all values.

Open {lang}.json in your editor and translate every string value. Keep all keys unchanged.

"save": "Save"

// sv.json
"save": "Spara"

4. Register the language in the current runtime configuration.

Use the existing locale configuration and formatting mappings as the pattern. Register the translation ID and its standard IETF locale together so Transloco, PrimeNG, and browser Intl formatting agree. The repository can move these definitions over time, so follow the current implementation and $hitkeep-i18n instead of copying a file-specific snippet from this guide.

5. Test locally.

./hk dev

Open the dashboard URL returned by ./hk workspace status, navigate to Settings → Preferences, and switch to your new language. Verify labels, number formats, and date formats all look correct.

6. Submit a pull request.

Include both the new {lang}.json file and the app.config.ts change in your PR. The title should follow Conventional Commits:

feat(i18n): add Swedish (sv) translation

Fixing an Existing Translation

Found a mistranslation or an untranslated key?

Locate the key in en.json to confirm the English source.
Edit the same key in the target locale file.
Submit a PR with title fix(i18n): correct <lang> translation for <key>.

Translation files are loaded at runtime as static JSON, but the change still needs the current change-aware QA profile.

Keeping Translations in Sync

When a new HitKeep feature ships, new keys are added to en.json first. Existing locale files become incomplete until a contributor translates the additions. Plan and run the current change-aware gates through hk:

./hk qa plan changed
./hk qa

If locale shape drift is suspected, use the synchronization utility identified by the current implementation or $hitkeep-i18n, then review every resulting change before keeping it. Do not treat generated translations as reviewed copy.

Tech Stack

Layer	Library	Role
Translation strings	Transloco	Load JSON files, switch language at runtime
Number & date formatting	@jsverse/transloco-locale	Localises `Intl.NumberFormat` / `Intl.DateTimeFormat` to the active lang
Persistence	`user_preferences.default_locale` in DuckDB	Stores the user’s choice server-side across sessions