@flightdev/i18n 0.1.5

package/dist/typegen.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Type Generation for Type-Safe Translation Keys
+ *
+ * Generates TypeScript declaration files from JSON translation files,
+ * enabling full autocompletion and compile-time validation of translation keys.
+ *
+ * @example CLI Usage
+ * ```bash
+ * # Generate types from translation directory
+ * npx flight i18n:typegen --input ./locales/en --output ./src/i18n.d.ts
+ *
+ * # Generate nested types
+ * npx flight i18n:typegen --input ./locales/en --output ./src/i18n.d.ts --style nested
+ * ```
+ *
+ * @example Programmatic Usage
+ * ```typescript
+ * import { generateTypesAndWrite } from '@flightdev/i18n/typegen';
+ *
+ * await generateTypesAndWrite({
+ *   input: './locales/en',
+ *   output: './src/i18n.d.ts',
+ *   style: 'flat',
+ * });
+ * ```
+ *
+ * @example Using Generated Types
+ * ```typescript
+ * import type { TranslationKey } from './i18n.d.ts';
+ * import { createTypedI18n } from '@flightdev/i18n';
+ *
+ * const i18n = createTypedI18n<TranslationKey>(adapter);
+ *
+ * i18n.t('nav.home');        // Valid - autocomplete works
+ * i18n.t('nav.nonexistent'); // TypeScript error
+ * ```
+ *
+ * @module @flightdev/i18n/typegen
+ */
+/**
+ * Options for type generation
+ */
+interface TypeGenOptions {
+    /** Input directory or JSON file containing translations */
+    input: string;
+    /** Output path for generated .d.ts file */
+    output: string;
+    /**
+     * Type style:
+     * - 'flat': Union of string literal types ("nav.home" | "nav.about")
+     * - 'nested': Nested object types matching JSON structure
+     * @default 'flat'
+     */
+    style?: 'flat' | 'nested';
+    /**
+     * Custom header comment for generated file
+     * @default Auto-generated header with timestamp
+     */
+    header?: string;
+    /**
+     * Module name if generating a module declaration
+     * If provided, wraps types in `declare module`
+     */
+    moduleName?: string;
+}
+/**
+ * Result of type generation
+ */
+interface TypeGenResult {
+    /** Generated TypeScript code */
+    content: string;
+    /** Number of translation keys found */
+    keyCount: number;
+    /** List of all keys in flat format */
+    keys: string[];
+}
+/** Recursive record type for nested translations */
+type NestedRecord = {
+    [key: string]: string | NestedRecord;
+};
+/**
+ * Extract all translation keys from a nested object in dot notation
+ *
+ * @param obj - Translation object
+ * @param prefix - Current key prefix
+ * @returns Array of dot-notation keys
+ *
+ * @example
+ * ```typescript
+ * extractKeysFromObject({ nav: { home: 'Home', about: 'About' } });
+ * // ['nav.home', 'nav.about']
+ * ```
+ */
+declare function extractKeysFromObject(obj: NestedRecord, prefix?: string): string[];
+/**
+ * Load translation data from file or directory
+ *
+ * @param inputPath - Path to JSON file or directory containing JSON files
+ * @returns Merged translation object
+ */
+declare function loadTranslations(inputPath: string): NestedRecord;
+/**
+ * Generate TypeScript types from translation files
+ *
+ * @param options - Generation options
+ * @returns Generated TypeScript content and metadata
+ */
+declare function generateTypes(options: TypeGenOptions): TypeGenResult;
+/**
+ * Generate types and write to output file
+ *
+ * @param options - Generation options
+ */
+declare function generateTypesAndWrite(options: TypeGenOptions): Promise<TypeGenResult>;
+interface WatchOptions extends TypeGenOptions {
+    /** Debounce delay in milliseconds */
+    debounce?: number;
+}
+/**
+ * Watch translation files and regenerate types on changes
+ *
+ * @param options - Watch options
+ * @returns Cleanup function to stop watching
+ */
+declare function watchAndGenerate(options: WatchOptions): () => void;
+
+export { type TypeGenOptions, type TypeGenResult, type WatchOptions, extractKeysFromObject, generateTypes, generateTypesAndWrite, loadTranslations, watchAndGenerate };

