@lingo.dev/cli 1.0.0

package/guides/api.md

@@ -0,0 +1,54 @@
+# API Reference – @lingo.dev/react
+
+## Hooks
+- `useLingo()` → returns Lingo with translation + formatting helpers.
+
+## Translation helpers (context required)
+```tsx
+l.text(source, { context, values? })
+l.jsx(source, { context, tags?, values? })
+l.plural(count, { one, other, zero?, two?, few?, many? }, { context })
+l.select(value, { ...forms, other }, { context })
+```
+
+Examples:
+```tsx
+l.text("Save", { context: "Form submit button" })
+l.text("Hello, {name}!", { context: "Dashboard welcome", values: { name } })
+l.jsx("Read <link>docs</link>", { context: "Footer link", tags: { link: c => <a href="/docs">{c}</a> } })
+l.plural(items, { one: "# item", other: "# items" }, { context: "Cart count" })
+l.select(role, { admin: "Admin", user: "User", other: "Guest" }, { context: "Nav label" })
+```
+
+Context rules:
+1) Always required on text/jsx/plural/select.
+2) Describes where/how the string is used ("Checkout CTA", "Toast error").
+3) Same source + different context = different translation key.
+
+## Formatting helpers (no context needed)
+```tsx
+l.num(1234567)            // "1,234,567"
+l.currency(29.99, "USD") // "$29.99"
+l.percent(0.156)         // "16%"
+l.date(new Date())        // locale date
+l.time(new Date())        // locale time
+l.relative(-1, "day")    // "yesterday"
+l.list(["A","B","C"]) // "A, B, and C"
+```
+
+## Components / HOCs (Next.js Pages Router)
+- `withLingoApp(App)` → wraps _app.tsx; sets dir for RTL; warns if page missing withLingoProps.
+- `withLingoProps({ route, handler? })` → load route-specific messages in getStaticProps/SSR.
+- `withLingoPaths(handler)` → expands getStaticPaths across locales (fallback: "blocking").
+- `useLocaleSwitch()` → sets NEXT_LOCALE cookie + router.push with locale.
+- `LingoHead` → hreflang SEO tags.
+
+## Files generated by CLI
+- `locales/<locale>.jsonc` – source/translated messages with @context + @src metadata.
+- `lingo.d.ts` – TypeScript augmentation with exact context unions and required values.
+
+## Required patterns
+- Every page using translations must export withLingoProps({ route }).
+- Every translation call must include context.
+- Always run `npx @lingo.dev/cli check` before finishing.
+```

package/guides/index.md

@@ -0,0 +1,10 @@
+# Lingo Guides
+
+Use `npx @lingo.dev/cli guide <name>` to view a guide.
+
+Available guides:
+- `setup` – first-time setup for @lingo.dev/react (Next.js Pages Router focus, works for React too)
+- `api` – API reference for `l.text`, `l.jsx`, `l.plural`, `l.select`, formatting helpers
+- `migrate` – migrate from next-intl, react-intl, i18next, lingui to @lingo.dev/react
+
+Always finish workflows with `npx @lingo.dev/cli check` (or `pnpm lingo check`) and expect 0 issues.

package/guides/migrate.md

@@ -0,0 +1,34 @@
+# Migration Guide – to @lingo.dev/react
+
+## Key differences
+- No manual keys. Use source text + required context: `l.text("Save", { context: "Form button" })`.
+- Automatic hash keys; per-route splitting via withLingoProps({ route }).
+- TypeScript enforces context and required values after `lingo extract`.
+
+## API mapping
+| Pattern          | next-intl                  | react-intl                      | i18next                   | @lingo.dev/react                                    |
+|------------------|----------------------------|---------------------------------|---------------------------|------------------------------------------------------|
+| Plain text       | `t("key")`               | `formatMessage({ id })`         | `t("key")`              | `l.text("source", { context: "..." })`            |
+| With values      | `t("key", { name })`     | `formatMessage({ id }, { name })`| `t("key", { name })`   | `l.text("Hello, {name}", { context: "...", values: { name } })` |
+| Rich text        | `t.rich("key", { link })`| `<FormattedMessage components>`  | `<Trans components>`     | `l.jsx("Click <link>here</link>", { context: "...", tags: { link } })` |
+| Plurals          | ICU in JSON               | `<FormattedPlural>`             | ICU in JSON              | `l.plural(count, { one: "# item", other: "# items" }, { context: "..." })` |
+| Provider         | `NextIntlProvider`        | `IntlProvider`                  | `I18nextProvider`        | `withLingoApp` (wraps LingoProvider)                 |
+| Hook             | `useTranslations()`       | `useIntl()`                     | `useTranslation()`       | `useLingo()`                                        |
+
+## Steps
+1) Install @lingo.dev/react (and @lingo.dev/react-next for Next.js). Keep old lib temporarily.
+2) Wrap root with withLingoApp (and keep old provider during migration if needed).
+3) Per file:
+   - Replace old hook with `useLingo()`.
+   - Replace calls using mapping above.
+   - Add `withLingoProps({ route })` to every page using translations.
+4) Run `npx @lingo.dev/cli extract`.
+5) Run `npx @lingo.dev/cli localize --target-locale <locale>`.
+6) Run `npx @lingo.dev/cli check` (expect 0 issues).
+7) Remove old provider, message files, and dependencies once all pages migrated.
+
+## Gotchas
+- Old JSON translation files can’t be reused directly (keys differ). Re-translate via `localize`.
+- Keep contexts specific (e.g., "Toolbar Save", "Form Save").
+- Dynamic routes still need withLingoPaths for locale expansion.
+```

