npm - glotfile - Versions diffs - 0.5.1 → 0.5.2 - Mend

glotfile 0.5.1 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/dist/server/cli.js +296 -45
package/dist/server/server.js +252 -42
package/dist/ui/assets/{index-DC89onXX.js → index-B1UwtMSs.js} +2 -2
package/dist/ui/index.html +1 -1
package/package.json +3 -2
package/skill/SKILL.md +66 -0
package/skill/references/cli-reference.md +84 -0
package/skill/references/conventions.md +50 -0
package/skill/references/schema.md +99 -0
package/skill/references/workflows.md +84 -0

package/dist/ui/index.html CHANGED Viewed

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Glotfile</title>
-    <script type="module" crossorigin src="/assets/index-DC89onXX.js"></script>
+    <script type="module" crossorigin src="/assets/index-B1UwtMSs.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DPfAS4pJ.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "glotfile",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Local-first, git-native translation management.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "skill"
   ],
   "engines": {
     "node": "^20.19.0 || >=22.12.0"

package/skill/SKILL.md ADDED Viewed

@@ -0,0 +1,66 @@
+---
+name: glotfile
+description: Manage translations in a repo that uses glotfile (a local-first, git-native translation catalog). Use when working in a project containing a glotfile.json or glotfile/ directory, or when the user asks to add/edit/translate/export strings, work with locales/i18n, or run any `glotfile` command. Covers the CLI workflows, the glotfile.json schema, adding and editing strings, glossary, and project conventions.
+---
+# Managing glotfile
+Glotfile keeps every translatable string for a project in one committed state file —
+`glotfile.json` (or a `glotfile/` directory when storage is split). A local web UI,
+a CLI, and pluggable AI providers all read and write that one file; platform locale
+files (Flutter ARB, Laravel PHP, i18next/vue-i18n JSON, gettext `.po`, Apple
+`.strings`/`.stringsdict`, Angular XLIFF, Rails YAML) are **generated from it on export**.
+## The one rule that prevents most mistakes
+**The state file is the single source of truth. Exported locale files are generated
+output — never hand-edit them.** Editing `lib/l10n/app_fr.arb` or `resources/lang/fr/`
+directly is wasted work: the next `glotfile export` overwrites it. Change the source
+string in glotfile, then export.
+To make a change:
+1. Edit the **state file** (or run a `glotfile` command, or use the UI).
+2. Run `glotfile export` to regenerate the locale files.
+3. Commit both the state file and the regenerated outputs.
+## Before you touch anything: discover the project's actual config
+Do not assume the locales, providers, or output formats — read them. They live in the
+state file's `config` block.
+- Single-file layout: read `glotfile.json` → `.config`.
+- Split layout: read `glotfile/config.json` → `.config`.
+`config.sourceLocale`, `config.locales`, and `config.outputs[]` tell you what languages
+exist and where exports land. Match the project; don't introduce a new locale or adapter
+unless asked.
+## Task → tool map
+| You want to… | Do this |
+| --- | --- |
+| Add a new string | Add a `KeyEntry` to `keys` (source-locale value, `state: "source"`), then `glotfile translate` + `glotfile export`. See `references/workflows.md`. |
+| Edit an existing source string | Change the source-locale value; downstream translations become stale — re-translate. See `references/workflows.md`. |
+| Translate missing strings | `glotfile translate` (only fills empties; `--all` re-translates everything). |
+| Write locale files | `glotfile export` |
+| Find problems | `glotfile lint` (catalog issues) / `glotfile check` (lint + exports up to date) |
+| Bootstrap from existing locale files | `glotfile import --format <adapter>` — see `references/workflows.md`. |
+| Remove dead keys | `glotfile prune --unused` / `--empty-source` (dry-run unless `--write`). |
+| Enforce term translations | Glossary — see `references/workflows.md`. |
+## Reference files — read the one you need
+- `references/cli-reference.md` — every command, its flags, and when to reach for it.
+- `references/schema.md` — the shape of `glotfile.json`: `Config`, `KeyEntry`, plurals,
+  placeholders, locale states. Read before editing the file by hand.
+- `references/workflows.md` — step-by-step recipes: adding/editing strings, onboarding a
+  repo via `import`, populating the glossary, building context for better translations.
+- `references/conventions.md` — guardrails and the mental model. Read this if you are
+  unsure whether an action fights the tool.
+## Provider/API keys
+AI provider settings and API keys live in **per-machine local settings** (not the
+committed config), so they are absent in fresh clones. If a `translate` or
+`build-context` run fails for a missing key/provider, that is a configuration step for
+the user — don't invent keys or commit them.

package/skill/references/cli-reference.md ADDED Viewed

@@ -0,0 +1,84 @@
+# glotfile CLI reference
+Run via `npx glotfile <command>` (or `node bin/glotfile.js <command>` from a checkout).
+Every command accepts the global flags:
+- `-f, --file <path>` — state file to use (default: `./glotfile.json`).
+- `-h, --help` — show help. `glotfile <command> --help` shows a command's options.
+The state file is auto-detected: a `glotfile/` directory (split layout) wins over a
+single `glotfile.json`.
+## serve
+`glotfile serve [--dev]` — start the local web UI (the default command when none is
+given). Opens a browser at a local URL. `--dev` runs the UI from source with hot reload
+(the API runs on a separate port; open the Vite URL, not the API port). With
+`config.autoExport` on (the default), serving re-exports to disk on every change.
+## export
+`glotfile export [--adapter <name>] [--watch]` — write the locale files for every
+configured output in `config.outputs`.
+- `--adapter <name>` — only export this adapter (e.g. `flutter-arb`, `laravel-php`).
+- `--watch` — re-export whenever the state file changes.
+Adapter names: `flutter-arb`, `laravel-php`, `i18next-json`, `vue-i18n-json`,
+`gettext-po`, `apple-strings`, `apple-stringsdict`, `angular-xliff`, `rails-yaml`.
+## translate
+`glotfile translate [--all] [--estimate] [--locale <list>] [--key <glob>]` — AI-translate
+strings into the target locales and write the results back into the state file.
+- By default only **empty** values are translated (existing translations are left alone).
+- `--all` — re-translate every string, overwriting existing translations.
+- `--estimate` — print batch/token/cost estimates and translate nothing.
+- `--locale fr,de` — restrict to these target locales (alias: `--locales`).
+- `--key <glob>` — only keys matching the glob (e.g. `auth.*`).
+Requires a configured AI provider + API key in per-machine local settings.
+## lint
+`glotfile lint [--format text|json|sarif] [--locale <list>] [--rule <list>] [--max-warnings <n>] [--include-suppressed] [--accept]`
+— check the catalog for problems (placeholder mismatches, length, glossary violations,
+spelling, identical-to-source, …).
+- `--max-warnings <n>` — exit non-zero if warnings exceed n (for CI).
+- `--accept` — suppress all current warnings (narrow with `--rule`/`--locale`); each
+  suppression expires automatically when its key's source text changes.
+- `--include-suppressed` — also show findings hidden by suppressions.
+## check
+`glotfile check [--format text|json|sarif]` — lint the catalog **and** verify the
+exported files on disk are up to date. Use in CI to catch a state file that was changed
+without re-exporting. Exits non-zero on any error.
+## import
+`glotfile import --format <name> [--source <dir>] [--source-locale <code>] [--locales <list>] [--cldr] [--force]`
+— create `glotfile.json` from a project's existing locale files. See
+`references/workflows.md` for the onboarding flow.
+- `--source <dir>` — directory to import from (default: the state file's directory).
+- `--source-locale <code>` — which locale is the source of truth.
+- `--cldr` — expand CLDR plural forms.
+- `--force` — overwrite an existing `glotfile.json`.
+## build-context
+`glotfile build-context [--all] [--key <glob>] [--limit <n>] [--since <date>]` —
+AI-generate per-key context (where/how a string is used) to improve translation quality.
+**Requires a prior `glotfile scan`** to index code references.
+## scan
+`glotfile scan` — index the codebase's references to translation keys, writing
+`.glotfile/usage.json`. Feeds `build-context` and `prune --unused`.
+## prune
+`glotfile prune (--empty-source | --unused) [--write]` — remove keys. **Dry-run (lists
+only) unless `--write` is given.**
+- `--empty-source` — keys whose source value is empty.
+- `--unused` — keys with no code reference (runs a scan first so the result is current).
+## split
+`glotfile split` — convert a single `glotfile.json` into a `glotfile/` directory
+(`config.json`, `keys.json`, `locales/<code>.json`). Produces smaller, more reviewable
+git diffs on large catalogs. All commands work with either layout.
+## skill
+`glotfile skill [--print] [--force]` — install this Claude Code skill into the current
+repo's `.claude/skills/glotfile/`. `--print` writes `SKILL.md` to stdout instead;
+`--force` overwrites an existing install.

package/skill/references/conventions.md ADDED Viewed

@@ -0,0 +1,50 @@
+# glotfile conventions & guardrails
+The mental model, and the rules that keep you from fighting the tool.
+## Local-first and git-native
+Everything lives in the repo and is meant to be committed. There is no server, no
+database, no account. The state file IS the database. A change isn't done until it's
+saved to the state file, exported, and committed.
+## The state file is the source of truth — exports are derived
+- **Never hand-edit exported locale files** (ARB, PHP, JSON, `.po`, `.strings`,
+  `.stringsdict`, XLIFF, YAML). They are regenerated by `glotfile export` and your edit
+  will be overwritten. Edit the state file instead, then export.
+- When you see a stale or wrong translation in an exported file, fix it in
+  `keys.<name>.values.<locale>` and re-export.
+## Keep diffs minimal
+- Glotfile serializes deterministically (stable key order, fixed indent, trailing
+  newline). Don't reformat the state file or reorder keys — let glotfile / the UI write
+  it so diffs stay reviewable.
+- Commit the state file and the regenerated outputs together, so the catalog and the
+  locale files never drift apart in history. `glotfile check` verifies they're in sync.
+## Two on-disk layouts — support both
+A project is either single-file (`glotfile.json`) or split (`glotfile/` directory).
+`glotfile` auto-detects (split wins). Read whichever exists; don't convert between them
+unless asked (`glotfile split` does the conversion). Large catalogs prefer split for
+smaller diffs.
+## Config round-trip
+Saving Settings from the UI replaces the entire `config` object. If you add a new
+`config.*` field, it must be modeled in the Settings round-trip or it gets silently wiped
+on the next save. When in doubt, set config via the UI/CLI rather than hand-editing.
+## Secrets stay out of the committed config
+AI provider API keys and editor choices live in **per-machine local settings**, never in
+`glotfile.json`. Don't move them into the committed config and don't commit keys. A fresh
+clone won't have them — a failed `translate` due to a missing key is a user setup step.
+## Don't assume — read
+Locales, output adapters, key-naming convention, and provider are all project-specific.
+Read them from the state file and follow the existing patterns rather than introducing
+new ones. Add a locale or output only when explicitly asked.

package/skill/references/schema.md ADDED Viewed

@@ -0,0 +1,99 @@
+# glotfile.json schema
+Read this before editing the state file by hand. Glotfile re-serializes the file
+deterministically (stable key order, fixed indent, trailing newline) so diffs stay
+minimal — match that style, or just let a `glotfile` command / the UI write it.
+Locales are canonicalized to lowercase BCP-47 (e.g. `pt-br`) on load and save.
+## Top-level shape
+```jsonc
+{
+  "version": 1,
+  "config": { /* Config — see below */ },
+  "glossary": [ /* term entries */ ],
+  "keys": { /* keyName -> KeyEntry */ }
+}
+```
+In **split** layout this is spread across `glotfile/config.json` (holds `version` +
+`config` + `glossary`), `glotfile/keys.json` (metadata per key), and
+`glotfile/locales/<code>.json` (the values for one locale).
+## Config
+```jsonc
+{
+  "sourceLocale": "en",
+  "locales": ["en", "fr", "de"],          // every locale in the catalog
+  "outputs": [                             // one per generated locale file set
+    { "adapter": "flutter-arb", "path": "lib/l10n/app_{locale}.arb" }
+    // OutputConfig also supports: style, emptyAs ("source"|"empty"|"omit"),
+    // indent, finalNewline, includeLocale, localeCase, localeMap, localeAliases
+  ],
+  "format": { "indent": 2, "sortKeys": true, "finalNewline": true },
+  "autoExport": true,                      // serve re-exports on change (default)
+  "spelling": { "customWords": [] },
+  "lint": { "rules": {}, "ignore": [], "spelling": {} },
+  "scan": { "include": [], "exclude": [], "accessors": [], "patterns": [] }
+}
+```
+`{locale}` in an output `path` is replaced with each locale's export token.
+**Saving Settings from the UI replaces the whole `config` object** — any new `config.*`
+section must be modeled in the round-trip or it is silently wiped.
+## KeyEntry
+```jsonc
+{
+  "context": "Shown on the empty-cart screen",  // helps the AI translate; optional
+  "description": "…",
+  "notes": [{ "id": "…", "text": "…", "at": "ISO-8601" }],
+  "tags": ["checkout"],
+  "maxLength": 40,                               // lint flags overflow
+  "screenshot": "…",                             // path; used by vision providers
+  "skipTranslate": false,
+  "plural": { "arg": "count" },                  // presence => plural message
+  "placeholders": {                              // typed placeholder metadata
+    "count": { "type": "int", "format": "compact", "example": "1,000" }
+  },
+  "suppressions": [ /* dismissed lint findings; expire when source changes */ ],
+  "values": {
+    "en": { "value": "Your cart is empty", "state": "source" },
+    "fr": { "value": "Votre panier est vide", "state": "machine" }
+  }
+}
+```
+### LocaleValue
+A scalar key carries `value`; a **plural** key (one with a `plural` marker) carries
+`forms` instead — one entry per ICU selector:
+```jsonc
+"values": {
+  "en": {
+    "forms": { "one": "{count} item", "other": "{count} items" },
+    "state": "source"
+  }
+}
+```
+`state` is one of:
+- `source` — the source-locale value (the authoritative text).
+- `machine` — AI-translated, not yet reviewed.
+- `needs-review` — flagged for human review (e.g. source changed after translation).
+- `reviewed` — human-approved.
+Plural form selectors are CLDR categories (`zero`, `one`, `two`, `few`, `many`, `other`)
+or exact matches like `=0`/`=1`. Not every locale uses every category; the source
+locale's set defines the message's branches.
+## Glossary
+`glossary` is an array of term entries that constrain how specific words/phrases are
+translated (or kept verbatim). The lint `glossary` rule flags violations. See
+`references/workflows.md` for how to add entries.

package/skill/references/workflows.md ADDED Viewed

@@ -0,0 +1,84 @@
+# glotfile workflows
+Recipes for the common jobs. All of them follow the same loop: **change the state file →
+`glotfile export` → commit both.** Prefer the CLI/UI over hand-editing; edit by hand only
+when no command fits (then match the deterministic format — see `references/schema.md`).
+## Add a new string
+1. Pick a key name that matches the project's existing convention (look at sibling keys —
+   dotted `auth.login.title`, flat, etc.).
+2. Add a `KeyEntry` to `keys` with the source-locale value and `state: "source"`:
+   ```jsonc
+   "cart.empty.title": {
+     "context": "Heading on the empty-cart screen",
+     "values": { "en": { "value": "Your cart is empty", "state": "source" } }
+   }
+   ```
+   Add `context` when the string is ambiguous out of context — it measurably improves
+   translation quality.
+3. `glotfile translate` to fill the other locales (or `--key "cart.*"` to scope it).
+4. `glotfile export` to write the locale files.
+5. Wire the key up in the app code using the project's i18n accessor, then commit.
+For a **plural** message, add a `plural: { "arg": "count" }` marker and use `forms`
+instead of `value` (see `references/schema.md`). Use ICU placeholders like `{count}` and
+keep them identical across locales — the lint placeholder rule enforces this.
+## Edit an existing source string
+1. Change the **source-locale** value in `keys.<name>.values.<sourceLocale>`.
+2. Existing translations are now stale. Re-translate them: `glotfile translate --all
+   --key "<name>"` (or let the user review). Glotfile tracks the source a translation was
+   made from, so stale entries can be flagged `needs-review`.
+3. `glotfile export`, then commit.
+Never edit a translation in an exported file to "fix" it — fix it in the state file
+(`state: "reviewed"` once a human approves) and re-export.
+## Onboard a repo that already has locale files
+1. Identify the existing format and pick the matching adapter (e.g. a Laravel app with
+   `resources/lang/{locale}/` → `laravel-php`; a Flutter app with `app_{locale}.arb` →
+   `flutter-arb`).
+2. `glotfile import --format <adapter> --source <dir> --source-locale <code>` — this reads
+   the existing files and writes a `glotfile.json`. Add `--cldr` if plurals use CLDR
+   forms; `--force` to overwrite an existing state file.
+3. Review the generated `config.outputs` so a subsequent `glotfile export` writes back to
+   the same paths the project already uses.
+4. `glotfile scan` then `glotfile build-context` (optional) to enrich keys with usage
+   context before translating.
+## Populate the glossary
+The glossary constrains how particular terms are translated across the catalog; the lint
+`glossary` rule flags violations. Each entry:
+```jsonc
+{
+  "term": "Glotfile",
+  "doNotTranslate": true,            // keep verbatim in every locale
+  "caseSensitive": true,
+  "notes": "Product name"
+}
+```
+Or pin specific translations:
+```jsonc
+{
+  "term": "cart",
+  "translations": { "fr": "panier", "de": "Warenkorb" },
+  "notes": "Use the e-commerce sense, not 'chariot'"
+}
+```
+Add entries to the top-level `glossary` array. After adding them, `glotfile lint` will
+flag existing translations that don't comply; `glotfile translate --all` re-translates
+with the glossary applied.
+## Improve translation quality with context
+`glotfile scan` (index code references) → `glotfile build-context` (AI writes a short
+`context` per key from how it's used in code) → `glotfile translate`. Keys with good
+`context` translate far more accurately, especially short or ambiguous strings.