@walkinissue/angy 0.2.17 → 0.2.19

package/README.md

@@ -1,6 +1,8 @@
 # Angy
 
-Dev-only SvelteKit translation helper for in-app PO workflow.
+Dev-only SvelteKit translation helper for in-app PO workflows.
+
+<video src="./docs/images/Backdrop_And_Caching.webm" controls muted playsinline width="100%"></video>
 
 ## Install
 
@@ -8,69 +10,36 @@ Dev-only SvelteKit translation helper for in-app PO workflow.
 npm install @walkinissue/angy
 ```
 
-## What it is
-
-- A QA widget for in-app translation work
-- A PO catalog lookup and commit layer
-- A suggestion pipeline for untranslated strings
-- A SvelteKit-friendly integration shape
-
-## Packages used
-
-- `svelte`
-  UI for the helper widget
-- `@sveltejs/kit`
-  Route handler shape and dev/server integration
-- `wuchale`
-  Runtime i18n layer and locale switching
-- `gettext-parser`
-  Read and write `.po` catalogs
-- `fuse.js`
-  Fuzzy lookup for key discovery
-- `esbuild`
-  Load `angy.config.ts` in dev and server contexts
-- OpenAI API
-  Optional translation suggestions
-
-## What problem it solves
-
-- Large apps are painful to internationalize late
-- Many strings have weak or missing context
-- Repeated copy appears in many components
-- PO workflows are slow when you must search manually
-- Existing i18n libraries solve extraction/runtime, not translator workflow
-- Teams need a way to select text in the app, inspect context, and commit safely
-
-## Why it exists
-
-- Plain catalog editing was too slow
-- Context from extraction alone was not enough
-- Similar strings caused ambiguity
-- Repeated strings needed reference-aware lookup
-- Suggestion workflows needed to stay inside the app
-- A dev-only helper reduced friction enough to keep the migration moving
-
-## Workflow
-
-- Developer runs app in dev
-- Developer mounts `<Angy />` in layout
-- App exports `POST` from the package handler
-- User selects text or uses the helper trigger in the UI
-- Client asks server for PO context and alternatives
-- Server matches best key, expands related entries, and returns alternatives
-- User edits, stages, tabs through unresolved strings, and commits
-- Suggestions can be requested for untranslated strings
-- Commits are written to the working catalog
+## What it does
+
+- select copy directly in the app
+- resolve the best PO key with nearby alternatives
+- stage and commit translations without leaving the page
+- request AI suggestions for untranslated strings
+- rotate locales for visual QA
+
+## Quick flow
+
+1. Select text or `Alt`+click an interactive element.
+2. Review the matched key and alternatives.
+3. Edit or accept a suggestion.
+4. Stage and commit.
+5. Rotate locales and verify the page visually.
+
+## Docs site
+
+- [Showcase and docs](https://walkingissue.github.io/Angy/)
+- [Release notes](./docs/changelog/0.2.19.md)
 
 ## Integration
 
-Use the plugin for shared config, then mount the component and define the route yourself.
+Use the plugin for dev glue, mount the component, and expose the server handler.
 
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite";
 import { sveltekit } from "@sveltejs/kit/vite";
-import { angy } from "@walkingissue/angy/plugin";
+import { angy } from "@walkinissue/angy/plugin";
 
 export default defineConfig({
 	plugins: [angy(), sveltekit()]
@@ -79,7 +48,7 @@ export default defineConfig({
 
 ```ts
 // angy.config.ts
