Feature Request: CLI-powered TypeScript type generation from Tolgee platform keys

[daunJung-dev]

Feature Request: CLI-powered TypeScript type generation from Tolgee platform keys

Problem

When multiple developers work on a project, translation keys inevitably get duplicated with slightly different names because keyName is a plain string with no discoverability at authoring time.

Real examples from our project (~800+ keys):

• common.confirm vs dialog.confirmButton vs button.confirm
• error.networkError vs common.networkFailed vs toast.connectionError

The existing tolgee.d.ts approach (importing a local JSON and using DotNotationEntries) helps with autocomplete for existing keys, but it has limitations:

1. It depends on a manually maintained local JSON file — the source of truth is the Tolgee platform, not a local file.
2. The types are only as fresh as the last tolgee pull. If another developer just created keys on the platform, you won't see them.
3. There's no enforcement — LiteralUnion intentionally allows arbitrary strings, so typos and duplicates still slip through.

Proposed Solution

Add a tolgee typegen (or integrate into tolgee pull) CLI command that:

1. Fetches the full key tree from the Tolgee platform (respecting namespaces and the nested key structure).
2. Generates a .d.ts file with a strict PathValues type representing all valid dot-notation key paths.
3. Optionally runs in strict mode — where using an unregistered key is a TypeScript error (no LiteralUnion fallback), forcing developers to register keys on the platform first.

// Auto-generated by `tolgee typegen`
// Do not edit manually.

export type TolgeeKeys =
  | 'common.confirm'
  | 'common.cancel'
  | 'common.save'
  | 'error.networkError'
  | 'dialog.title'
  | 'dialog.description'
  // ... all keys from platform
;

declare module '@tolgee/core/lib/types' {
  export type TranslationKey = TolgeeKeys; // strict mode
  // or: LiteralUnion<TolgeeKeys, string>  // relaxed mode
}

Benefits

• Duplicate prevention: Autocomplete shows all existing keys at the moment of authoring → developers discover existing keys before creating new ones.
• Single source of truth: Types are generated from the platform, not a local JSON snapshot.
• CI integration: tolgee typegen --check can fail CI if types are stale, ensuring the codebase stays in sync.
• Namespace-aware: The generated type tree can respect Tolgee namespaces, producing per-namespace types.

Prior Art

• next-intl generates TypeScript types from message files with full path autocomplete.
• typesafe-i18n generates types from a master locale file.
• Tolgee's own docs mention considering typesafe-i18n-like support (ref: Tolgee blog, 2022).

Suggested Implementation Path

1. New CLI command tolgee typegen (or --typegen flag on tolgee pull)
2. Reads .tolgeerc for project config (API key, namespaces)
3. Fetches key list via REST API (/v2/projects/{id}/translations/select-all)
4. Outputs a generated .d.ts to a configurable path
5. Optional --strict flag to omit LiteralUnion wrapper
6. Optional --check flag for CI (exit 1 if generated file differs from committed file)

Environment

• Tolgee self-hosted / cloud
• @tolgee/react + TypeScript
• Monorepo with multiple apps sharing the same Tolgee project

[JanCizmar]

Thanks for this feature request, this is an amazing idea! 🙏 We appreciate you taking the time to describe it so thoroughly.

One thing I wanted to mention though. In general, we don't recommend reusing the same translation keys across different contexts. Even if two buttons say "Confirm" today, they might need different translations in other languages or evolve differently over time.

Keeping keys tied to their specific context (like dialog.confirmButton vs common.confirm) gives translators more flexibility and avoids situations where changing one translation accidentally breaks another place in the UI.

That said, the TypeScript type generation itself is still a great idea for catching typos and improving discoverability.

Would you be up for submitting a PR for this? 🙏 The CLI lives in the tolgee-cli repo. We'd be happy to help guide you through the codebase if needed.