comvi typegen

The typegen command generates a TypeScript declaration file from the translation key schema in Comvi. The generated file augments @comvi/core, so every framework binding gets autocomplete for translation keys and compile-time validation of interpolation parameters.

Usage

comvi typegen

This reads .comvirc.json, fetches the project schema from Comvi, and writes a .d.ts file to the configured output path.

Generated Output

Given a project schema with these keys:

default:hello
default:greeting       params: name
default:cart.items     params: count
admin:dashboard.title

The CLI generates:

src/types/i18n.d.ts

/**
 * Auto-generated translation keys
 * DO NOT EDIT MANUALLY - This file is generated by @comvi/cli
 */

import '@comvi/core';

declare module '@comvi/core' {
  interface TranslationKeys {
    'hello': never;
    'greeting': { name: string };
    'cart.items': { count: number };
    'admin:dashboard.title': never;
  }
}

export {};

Using Generated Types

Import the generated declaration once anywhere that is included by TypeScript, usually next to your i18n setup:

src/i18n.ts

import { createI18n } from '@comvi/react';
import './types/i18n';

export const i18n = createI18n({
  locale: 'en',
});

Now t() is fully typed:

const { t } = useI18n();

t('hello');                    // OK
t('greeting', { name: 'Al' }); // OK
t('greeting');                 // Error: missing required param 'name'
t('nonexistent');              // Error: key doesn't exist
t('cart.items', { count: 5 }); // OK — count is number
t('dashboard.title', { ns: 'admin' }); // OK — namespaced key

Tip

Run comvi typegen as part of your build step or in a pre-commit hook to keep types in sync with your translations.

Options

comvi typegen [options]

Option	Default	Description
--config, -c	.comvirc.json	Path to the Comvi config file
--watch, -w	false	Subscribe to schema updates and regenerate types
--check	false	CI mode: exit with an error if generated types are outdated

How It Works

1. Loads .comvirc.json
2. Fetches the project translation schema from Comvi
3. Converts schema keys to TypeScript declarations
4. Strips the default namespace prefix from default namespace keys
5. Emits declare module '@comvi/core' { interface TranslationKeys { ... } }
6. Uses never for keys with no parameters

Multiple Namespaces

When using namespaces, keys from the configured default namespace are emitted without a namespace prefix. Other namespaces use the namespace:key format:

src/types/i18n.d.ts

declare module '@comvi/core' {
  interface TranslationKeys {
    'hello': never;                 // default:hello
    'greeting': { name: string };   // default:greeting
    'admin:page.title': never;
    'admin:stats.users': { count: number };
  }
}

Use namespace-scoped helpers such as useI18n('admin') or pass { ns: 'admin' } to translate namespaced keys without writing the prefix in call sites.

Watch Mode

Re-generate types automatically when translations change:

comvi typegen --watch

Check Mode

Fail CI if generated types are not current:

comvi typegen --check

Next Steps

• Type-Safe Translations — full guide to type-safe i18n
• CLI Overview — all CLI commands
• comvi pull — download translations before generating types
• CI/CD Integration — automate type generation in your pipeline