-import { defineAngyConfig } from "@walkingissue/angy/server";
+import { defineAngyConfig } from "@walkinissue/angy/server";
 
 export default defineAngyConfig({
 	basePoPath: "./src/locales/en.po",
@@ -88,7 +57,7 @@ export default defineAngyConfig({
 	targetLocale: "en",
 	routePath: "/api/translations",
 	apiKey: "",
-	watchIgnore: ["**/locales/en-working.po"]
+	suggestionModel: { model: "gpt-4.1-mini" }
 });
 ```
 
@@ -96,151 +65,65 @@ export default defineAngyConfig({
 <!-- src/routes/+layout.svelte -->
 <script lang="ts">
 	import { dev } from "$app/environment";
-	import { Angy } from "@walkingissue/angy";
+	import { Angy } from "@walkinissue/angy";
+
+	let { children } = $props();
 </script>
 
 {#if dev}
 	<Angy />
 {/if}
 
-<slot />
+{@render children?.()}
 ```
 
 ```ts
 // src/routes/api/translations/+server.ts
-export { handler as POST } from "@walkingissue/angy/server";
+export { handler as POST } from "@walkinissue/angy/server";
 ```
 
 ## Catalog model
 
-- `en.po` is the base catalog
-- `en-working.po` is the mutable working catalog
-- Base catalog is the source of truth for valid keys
-- Working catalog is the source of truth for current translation state
-- Lookup reads working state first
-- Commit validates against base, then writes to working
-
-## Discovery algorithm
-
-- User sends selected text and current route path
-- Server creates lookup variants from the selected text
-- Fuzzy search runs against the effective working view of the catalog
-- Best match must clear a score threshold
-- Top 4 similar direct matches are kept
-- Server infers a page reference like `src/routes/.../+page.svelte`
-- It then pulls entries that share PO references with the best match
-- It then pulls entries whose references look similar to the current route
-- If space remains, it fills with similar unresolved strings
-- It also keeps a smaller translated slice for cohesion
-
-## Why the lookup works like this
-
-- Direct fuzzy match alone is not enough
-- Repeated UI copy often exists in several components
-- Shared PO references are strong local context
-- Route similarity helps reconstruct page-level context
-- A translated slice helps keep wording consistent
-- An untranslated-heavy pool focuses effort where work remains
-
-## Retrieval targets
-
-- Up to 300 alternatives
-- Roughly 80% untranslated
-- Roughly 20% already translated
-- Enough translated context for tone and syntax
-- Enough untranslated context for efficient batch work
-
-## Suggestions
-
-- Suggestions are dev-only
-- Server-side request to OpenAI
-- Prompt aims to preserve placeholders, markup, casing, and product terminology
-- Existing translations are used as style anchors
-- Suggestions are cached client-side to avoid repeat requests
-- Built-in suggestions are disabled when `apiKey` is empty
-- Consumers can replace the suggestion pipeline with `suggestionProvider`
+- `en.po` is base
+- `en-working.po` is runtime working state
+- `en-working.angy-draft.po` is the draft write target
+- commits write to draft first
+- entering `*-working` preview promotes draft into runtime working
 
 ## Config
 
-| Key | Required | Default | Notes |
-| --- | --- | --- | --- |
-| `basePoPath` | Yes | None | Path to base catalog |
-| `workingPoPath` | Yes | None | Path to working catalog |
-| `sourceLocale` | Yes | None | Source language for suggestions. Can be set to `"base"` to infer from `basePoPath` |
-| `targetLocale` | Yes | None | Target language for suggestions. Can be set to `"working"` to infer from `workingPoPath` |
-| `routePath` | No | `/api/translations` | Route used by the helper client and consumer server handler |
-| `apiKey` | Yes | None | Used by built-in suggestion pipeline. If empty, suggestions are disabled |
-| `systemMessage` | No | Built from locales | Default AI system prompt |
-| `suggestionModel` | No | `gpt-4.1-mini` | Cheap default to avoid cost surprises |
-| `watchIgnore` | No | `["**/en-working.po"]` | Extra Vite watch ignore patterns |
-| `suggestionProvider` | No | None | Custom suggestion pipeline hook |
-
-## Route config
-
-- The server route path is defined by the consumer app
-- The default route path is `/api/translations`
-- `routePath` lives in `angy.config.ts`
-- The `Angy` `endpoint` prop is optional
-- Use the prop only if you want to override `routePath` per instance
-
-## Custom suggestion provider
-
-Use `suggestionProvider` if you want your own AI pipeline.
-
-Input:
-
-- `context`
-- `items`
-- `sourceLocale`
-- `targetLocale`
-- `systemMessage`
-- `model`
-- `apiKey`
-
-Return:
-
-- `Array<{ msgid: string; msgctxt: string | null; suggestion: string }>`
-
-Example:
-
-```ts
-import { defineAngyConfig, type SuggestionProvider } from "@walkingissue/angy/server";
-
-const suggestionProvider: SuggestionProvider = async ({ items }) => {
-	return items.map((item) => ({
-		msgid: item.msgid,
-		msgctxt: item.msgctxt,
-		suggestion: `TODO: ${item.msgid}`
-	}));
-};
-
-export default defineAngyConfig({
-	basePoPath: "./src/locales/en.po",
-	workingPoPath: "./src/locales/en-working.po",
-	sourceLocale: "sv",
-	targetLocale: "en",
-	routePath: "/api/translations",
-	apiKey: "",
-	suggestionProvider
-});
-```
-
-## Exports
-
-- `Angy` from `@walkingissue/angy`
-- `handler` and `defineAngyConfig` from `@walkingissue/angy/server`
-- `angy` from `@walkingissue/angy/plugin`
-
-## Notes
-
-- The default `handler` returns a `404` outside dev.
-- The package still has fallback internal paths, but consumers should define their own explicit catalog paths.
-- Override paths, locales, `routePath`, `apiKey`, `systemMessage`, `suggestionModel`, `watchIgnore`, and `suggestionProvider` through `angy.config.ts`.
-- The default export surface is intentionally small: plugin, component, config helper, and server handler.
-
-## Future work
-
-- Handle server paths for single config and single app
-- Support multiple catalogs
-- Support multiple translations from a single source locale
-- This seems trivially implemented with the current setup
+| Key | Required | Notes |
+| --- | --- | --- |
+| `basePoPath` | Yes | Base catalog path |
+| `workingPoPath` | Yes | Working catalog path |
+| `sourceLocale` | Yes | Source language for suggestions |
+| `targetLocale` | Yes | Target language for suggestions |
+| `routePath` | No | Defaults to `/api/translations` |
+| `apiKey` | No | Empty string disables built-in suggestions |
+| `systemMessage` | No | Custom suggestion prompt |
+| `suggestionModel` | No | Object config, defaults to `{ model: "gpt-4.1-mini" }` |
+| `watchIgnore` | No | Extra Vite watch ignore patterns |
+| `suggestionProvider` | No | Custom suggestion pipeline |
+
+Reasoning is validated per model. Non-reasoning models like `gpt-4.1-mini` do not accept it.
+
+## Frequent issues
+
+- Locale changes in Angy, but the page does not rerender
+  - Wuchale usually is not fully bootstrapped in the host app.
+- `*-working` is visible, but commit is disabled
+  - Working locale is preview-only by design.
+- Rotation shows a warning modal
+  - That is a preview of what rotation will promote into base.
+- Angy refuses to operate with a catalog integrity error
+  - Regenerate or replace the working catalog.
+
+## Docs
+
+- [Release notes](./docs/changelog/0.2.19.md)
+- [Roadmap](./docs/roadmap.md)
+- [Wuchale runtime wiring](./docs/wuchale-runtime.md)
+
+## License
+
+MIT