@dialexjs/cli 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Halil Aydın
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,87 @@
-# Temporary Holding Version
+# @dialexjs/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+> High-performance CLI tool for Dialex internationalization (codegen, scaffolding, CI parity checking).
+
+[![npm version](https://img.shields.io/npm/v/@dialexjs/cli.svg)](https://www.npmjs.com/package/@dialexjs/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 📦 Installation
+
+```bash
+# Locally in project (Recommended)
+npm install -D @dialexjs/cli dialexjs
+bun add -d @dialexjs/cli dialexjs
+
+# Or globally
+npm install -g @dialexjs/cli
+```
+
+Binaries installed: `dialexjs` and alias `dx`.
+
+---
+
+## 🛠️ Commands
+
+### `dialex init`
+
+Initialize or configure Dialex in any project:
+
+- **Automatic Framework Detection**: Identifies Next.js, Fastify, Koa, Hono, Express, NestJS, Elysia, SvelteKit, Astro, Vue, Nuxt, and React/Vite.
+- **Magicast AST Injection**: Manipulates `dialex.config.ts` and injects Vite plugins into `vite.config.ts` (React, Vue) and the module into `nuxt.config.ts` (Nuxt) cleanly.
+- **Starter Dictionaries**: Emits typed starter dictionary and TypeScript declaration file.
+
+```bash
+# Interactive:
+dialex init
+
+# Headless / CI:
+dialex init --framework fastify --default-locale en --locales en,tr -y
+```
+
+### `dialex generate` (alias: `gen`)
+
+Compiles `.content.ts` dictionaries into static TypeScript modules for zero-overhead server execution:
+
+- Outputs `src/i18n.generated.ts` (static dictionary map).
+- Outputs `src/dialex-env.d.ts` (type registry augmentation).
+- **Watch Mode (`-w` / `--watch`)**: Continuously monitors dictionary changes and updates bundles instantaneously.
+
+```bash
+dialex generate
+dialex generate --watch
+```
+
+### `dialex export` / `dialex import`
+
+Round-trip strings with translators as JSON, CSV or XLIFF 1.2, without editing TypeScript.
+
+```bash
+dialex export -f xliff -o translations
+dialex import translations/tr.xlf
+```
+
+### `dialex translate`
+
+Fills missing (or `[TODO]`) strings with a provider you configure in `dialex.config.ts`. Built-in providers for Claude, OpenAI (ChatGPT), Gemini and DeepL are exported from `@dialexjs/cli/translate`. `--dry-run` lists what would be sent without calling anything.
+
+### `dialex check` (alias: `lint`)
+
+CI verification command:
+
+- Checks translation parity across all registered locales.
+- Detects missing keys or untracked locale entries (including nested keys).
+- Flags `getDictionary("x")` / `t("x.y")` calls that point at nothing, and warns about possibly unused keys.
+- `--fix` inserts missing keys marked `[TODO]`; `--json` and `--github` produce machine-readable output.
+- Exits with code `1` on parity errors, ideal for pre-commit hooks and GitHub Actions.
+
+```bash
+dialex check
+```
+
+---
+
+## 📄 License
+
+MIT © [awaiden](https://github.com/awaiden)

package/dist/api.d.mts

@@ -0,0 +1,246 @@
+import { loadFile } from "magicast";
+import { I18nConfig } from "dialexjs";
+//#region src/utils/dictionary-edit.d.ts
+/**
+ * AST-level helpers for reading and editing `.content.ts` dictionary files.
+ *
+ * Magicast's proxy layer cannot represent every value (for example template-literal
+ * functions), so these helpers work on the underlying AST nodes and use Magicast only
+ * to parse and print, which preserves the rest of the file's formatting.
+ *
+ * Supported shapes:
+ * - `export default defineDictionary("name", { en: {...}, tr: {...} })`
+ * - `export default defineDictionary({ name: "name", dictionary: { ... } })`
+ * - `export default { name: "name", dictionary: { ... } }`
+ */
+type Node = {
+  type: string;
+  [key: string]: any;
+};
+export declare const TODO_PREFIX = "[TODO] ";
+interface DictionaryFile {
+  file: string;
+  /** Dictionary name from `defineDictionary("name", ...)` or the `name` property, if literal. */
+  name?: string;
+  mod: Awaited<ReturnType<typeof loadFile>>;
+  /** The object whose keys are locales. */
+  localesObj: Node;
+  /** Whether the file ended with a newline when loaded; restored on save. */
+  endsWithNewline: boolean;
+  /**
+   * `false` when part of the dictionary cannot be read statically (spreads, computed keys, or a
+   * locale whose content is not an object literal). Leaf lists and parity checks are unreliable
+   * for such files.
+   */
+  complete: boolean;
+}
+/** A zero-based line/column range, as used by editors. */
+interface SourceRange {
+  start: {
+    line: number;
+    column: number;
+  };
+  end: {
+    line: number;
+    column: number;
+  };
+}
+type LeafKind = "string" | "function" | "other";
+interface Leaf {
+  path: string[];
+  kind: LeafKind;
+  /** Present when `kind` is `"string"`. */
+  value?: string;
+}
+/**
+ * Parses dictionary source text (for example an unsaved editor buffer). Returns `undefined` when
+ * the file does not have an editable shape; throws on syntax errors.
+ */
+export declare function parseDictionaryText(file: string, text: string): DictionaryFile | undefined;
+/** Loads a dictionary file; returns `undefined` when its shape is not editable. */
+export declare function loadDictionaryFile(file: string): Promise<DictionaryFile | undefined>;
+/** The source text with all edits applied, without writing anything. */
+export declare function renderDictionaryFile(df: DictionaryFile): string;
+export declare function saveDictionaryFile(df: DictionaryFile): Promise<void>;
+export declare function listLocales(df: DictionaryFile): string[];
+/** Lists every leaf (string, function, or other value) of a locale, in source order. */
+export declare function listLeaves(df: DictionaryFile, locale: string): Leaf[];
+export declare function hasPath(df: DictionaryFile, locale: string, path: string[]): boolean;
+export declare function getString(df: DictionaryFile, locale: string, path: string[]): string | undefined;
+type SetResult = "created" | "updated" | "skipped";
+/**
+ * Sets a string value at `path`. Existing function or non-string values are left alone
+ * (`"skipped"`) because they cannot be translated as plain text.
+ */
+export declare function setString(df: DictionaryFile, locale: string, path: string[], value: string): SetResult;
+/**
+ * Copies the leaf at `path` from one locale to another. String values can be rewritten with
+ * `mapString` (for example to add a `[TODO]` marker); other values are copied verbatim.
+ * Returns `false` when the source has no such leaf or the target already has one.
+ */
+export declare function copyLeaf(df: DictionaryFile, fromLocale: string, toLocale: string, path: string[], mapString?: (value: string) => string): boolean;
+/**
+ * Where a locale (no `path`) or a key within it is written. The range covers the property key, so
+ * it is a good place to attach a diagnostic or jump to.
+ */
+export declare function locationOf(df: DictionaryFile, locale: string, path?: string[]): SourceRange | undefined;
+/** The source text of the dictionary object itself (the object whose keys are locales). */
+export declare function dictionaryLocation(df: DictionaryFile): SourceRange | undefined;
+/** The source code of a leaf's value (a function's source, or a string with its quotes). */
+export declare function getLeafSource(df: DictionaryFile, locale: string, path: string[]): string | undefined;
+//#endregion
+//#region src/analysis.d.ts
+/**
+ * Project analysis shared by `dialex check` and the editor extension.
+ *
+ * It reads dictionaries from the syntax tree, so it never runs project code. Dictionaries that
+ * cannot be read that way (spreads, computed keys, imported values) are skipped with an `info`
+ * issue, unless `runtime: true` is passed, in which case they are imported and read from the
+ * evaluated module (the CLI does this; editors must not).
+ */
+type IssueLevel = "error" | "warning" | "info";
+type IssueCode = "invalid-dictionary" | "unanalyzable" | "missing-locale" | "missing-key" | "invalid-locale" | "todo-placeholder" | "invalid-icu" | "icu-args-mismatch" | "icu-plural-categories" | "unknown-dictionary" | "unknown-path" | "unused-key" | "unused-dictionary";
+interface AnalysisIssue {
+  /** Absolute path of the file the issue is in. */
+  file: string;
+  level: IssueLevel;
+  code: IssueCode;
+  message: string;
+  /** Where to point, when known. Lines and columns are zero-based. */
+  range?: SourceRange;
+  /** The dictionary the issue is about, when it is about one. */
+  dictionary?: string;
+  locale?: string;
+  /** Key path within the dictionary. */
+  path?: string[];
+  /** For `missing-key`: a locale that has the key, to copy it from. */
+  sourceLocale?: string;
+}
+interface AnalysisConfig {
+  defaultLocale?: string;
+  locales?: string[];
+  include?: string | string[];
+}
+interface AnalysisOptions {
+  root: string;
+  config: AnalysisConfig;
+  /** Source globs to scan for dictionary references. Pass `[]` to skip scanning. */
+  src?: string[];
+  /** Import dictionaries the syntax tree cannot fully describe. Runs project code. */
+  runtime?: boolean;
+  /** Extra ignore globs, relative to `root`. */
+  ignore?: string[];
+  /** Report possibly unused keys and dictionaries. @default true */
+  unused?: boolean;
+}
+interface LeafInfo {
+  kind: "string" | "function" | "other";
+  value?: string;
+}
+interface AnalyzedDictionary {
+  name: string;
+  /** Absolute path. */
+  file: string;
+  /** Locales in source order. */
+  locales: string[];
+  /** `locale -> dotted path -> leaf` */
+  leaves: Map<string, Map<string, LeafInfo>>;
+  /** Union of dotted leaf paths across locales, in order of first appearance. */
+  paths: string[];
+  /** The parsed file, present when it was read statically. */
+  df?: DictionaryFile;
+}
+interface AnalysisResult {
+  issues: AnalysisIssue[];
+  dictionaries: AnalyzedDictionary[];
+  /** Absolute paths of every dictionary file that matched. */
+  files: string[];
+  sourceFilesScanned: number;
+}
+export declare const DEFAULT_SOURCE_GLOB = "**/*.{ts,tsx,js,jsx,mjs,cjs,vue,svelte,astro,mdx}";
+interface Reference {
+  /** A dictionary name, or a full `dictionary.key.path`. */
+  kind: "dictionary" | "path";
+  value: string;
+  /** Offsets of the string's contents (without the quotes) in the scanned text. */
+  start: number;
+  end: number;
+}
+/** Finds `getDictionary("x")`-style and `t("x.y.z")` references in source text. */
+export declare function scanReferences(text: string): Reference[];
+export declare function analyzeProject(options: AnalysisOptions): Promise<AnalysisResult>;
+/** Project root-relative path with forward slashes, for display. */
+export declare function relativeFile(root: string, file: string): string;
+//#endregion
+//#region src/utils/static-config.d.ts
+/**
+ * The parts of `dialex.config` that tooling needs, read **without running the file**. Editors must
+ * not execute workspace code (it may be untrusted), so values are read from the syntax tree and
+ * only literals are understood.
+ */
+interface StaticConfig {
+  defaultLocale: string;
+  locales: string[];
+  include: string | string[];
+  fallbacks: Record<string, string[]>;
+  prefixDefault: boolean;
+  lazy: boolean;
+}
+interface StaticConfigResult {
+  config: StaticConfig;
+  /** The file the values came from, if any. */
+  file?: string;
+  /** Things that could not be read statically, for example `locales: getLocales()`. */
+  notes: string[];
+}
+export declare const DEFAULT_STATIC_CONFIG: StaticConfig;
+/** Reads a config file's source text. Exposed for tests and for unsaved buffers. */
+export declare function parseStaticConfig(text: string, file?: string): StaticConfigResult;
+/** Reads `dialex.config.*` (or `i18n.config.*`) from `root`, or from `configFile` if given. */
+export declare function readStaticConfig(root: string, configFile?: string): StaticConfigResult;
+//#endregion
+//#region src/utils/project.d.ts
+interface ProjectDictionary {
+  /** Path relative to the project root. */
+  rel: string;
+  name: string;
+  df: DictionaryFile;
+}
+interface Project {
+  root: string;
+  config: I18nConfig;
+  dictionaries: ProjectDictionary[];
+  /** Dictionary files that could not be parsed into an editable shape. */
+  unsupported: string[];
+  /** Config values that could not be read statically (static loading only). */
+  notes: string[];
+}
+/**
+ * Resolves the config (running `dialex.config.*` through the loader, which executes it) and loads
+ * every dictionary file for AST-level reading and editing.
+ */
+export declare function loadProject(root: string, configFile?: string): Promise<Project>;
+/**
+ * Like `loadProject`, but reads the config from the syntax tree without executing it. Use this in
+ * editors and anywhere project code must not run.
+ */
+export declare function loadStaticProject(root: string, configFile?: string): Promise<Project>;
+/** `home` + `["nav", "about"]` -> `home.nav.about` */
+export declare const toKey: (dictionary: string, keyPath: string[]) => string;
+//#endregion
+//#region src/commands/generate.d.ts
+interface GenerateOptions {
+  cwd?: string;
+  watch?: boolean;
+  output?: string;
+  config?: string;
+  json?: boolean;
+}
+export declare function generateDictionaries(root: string, options?: GenerateOptions): {
+  files: string[];
+  outputPath: string;
+  dtsPath: string;
+};
+//#endregion
+export type { AnalysisConfig, AnalysisIssue, AnalysisOptions, AnalysisResult, AnalyzedDictionary, DictionaryFile, GenerateOptions, IssueCode, IssueLevel, Leaf, LeafInfo, LeafKind, Project, ProjectDictionary, Reference, SourceRange, StaticConfig, StaticConfigResult };
+//# sourceMappingURL=api.d.mts.map

package/dist/api.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.mts","names":[],"sources":["../src/utils/dictionary-edit.ts","../src/analysis.ts","../src/utils/static-config.ts","../src/utils/project.ts","../src/commands/generate.ts"],"mappings":";;;;;;;;;;;;;;;KAgBK;EAAS;GAAe;;qBAEhB;UAII;EACf;;EAEA;EACA,KAAK,QAAQ,kBAAkB;;EAE/B,YAAY;;EAEZ;;;;;;EAMA;;;UAIe;EACf;IAAS;IAAc;;EACvB;IAAO;IAAc;;;KAGX;UAEK;EACf;EACA,MAAM;;EAEN;;;;;;wBAgIc,oBAAoB,cAAc,eAAe;;wBAoB3C,mBAAmB,eAAe,QAAQ;;wBAKhD,qBAAqB,IAAI;wBAKnB,mBAAmB,IAAI,iBAAiB;wBAQ9C,YAAY,IAAI;;wBAahB,WAAW,IAAI,gBAAgB,iBAAiB;wBAoChD,QAAQ,IAAI,gBAAgB,gBAAgB;wBAI5C,UAAU,IAAI,gBAAgB,gBAAgB;KA+BlD;;;;;wBAMI,UACd,IAAI,gBACJ,gBACA,gBACA,gBACC;;;;;;wBAsBa,SACd,IAAI,gBACJ,oBACA,kBACA,gBACA,aAAa;;;;;wBAwCC,WACd,IAAI,gBACJ,gBACA,kBACC;;wBAMa,mBAAmB,IAAI,iBAAiB;;wBAKxC,cACd,IAAI,gBACJ,gBACA;;;;;;;;;;;KCnXU;KAEA;UAeK;;EAEf;EACA,OAAO;EACP,MAAM;EACN;;EAEA,QAAQ;;EAER;EACA;;EAEA;;EAEA;;UAGe;EACf;EACA;EACA;;UAGe;EACf;EACA,QAAQ;;EAER;;EAEA;;EAEA;;EAEA;;UAGe;EACf;EACA;;UAGe;EACf;;EAEA;;EAEA;;EAEA,QAAQ,YAAY,YAAY;;EAEhC;;EAEA,KAAK;;UAGU;EACf,QAAQ;EACR,cAAc;;EAEd;EACA;;qBAKW;UAqBI;;EAEf;EACA;;EAEA;EACA;;;wBAIc,eAAe,eAAe;wBA4IxB,eAAe,SAAS,kBAAkB,QAAQ;;wBA+NxD,aAAa,cAAc;;;;;;;;UCte1B;EACf;EACA;EACA;EACA,WAAW;EACX;EACA;;UAGe;EACf,QAAQ;;EAER;;EAEA;;qBAMW,uBAAuB;;wBAiFpB,kBAAkB,cAAc,gBAA4B;;wBA8C5D,iBAAiB,cAAc,sBAAsB;;;UC5JpD;;EAEf;EACA;EACA,IAAI;;UAGW;EACf;EACA,QAAQ;EACR,cAAc;;EAEd;;EAEA;;;;;;wBAgCoB,YAAY,cAAc,sBAAsB,QAAQ;;;;;wBASxD,kBAAkB,cAAc,sBAAsB,QAAQ;;qBAMvE,QAAK,oBAAsB;;;UC7DvB;EACf;EACA;EACA;EACA;EACA;;wBAGc,qBACd,cACA,UAAS;EAET;EACA;EACA"}

package/dist/api.mjs

@@ -0,0 +1,2 @@
+import { C as saveDictionaryFile, S as renderDictionaryFile, T as generateDictionaries, _ as listLeaves, a as parseStaticConfig, b as locationOf, c as analyzeProject, d as TODO_PREFIX, f as copyLeaf, g as hasPath, h as getString, i as DEFAULT_STATIC_CONFIG, l as relativeFile, m as getLeafSource, n as loadStaticProject, o as readStaticConfig, p as dictionaryLocation, r as toKey, s as DEFAULT_SOURCE_GLOB, t as loadProject, u as scanReferences, v as listLocales, w as setString, x as parseDictionaryText, y as loadDictionaryFile } from "./project-gkFBurqG.mjs";
+export { DEFAULT_SOURCE_GLOB, DEFAULT_STATIC_CONFIG, TODO_PREFIX, analyzeProject, copyLeaf, dictionaryLocation, generateDictionaries, getLeafSource, getString, hasPath, listLeaves, listLocales, loadDictionaryFile, loadProject, loadStaticProject, locationOf, parseDictionaryText, parseStaticConfig, readStaticConfig, relativeFile, renderDictionaryFile, saveDictionaryFile, scanReferences, setString, toKey };

package/dist/index.d.mts

@@ -0,0 +1 @@
+export {}