package/guides/setup.md

@@ -0,0 +1,111 @@
+# Setup Guide – @lingo.dev/react (Next.js Pages Router)
+
+Philosophy: the agent writes i18n code; context is required on every call; route is required on every page loader. Finish with `npx @lingo.dev/cli check`.
+
+## 1) Install packages
+Detect package manager from lockfile. Example (pnpm):
+```bash
+pnpm add @lingo.dev/react @lingo.dev/react-next
+pnpm add -D @lingo.dev/cli
+```
+
+## 2) Configure Next.js i18n
+`next.config.ts`
+```ts
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  i18n: {
+    locales: ["en", "es"],
+    defaultLocale: "en",
+  },
+};
+
+export default nextConfig;
+```
+
+## 3) Wrap _app.tsx
+```tsx
+// pages/_app.tsx
+import type { AppProps } from "next/app";
+import { withLingoApp, LingoHead } from "@lingo.dev/react-next/pages/client";
+
+export default withLingoApp(function App({ Component, pageProps }: AppProps) {
+  return (
+    <>
+      <LingoHead />
+      <Component {...pageProps} />
+    </>
+  );
+});
+```
+- withLingoApp wires LingoProvider, sets dir for RTL, warns if a page lacks withLingoProps.
+- LingoHead adds hreflang tags.
+
+## 4) Add withLingoProps to every page
+Route = file path without extension (relative to repo root).
+```tsx
+import { withLingoProps } from "@lingo.dev/react-next/pages/server";
+export const getStaticProps = withLingoProps({ route: "src/pages/index" });
+```
+Dynamic routes also add withLingoPaths:
+```tsx
+import { withLingoPaths } from "@lingo.dev/react-next/pages/server";
+export const getStaticPaths = withLingoPaths(async () =>
+  getPosts().then((posts) => posts.map((p) => ({ params: { slug: p.slug } })))
+);
+```
+
+## 5) Wrap strings with useLingo
+```tsx
+import { useLingo } from "@lingo.dev/react";
+
+const l = useLingo();
+<h1>{l.text("Welcome to Acme", { context: "Hero heading" })}</h1>
+<p>{l.text("The best tool for teams.", { context: "Hero subheading" })}</p>
+<button>{l.text("Get started", { context: "Hero CTA" })}</button>
+```
+Context is REQUIRED on l.text/l.jsx/l.plural/l.select.
+
+### API cheatsheet
+- `l.text(source, { context, values? })`
+- `l.jsx(source, { context, tags?, values? })`
+- `l.plural(count, forms, { context })`
+- `l.select(value, forms, { context })`
+- Formatting: `l.num`, `l.currency`, `l.percent`, `l.date`, `l.time`, `l.relative`, `l.list`
+
+## 6) Locale switcher
+```tsx
+import { useLocaleSwitch } from "@lingo.dev/react-next/pages/client";
+import { useRouter } from "next/router";
+
+const switchLocale = useLocaleSwitch();
+const { locale, locales } = useRouter();
+<select value={locale} onChange={(e) => switchLocale(e.target.value)}>
+  {locales?.map((loc) => <option key={loc}>{loc}</option>)}
+</select>
+```
+
+## 7) Extract
+```bash
+npx @lingo.dev/cli extract   # or pnpm lingo extract
+```
+Generates `locales/en.jsonc` + `lingo.d.ts`. After this, TS enforces context + values.
+
+## 8) Translate
+```bash
+npx @lingo.dev/cli localize --target-locale es
+```
+Writes `locales/es.jsonc`.
+
+## 9) Verify
+```bash
+npx @lingo.dev/cli check
+```
+0 issues = done.
+
+## Rules to remember
+- Context required on every translation call.
+- Route required on every withLingoProps.
+- Always finish with `npx @lingo.dev/cli check`.
+```

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@lingo.dev/cli",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "lingo": "./dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "guides"
+  ],
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.76",
+    "@babel/parser": "^7.29.0",
+    "@babel/traverse": "^7.29.0",
+    "@clack/prompts": "^0.11.0",
+    "@effect/cli": "^0.73.0",
+    "@effect/platform": "^0.94.1",
+    "@effect/platform-node": "^0.104.0",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@supabase/supabase-js": "^2.99.1",
+    "cfonts": "^3.3.1",
+    "ci-info": "^4.4.0",
+    "effect": "^3.19.0",
+    "jsonc-parser": "^3.3.1",
+    "log-update": "^7.2.0",
+    "picocolors": "^1.1.1",
+    "posthog-node": "^5.28.2",
+    "semver": "^7.7.4",
+    "zod": "^4.0.0",
+    "@lingo.dev/spec": "1.0.0"
+  },
+  "devDependencies": {
+    "@babel/types": "^7.29.0",
+    "@types/babel__traverse": "^7.28.0",
+    "@types/node": "^25.5.0",
+    "@types/semver": "^7.7.1",
+    "tsdown": "^0.12.5",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.2",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "cli": "node --import tsx/esm src/bin.ts",
+    "dev": "tsdown && node dist/bin.js"
+  }
+}

package/skills/lingo/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: lingo
+description: >
+  Set up, migrate, or maintain internationalization using @lingo.dev/react.
+  Use when the user asks about i18n, localization, translations, multi-language support,
+  adding a new locale, translating strings, or migrating from another i18n library.
+user-invocable: true
+argument-hint: "[add <locale>, migrate from <library>, or blank]"
+---
+
+Run `npx @lingo.dev/cli guide` to read the guides (setup, api, migrate).