package/dist/typegen.js

@@ -0,0 +1,214 @@
+// src/typegen.ts
+import * as fs from "fs";
+import * as path from "path";
+function extractKeysFromObject(obj, prefix = "") {
+  const keys = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const safeKey = key.replace(/[^a-zA-Z0-9_]/g, "_");
+    const fullKey = prefix ? `${prefix}.${safeKey}` : safeKey;
+    if (typeof value === "string") {
+      keys.push(fullKey);
+    } else if (typeof value === "object" && value !== null) {
+      keys.push(...extractKeysFromObject(value, fullKey));
+    }
+  }
+  return keys.sort();
+}
+function loadTranslations(inputPath) {
+  const absolutePath = path.resolve(inputPath);
+  if (!fs.existsSync(absolutePath)) {
+    throw new Error(`Translation path does not exist: ${absolutePath}`);
+  }
+  const stat = fs.statSync(absolutePath);
+  if (stat.isFile()) {
+    if (!absolutePath.endsWith(".json")) {
+      throw new Error(`Input file must be a JSON file: ${absolutePath}`);
+    }
+    const content = fs.readFileSync(absolutePath, "utf-8");
+    return JSON.parse(content);
+  }
+  if (stat.isDirectory()) {
+    const merged = {};
+    const files = fs.readdirSync(absolutePath);
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      const namespace = file.replace(".json", "");
+      const filePath = path.join(absolutePath, file);
+      const content = fs.readFileSync(filePath, "utf-8");
+      try {
+        merged[namespace] = JSON.parse(content);
+      } catch (error) {
+        throw new Error(`Failed to parse ${filePath}: ${error.message}`);
+      }
+    }
+    if (Object.keys(merged).length === 0) {
+      throw new Error(`No JSON files found in directory: ${absolutePath}`);
+    }
+    return merged;
+  }
+  throw new Error(`Input path is neither a file nor directory: ${absolutePath}`);
+}
+function generateFlatTypes(keys, options) {
+  const header = options.header ?? generateDefaultHeader();
+  const keyLiterals = keys.map((k) => `  | '${k}'`).join("\n");
+  let content = `${header}
+
+/**
+ * All available translation keys (union type)
+ * Use with createTypedI18n for full type safety
+ */
+export type TranslationKey =
+${keyLiterals};
+
+/**
+ * Translation key to value mapping
+ */
+export type TranslationKeys = {
+    [K in TranslationKey]: string;
+};
+
+/**
+ * Helper type to validate translation keys
+ */
+export type ValidTranslationKey<T extends string> = T extends TranslationKey ? T : never;
+`;
+  if (options.moduleName) {
+    content = `declare module '${options.moduleName}' {
+${content}
+}`;
+  }
+  return content;
+}
+function generateNestedInterface(obj, indent = 1) {
+  const spaces = "  ".repeat(indent);
+  const lines = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : `'${key}'`;
+    if (typeof value === "string") {
+      lines.push(`${spaces}${safeKey}: string;`);
+    } else if (typeof value === "object" && value !== null) {
+      lines.push(`${spaces}${safeKey}: {`);
+      lines.push(generateNestedInterface(value, indent + 1));
+      lines.push(`${spaces}};`);
+    }
+  }
+  return lines.join("\n");
+}
+function generateNestedTypes(obj, options) {
+  const header = options.header ?? generateDefaultHeader();
+  const interfaceContent = generateNestedInterface(obj);
+  let content = `${header}
+
+/**
+ * Nested translation structure matching JSON files
+ */
+export interface TranslationTree {
+${interfaceContent}
+}
+
+/**
+ * Utility type to flatten nested keys to dot notation
+ */
+type FlattenKeys<T, Prefix extends string = ''> = T extends string
+  ? Prefix
+  : {
+      [K in keyof T]: K extends string
+        ? FlattenKeys<T[K], Prefix extends '' ? K : \`\${Prefix}.\${K}\`>
+        : never;
+    }[keyof T];
+
+/**
+ * All available translation keys (flattened from nested structure)
+ */
+export type TranslationKey = FlattenKeys<TranslationTree>;
+
+/**
+ * Access nested value by dot-notation key
+ */
+type GetNested<T, K extends string> = K extends \`\${infer A}.\${infer B}\`
+  ? A extends keyof T
+    ? GetNested<T[A], B>
+    : never
+  : K extends keyof T
+  ? T[K]
+  : never;
+
+/**
+ * Get the value type for a specific key
+ */
+export type TranslationValue<K extends TranslationKey> = GetNested<TranslationTree, K>;
+`;
+  if (options.moduleName) {
+    content = `declare module '${options.moduleName}' {
+${content}
+}`;
+  }
+  return content;
+}
+function generateDefaultHeader() {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  return `/**
+ * Auto-generated translation types
+ * DO NOT EDIT - Generated by @flightdev/i18n
+ * Generated at: ${timestamp}
+ *
+ * To regenerate, run:
+ * npx flight i18n:typegen --input <translations-path> --output <output-path>
+ */`;
+}
+function generateTypes(options) {
+  const { input, style = "flat" } = options;
+  const translations = loadTranslations(input);
+  const keys = extractKeysFromObject(translations);
+  const content = style === "nested" ? generateNestedTypes(translations, options) : generateFlatTypes(keys, options);
+  return {
+    content,
+    keyCount: keys.length,
+    keys
+  };
+}
+async function generateTypesAndWrite(options) {
+  const result = generateTypes(options);
+  const outputPath = path.resolve(options.output);
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  fs.writeFileSync(outputPath, result.content, "utf-8");
+  console.log(`Generated ${result.keyCount} translation keys at ${outputPath}`);
+  return result;
+}
+function watchAndGenerate(options) {
+  const { input, debounce = 100 } = options;
+  const absolutePath = path.resolve(input);
+  let timeout = null;
+  const regenerate = () => {
+    try {
+      generateTypesAndWrite(options);
+    } catch (error) {
+      console.error("Type generation failed:", error.message);
+    }
+  };
+  const debouncedRegenerate = () => {
+    if (timeout) clearTimeout(timeout);
+    timeout = setTimeout(regenerate, debounce);
+  };
+  regenerate();
+  const watcher = fs.watch(absolutePath, { recursive: true }, (eventType, filename) => {
+    if (filename?.endsWith(".json")) {
+      console.log(`Translation file changed: ${filename}`);
+      debouncedRegenerate();
+    }
+  });
+  return () => {
+    watcher.close();
+    if (timeout) clearTimeout(timeout);
+  };
+}
+export {
+  extractKeysFromObject,
+  generateTypes,
+  generateTypesAndWrite,
+  loadTranslations,
+  watchAndGenerate
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@flightdev/i18n",
+  "version": "0.1.5",
+  "description": "Agnostic internationalization for Flight Framework. Choose your engine: i18next, Paraglide, FormatJS, Lingui, or custom.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./i18next": {
+      "types": "./dist/adapters/i18next.d.ts",
+      "import": "./dist/adapters/i18next.js"
+    },
+    "./paraglide": {
+      "types": "./dist/adapters/paraglide.d.ts",
+      "import": "./dist/adapters/paraglide.js"
+    },
+    "./formatjs": {
+      "types": "./dist/adapters/formatjs.d.ts",
+      "import": "./dist/adapters/formatjs.js"
+    },
+    "./lingui": {
+      "types": "./dist/adapters/lingui.d.ts",
+      "import": "./dist/adapters/lingui.js"
+    },
+    "./routing": {
+      "types": "./dist/routing.d.ts",
+      "import": "./dist/routing.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "import": "./dist/middleware.js"
+    },
+    "./typegen": {
+      "types": "./dist/typegen.d.ts",
+      "import": "./dist/typegen.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@formatjs/intl": ">=2.0.0",
+    "@lingui/core": ">=5.0.0",
+    "i18next": ">=23.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@formatjs/intl": {
+      "optional": true
+    },
+    "@lingui/core": {
+      "optional": true
+    },
+    "i18next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}