claude-translator 1.4.0 → 2.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "conveythis-translator",
+  "version": "2.0.0",
+  "description": "Localize a built static site into dozens of languages as real static pages, by substituting into the built HTML instead of re-rendering — so Core Web Vitals hold. Works with Astro, Next export, Hugo, Eleventy, Jekyll or plain HTML, via Claude, Gemini, any OpenAI-compatible endpoint, or a fully local model.",
+  "author": {
+    "name": "ConveyThis",
+    "url": "https://www.conveythis.com"
+  },
+  "homepage": "https://github.com/ConveyThis/claude-translator",
+  "repository": "https://github.com/ConveyThis/claude-translator",
+  "license": "AGPL-3.0-or-later",
+  "keywords": ["i18n", "l10n", "localization", "translation", "static-site", "hreflang", "seo"]
+}

package/CHANGELOG.md

@@ -5,6 +5,186 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] — 2026-08-30
+
+Answers to a set of questions from a localization professional, who asked what the tool
+does about terminology, brand-name sense, register in tightly-spaced CTAs, locale number
+conventions, and whether there was any TQA evidence at all. Four of those had no answer.
+Now they do — and two README claims that did not survive being checked are corrected.
+
+### Added
+
+- **A glossary.** `glossary` in the config, inline or a path to a JSON file. Two rules:
+  `keep` (leave in the source language, case-sensitive by default) and `translate` with
+  per-locale `targets`. Matching is whole-word, so `Apple` never matches inside
+  `Applesauce`, and `matchCase` is what separates **Apple** the company from **apple** the
+  fruit — a distinction the old flat `doNotTranslate` list could not express.
+
+  Only the terms present in a batch are injected into that batch's prompt, so a large
+  glossary does not inflate every request. `doNotTranslate.brands` is folded in
+  automatically as case-sensitive `keep` rules, so existing configs gain word-boundary
+  matching and verification without being edited.
+
+  Changing a term re-translates **only** the units that contain it, tracked by a
+  fingerprint sidecar at `i18n/tm/{lang}.meta.json`. It is a sidecar rather than a key
+  inside the memory because the memory is documented as a hand-editable `hash -> string`
+  map, and three other scripts iterate it — a `__meta` key would have made every coverage
+  count off by one.
+
+- **Locale conventions for numbers, percentages and currency.** `localeFormat`. The model
+  is still told to leave numbers alone; `Intl` reformats them afterwards, deterministically.
+  `1,234.56` becomes `1.234,56` in German, `$5` becomes `5,00 $US` in French.
+
+  **Currency is formatted, never converted, and there is no option to convert it.** Every
+  monetary amount found is written to `i18n/locale-format.json` for a human to price per
+  market instead. Version numbers, times, IP addresses, ISO dates, phone numbers, fractions
+  and ungrouped numbers are deliberately left untouched — during development a greedy
+  pattern turned `192.168.1.1` into `1.921.681,1`, which is why only unambiguous quantities
+  are matched and why that case is now a test.
+
+- **`tqa.mjs` — MQM translation quality assessment.** Scores a seeded, frequency-stratified
+  sample using the standard MQM typology and severity weights (minor 1, major 5,
+  critical 10). Writes `i18n/tqa/{lang}.json` and a Markdown scorecard.
+
+  The judge defaults to a **different provider than the translator**, because models prefer
+  their own output; when no second key is available it says so in the run and in the
+  report. `--repeat` scores the same sample twice and reports the gap, because a quality
+  number without its variance is marketing. A unit the judge cannot assess is **excluded,
+  not counted as clean** — an early version printed `100.00 / 100` from a sample where
+  every single unit had failed, and it now refuses to report a score at all in that case.
+
+- **Element context for register (`el`).** The model now learns *what* a string is, not
+  only what it says. `extract.mjs` always knew — it walks the DOM with `node.tagName` in
+  hand — and threw it away, so rule 5's "Headings stay headings; button labels stay short"
+  was unenforceable: every string arrived looking like prose.
+
+  A `<button>`, a standalone `<a>`, a heading, a `<label>`, an `alt` attribute and a meta
+  description now each carry a short label, and the prompt gains a CONTEXT block describing
+  **only the roles present in that batch**. Ordinary prose sends no field at all, so a site
+  of nothing but paragraphs produces a byte-identical payload to 1.x.
+
+  Two deliberate restraints. The button guidance does **not** demand the imperative — German
+  UI prefers a verbal noun and French the infinitive, and ordering a literal command
+  everywhere is the exact defect this exists to avoid. And when the same string appears as
+  both a button and a paragraph, the hint is **cleared** rather than guessed: one hash means
+  one translation, and a confident wrong answer is worse than none.
+
+  `kind` is untouched. It looks like the natural place for this, but `build-locales.mjs`
+  switches on it to choose an escaper, and a value like `'block:button'` would fall through
+  to `escHtml` and print literal `&lt;0&gt;` placeholder tokens as visible text on every
+  localized page — with no test to catch it. The element travels in a new field instead.
+
+  **No translation memory is invalidated.** Unit hashes are computed from text alone, and a
+  fixture run proves the hashes are byte-identical before and after the change.
+
+- **Gate 7 — glossary compliance.** Reports terms that were supposed to survive, or to be
+  rendered a particular way, and were not. Reports by default; `--strict` makes it fail the
+  build. It only warns because target languages inflect pinned terms, and
+  `references/quality-review.md` is explicit that over-flagging is worse than no check.
+
+- **Gate 8 — numeric integrity.** Fails the build when the *value* of a number changes
+  between source and translation. A model that ships `$39` where the source said `$49`
+  passes every other gate: identical markup, matching placeholders, plausible length,
+  fluent target language.
+
+### Fixed
+
+- **The README claimed to emit things it only rewrites.** "What you get" promised "a
+  complete `hreflang` set" and "per-locale sitemaps". Neither is generated: the only write
+  into the build directory is one HTML file per page, and every locale-identity rule
+  *replaces an attribute on a tag the template already emits*. The section is now split
+  into what the tool rewrites and what your template must supply — and it explains that
+  the rewrite-only design is what preserves byte-identical markup.
+
+- **`i18nDir` silently did nothing** in `verify.mjs` and `audit-seo.mjs`, which imported
+  `I18N_DIR` and then used hardcoded `i18n/...` paths. Same for `$I18N_ROOT`, which three
+  scripts ignored in favour of `process.cwd()`.
+
+- **The generator tag stamped a stale version** — `1.4.0` while the package said `1.5.0`.
+  It cannot be read from `package.json` (once vendored, the nearest manifest is the user's
+  own application), so CI now asserts the literal matches instead.
+
+- **`init` vendored our own contract tests** into the user's project, where they import a
+  test runner and assert on our internals.
+
+### Changed
+
+- `verify.mjs` runs eight gates, not six.
+- `init` scaffolds a starter `glossary.json`.
+- CI now runs the fixture through build and all eight gates, not just extraction, and
+  checks that the packaged CLI scaffolds every new script.
+
+> **Upgrading:** `init` copies the pipeline into your project, so an existing install
+> keeps running the scripts it already has. Re-run `npx claude-translator init --force` to
+> pick up the new stages. Nothing in this release changes existing translations, and no
+> memory is invalidated unless you add a glossary.
+
+## [1.5.0] — 2026-08-25
+
+### Added
+
+- **The repo is now a Claude Code plugin, not only a skill.** A `.claude-plugin/plugin.json`
+  manifest gives it the name, version, description and licence the plugin directory needs in
+  order to list it. The plugin is named `conveythis-translator`, so the skill is invoked as
+  `/conveythis-translator:translate-site`
+
+- **README section on installing it as a plugin**, covering the community-marketplace install,
+  `claude --plugin-dir` for a local clone, and the `~/.claude/skills/` directory-plugin path
+
+### Changed
+
+- **`SKILL.md` moved from the repo root to `skills/translate-site/SKILL.md`.** This was forced,
+  not cosmetic. The plugin documentation states that a single-skill plugin may keep `SKILL.md` at
+  the plugin root, but on Claude Code 2.1.126 that skill is never discovered — verified against
+  three variants (manifest present, manifest absent, and `"skills": "./"`), all of which loaded
+  no skill at all. The conventional `skills/<name>/SKILL.md` layout loads correctly
+
+- **`references/` moved into `skills/translate-site/references/`, so the skill directory is
+  self-contained.** This keeps both install paths working from one copy: as a plugin, and as a
+  plain personal skill symlinked into `~/.claude/skills/`. The reference links in the skill stay
+  plain relative paths; only `LICENSING.md` and `i18n.config.example.json`, which remain at the
+  repo root, are addressed as `${CLAUDE_PLUGIN_ROOT}/…`
+
+- Contrary to what an earlier draft of this entry claimed, a directory in `~/.claude/skills/`
+  carrying a `.claude-plugin/plugin.json` is **not** auto-loaded as a plugin on 2.1.126 —
+  `claude plugin list` reports nothing installed. The README now documents symlinking the skill
+  directory itself, which is verified to work
+
+- The skill's frontmatter `name` is now `translate-site` rather than `claude-translator`, so the
+  namespaced invocation does not read `/conveythis-translator:claude-translator`
+
+- `package.json` `files` ships `.claude-plugin/` and `skills/` in place of the root `SKILL.md`
+
+### Fixed
+
+- **The Pipeline commands in `SKILL.md` pointed at the wrong directory.** They read
+  `node scripts/extract.mjs`, but `claude-translator init` scaffolds into `scripts/i18n/`
+  (its `--dir` default), as the README has always shown correctly. Every command in that block
+  would have failed with `Cannot find module` for anyone following the skill rather than the
+  README
+
+- **Setup instructions assumed a hand-clone.** The skill hardcoded
+  `~/.claude/skills/claude-translator/bin/claude-translator.mjs`, a path that does not exist for
+  a plugin install. It now leads with `npx claude-translator init` and offers
+  `"${CLAUDE_PLUGIN_ROOT}"/bin/claude-translator.mjs` as the offline fallback, which resolves to
+  wherever the plugin actually landed
+
+### Verified
+
+- `claude plugin validate .` passes with no errors and no warnings on Claude Code 2.1.126.
+  Note that this version rejects both `displayName` and `"skills": ["."]`, which the current
+  plugin reference documents — neither is used here
+- Loaded through `claude --plugin-dir`, the skill is discovered and namespaced correctly. The
+  check used a uniquely renamed copy of the skill, so a same-named skill already installed in
+  `~/.claude/skills/` could not be mistaken for it
+- `${CLAUDE_PLUGIN_ROOT}` resolution and the corrected setup line were confirmed end to end:
+  running the documented command against a throwaway project scaffolds `scripts/i18n/` with all
+  nine scripts, `i18n.config.json`, and the `.gitignore` entries
+- Both install paths were checked against the final layout: the plugin loads through
+  `--plugin-dir`, and the skill directory symlinked into `~/.claude/skills/` is discovered too
+- `npm run check` and `npm test` (39 tests) pass unchanged; `npm pack` ships
+  `.claude-plugin/plugin.json`, the skill and its references
+
 ## [1.4.0] — 2026-08-25
 
 ### Changed

