Type Extractor

The type extractor scans your locale JSON files and generates a TypeScript interface plus a LocaleCodes union type, so your LocaleManager generics stay in sync with your translation files automatically.

• CLI Usage
• Directory Structures
• Generated Output
• Wiring Into LocaleManager
• Watch Mode
• Programmatic API

CLI Usage

npx logosdx-locale extract --dir ./i18n --out ./src/locale-keys.ts

Flag	Default	Description
--dir	--	Directory containing locale JSON files
--out	--	Output path for the generated .ts file
--locale	First found	Which locale to use as the type source
--name	AppLocale	Name of the generated interface
--watch	false	Re-generate on file changes

Directory Structures

The extractor supports flat files, namespaced subdirectories, and mixed layouts.

# Flat — one JSON file per locale
i18n/
├── en.json
├── es.json
└── fr.json

# Namespaced — subdirectories per locale
i18n/
├── en/
│   ├── common.json
│   ├── auth.json
│   └── dashboard.json
├── es/
│   ├── common.json
│   └── auth.json
└── fr/
    └── common.json

# Mixed — top-level keys alongside namespace files
i18n/
├── en.json
├── en/
│   ├── auth.json
│   └── dashboard.json

Generated Output

Given en/common.json and en/auth.json, the extractor produces a file like this:

// Auto-generated by @logosdx/localize — do not edit manually

export interface AppLocale {
    common: {
        buttons: {
            save: string;
            cancel: string;
        };
        messages: {
            welcome: string;
            error: string;
        };
    };
    auth: {
        login: {
            title: string;
            username: string;
            password: string;
        };
        errors: {
            invalid: string;
            expired: string;
        };
    };
}

export type LocaleCodes = 'en' | 'es' | 'fr';

Wiring Into LocaleManager

Import the generated types and pass them as generics to LocaleManager:

import { LocaleManager } from '@logosdx/localize';
import type { AppLocale, LocaleCodes } from './locale-keys';

const i18n = new LocaleManager<AppLocale, LocaleCodes>({
    current: 'en',
    fallback: 'en',
    locales: {
        en: { code: 'en', text: 'English', labels: enLabels }
    }
});

// All t() calls are now type-checked against your JSON structure
i18n.t('common.buttons.save');
i18n.t('auth.login.title');

Watch Mode

During development, use --watch to regenerate the output file whenever a locale JSON file is added, removed, or modified:

npx logosdx-locale extract --dir ./i18n --out ./src/locale-keys.ts --watch

This pairs well with your dev server so type errors surface immediately when translations change.

Programmatic API

If you need to integrate extraction into a build script or custom tooling, import from @logosdx/localize/extractor:

import { scanDirectory, generateOutput } from '@logosdx/localize/extractor';
import { writeFile } from 'node:fs/promises';

// Scan locale files and build a structure descriptor
const scan = await scanDirectory('./i18n', { locale: 'en' });

// Generate the TypeScript source string
const source = generateOutput(scan, { name: 'AppLocale' });

// Write to disk
await writeFile('./src/locale-keys.ts', source);