glotfox 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
+# glotfox
 
-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.
+Command-line tool for [GlotFox](https://glotfox.app.dukauskas.lt). It extracts translation keys from React, Next.js and vanilla JS/TS projects into the source-locale files.
+
+Requires Node 22+.
+
+```sh
+npx glotfox init --source en --targets de,fr
+npx glotfox extract
+```
+
+## Commands
+
+### `glotfox init`
+
+Writes `glotfox.config.json` in the current directory. It refuses to overwrite an existing file unless you pass `--force`.
+
+| Option | Description |
+|--------|-------------|
+| `--source <locale>` | Source locale (default `en`). |
+| `--targets <a,b,...>` | Comma-separated target locales (default: none). |
+| `--force` | Overwrite an existing config. |
+
+`include` is set to the `src`, `app`, `pages` and `components` folders that exist (falling back to `src`).
+
+### `glotfox extract`
+
+Scans the files matched by `include`/`exclude` and writes the keys it finds into `<output.dir>/<sourceLocale>/<namespace>.json`.
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Report what would change without writing files. |
+| `--force` | Overwrite descriptions that already exist in `*.meta.json`. |
+
+Behavior:
+
+- **Never deletes.** Existing keys and values (including hand-edited source text and all target-locale translations) are kept as they are. New keys are added and files are written with sorted keys.
+- **Reports unused keys.** Keys that are in the source locale but no longer found in code are listed; they stay in the file.
+- Creates missing target-locale files for each namespace. With `output.emptyValues: "empty"`, missing keys are added as `""`; the default `"omit"` leaves them out.
+- Keys that are invalid (see the file format spec) or that conflict with an existing key (one being a prefix of the other) are skipped with a warning.
+
+### `glotfox push` / `glotfox pull`
+
+Sync with the GlotFox service using a project API key (create one in the dashboard):
+
+```sh
+export GLOTFOX_API_KEY=gf_...
+npx glotfox extract
+npx glotfox push     # upload source keys and descriptions
+npx glotfox pull     # write approved translations into the locale files
+```
+
+| Option | Description |
+|--------|-------------|
+| `--api-url <url>` | Server URL (default `$GLOTFOX_API_URL`, then `https://glotfox.app.dukauskas.lt`). |
+| `--dry-run` | Report what would happen without uploading (`push`) or writing files (`pull`). |
+
+- `push` sends every key of the source-locale files as `namespace:key` with its text and its `*.meta.json` description. It never deletes keys on the server.
+- `pull` fetches the **approved** translations of each `targetLocales` entry and merges them into `<output.dir>/<locale>/<namespace>.json` (sorted keys). Approved text wins; other local keys are left alone.
+
+### `glotfox check`
+
+Read-only check for CI (see `packages/action`). Exits with 1 if code uses keys that are not in the source-locale files (run `extract`) or if the generated types file (`output.types`) is missing or out of date. Writes nothing.
+
+It also runs the translation QA checks (`@glotfox/shared/qa`) on every non-empty target-locale message: `icu-invalid` is an error and fails the check; other findings (missing/extra placeholders, plural categories, whitespace, punctuation, numbers, untranslated) are listed as warnings. `--strict` turns warnings into failures.
+
+### `glotfox types`
+
+Generates a TypeScript declaration file from the source-locale files, so unknown keys and missing or mistyped ICU placeholders become compile errors. The file path comes from `output.types` in the config (e.g. `"types": "src/glotfox.d.ts"`); `extract` runs the same step at the end when `output.types` is set.
+
+| Option | Description |
+|--------|-------------|
+| `--out <file>` | Output file, relative to the config directory (overrides `output.types`). |
+| `--dry-run` | Report whether the file would change without writing it. |
+
+Placeholder types follow the file format spec: `{x}` → `string | number`, `number`/`plural`/`selectordinal` → `number`, `date`/`time` → `Date | number`, `select` → its branch names (`'a' | 'b' | (string & {})`), and `<tag>` → `(chunks) => unknown`. Messages that fail to parse produce a warning and untyped placeholders.
+
+The generated file exports `TFunction`, `TranslationKey` and `GlotfoxMessages`. Keys are available as `namespace:key`, and as plain `key` for the default namespace. Use `TFunction` to type your translate function:
+
+```ts
+import type { TFunction } from "./glotfox"; // src/glotfox.d.ts
+
+declare const t: TFunction;
+
+t("greeting", { name: "Ada" }); // "greeting": "Hello, {name}!"
+t("greeting");                  // error: missing placeholder "name"
+t("missing.key");               // error: unknown key
+```
+
+With i18next/react-i18next, wrap your `t` once: `const typedT = t as unknown as TFunction`. Re-run `glotfox types` (or `extract`) after changing the source-locale files.
+
+## What is detected
+
+| Pattern | Notes |
+|---------|-------|
+| `t('key')`, `i18n.t('key')`, `` t(`key`) `` | String literals only; dynamic keys (`t(variable)`) are ignored. |
+| `t('key', 'Default text')` | Default text becomes the source string. |
+| `t('key', { defaultValue: '...', description: '...', ns: '...' })` | `description` is written to `<namespace>.meta.json`. |
+| `<Trans i18nKey="key" defaults="..." ns="..." />` | Default text from `defaults`, or from plain-text children. |
+| `useTranslation('ns')` / `useTranslation(['ns', ...])` | The first namespace is the default for `t` and `<Trans>` in that file. |
+| `t('ns:key')` | Explicit namespace prefix. |
+
+Without a default text, a new key's value is set to the key itself and a warning is printed. Keys without a namespace go to `defaultNamespace` (default `common`).
+
+## Config
+
+See `glotfox.config.json` in the translation file format spec. Example:
+
+```json
+{
+  "version": 1,
+  "sourceLocale": "en",
+  "targetLocales": ["de", "fr"],
+  "defaultNamespace": "common",
+  "include": ["src/**/*.{ts,tsx,js,jsx,mjs,cjs}"],
+  "exclude": ["**/*.test.*", "**/node_modules/**"],
+  "output": { "dir": "locales", "pattern": "{locale}/{namespace}.json", "emptyValues": "omit" }
+}
+```
+
+Unknown fields are rejected. `output.format` is `"json"` (default), `"po"` or `"yaml"`; use a matching `output.pattern` (e.g. `{locale}/{namespace}.po`). Descriptions always stay in `<namespace>.meta.json`.
+
+## Development
+
+```sh
+pnpm install
+pnpm --filter glotfox test
+pnpm --filter glotfox build
+```

package/dist/_shared/formats.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Translation file formats (docs/file-format.html): JSON, gettext PO and YAML.
+ * Every format maps to the same model: a flat `key -> ICU message` object where keys may contain dots.
+ * Dependency-free and self-contained so the CLI, worker and web app can share it.
+ */
+export declare const FILE_FORMATS: readonly ["json", "po", "yaml"];
+export type FileFormat = (typeof FILE_FORMATS)[number];
+export type Messages = Record<string, string>;
+export declare const isFileFormat: (v: unknown) => v is FileFormat;
+export declare const FORMAT_EXTENSION: Record<FileFormat, string>;
+export declare const defaultPattern: (format: FileFormat) => string;
+export interface SerializeOptions {
+    /** Written to the PO header (`Language:`). */
+    locale?: string;
+}
+export declare function parseMessages(format: FileFormat, text: string): Messages;
+/** Keys sorted, always ending with a newline. */
+export declare function serializeMessages(format: FileFormat, messages: Messages, opts?: SerializeOptions): string;

package/dist/check.d.ts

@@ -0,0 +1,23 @@
+import { type Issue } from "@glotfox/shared/qa";
+export interface CheckResult {
+    /** "ns:key" found in code but missing from the source-locale files (run `glotfox extract`). */
+    missing: string[];
+    /** The generated types file is missing or out of date (run `glotfox types`). */
+    typesStale: boolean;
+    typesFile?: string;
+    warnings: string[];
+    /** QA findings for non-empty target translations (see `@glotfox/shared/qa`). */
+    issues: QaFinding[];
+    ok: boolean;
+}
+export interface QaFinding {
+    locale: string;
+    /** "ns:key" */
+    key: string;
+    issue: Issue;
+}
+/** Read-only verification used in CI: nothing is written. `strict` makes QA warnings fail the check. */
+export declare function check(opts: {
+    cwd: string;
+    strict?: boolean;
+}): CheckResult;