package/PRIVACY.md

@@ -0,0 +1,71 @@
+# Privacy
+
+Short version: this tool runs on your machine, and it sends us nothing.
+
+The canonical policy is the **Open-Source and Downloadable Software** section of the
+[ConveyThis Privacy Policy](https://www.conveythis.com/legal/privacy-policy#open-source-and-downloadable-software).
+This file is the code-adjacent summary, and it is meant to be checkable against the source.
+
+## What it sends, and where
+
+There is exactly **one** outbound network call in this repository. It lives in
+[`scripts/translate.mjs`](scripts/translate.mjs), and its URL comes from whichever provider
+adapter you selected in `i18n.config.json`:
+
+| Provider | Endpoint | Key it reads |
+| --- | --- | --- |
+| `anthropic` (default) | `https://api.anthropic.com/v1` | `ANTHROPIC_API_KEY` |
+| `gemini` | `https://generativelanguage.googleapis.com/v1beta/models` | `GEMINI_API_KEY` / `GOOGLE_API_KEY` |
+| `openai` | `https://api.openai.com/v1`, or whatever you set as `apiBaseUrl` | `OPENAI_API_KEY` / `OPENAI_COMPATIBLE_API_KEY` |
+
+Only `translate.mjs` makes any request at all. `extract`, `review`, `build-locales`, `verify`
+and `audit-seo` are entirely offline — they read and write files on your disk and nothing else.
+
+Verify it yourself:
+
+```bash
+grep -rn "fetch(" scripts bin        # one hit, in translate.mjs
+```
+
+## What it never sends
+
+- **Nothing goes to ConveyThis.** No analytics, no usage reporting, no error reporting, no
+  licence check. We do not know you installed this, ran it, or what you translated.
+- **Your API key goes only to the provider it belongs to.** It is read from the environment or a
+  gitignored `.env`, used as that provider's auth header, and never written to output.
+- **Your content goes only to the provider you chose.** Translating means sending your page text
+  to a model, which is inherent to the task — but it goes there directly from your machine.
+
+## Running with zero network egress
+
+Set the `openai` provider against a local endpoint and nothing leaves the machine:
+
+```json
+{ "provider": "openai", "apiBaseUrl": "http://localhost:11434/v1", "model": "qwen2.5:14b" }
+```
+
+Ollama, LM Studio and vLLM all work this way. No key, no quota, no third party. Use this if the
+content is confidential.
+
+## The attribution tag
+
+Generated pages carry a `<meta name="generator">` tag and an HTML comment naming ConveyThis,
+written by [`scripts/credit.mjs`](scripts/credit.mjs). Both are **static markup**: they make no
+request, load no script, set no cookie, and report nothing to us when someone views your page.
+The `conveythis.com` and `doctranslator.com` strings in that file are written into HTML — they
+are never fetched.
+
+To remove them, set `credit.generatorTag` and `credit.htmlComment` to `false` in
+`i18n.config.json`.
+
+## Your translation memory
+
+`i18n/tm/{lang}.json` holds your source and translated copy, and is meant to be committed —
+losing it means paying to re-translate. Check that this suits your repository's visibility
+before committing it to a public repo.
+
+## Elsewhere
+
+Opening issues or pull requests on GitHub, or installing from npm, is governed by those
+platforms' own privacy policies. Security reports go to **security@conveythis.com** — see
+[SECURITY.md](SECURITY.md).