### Install and Run Vite + React Example

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/examples/vite-react/README.md

Install dependencies and start the development server for the Vite + React example. This command is used to run the end-to-end demo.

```bash
pnpm install
pnpm --filter @autotranslate/example-vite-react dev
```

--------------------------------

### Project Setup and Build

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/CONTRIBUTING.md

Clone the repository, install dependencies, and build the project.

```bash
git clone https://github.com/tamimbinhakim/autotranslate.git
cd autotranslate
pnpm install
pnpm build
```

--------------------------------

### Run Next.js App Example

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/README.md

Use this command to run the Next.js application example. Ensure you have pnpm installed.

```bash
pnpm --filter @autotranslate/example-next-app dev
```

--------------------------------

### Run Vite React App Example

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/README.md

Use this command to run the Vite + React SPA example. Ensure you have pnpm installed.

```bash
pnpm --filter @autotranslate/example-vite-react dev
```

--------------------------------

### Install and Run Next.js App

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/examples/next-app/README.md

Install dependencies and start the Next.js development server. Access the application at http://localhost:3000, where paths under /<locale>/... will resolve to the corresponding catalog.

```bash
pnpm install
pnpm --filter @autotranslate/example-next-app dev
```

--------------------------------

### Install AI Provider Peer Dependencies

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/guides/providers.md

When using the 'ai' provider, you need to install the core 'ai' package along with the specific vendor's SDK. This example shows how to install the Anthropic SDK.

```bash
pnpm add ai @ai-sdk/anthropic
```

--------------------------------

### Running Examples

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/CONTRIBUTING.md

Commands to develop specific examples using pnpm filters.

```bash
pnpm --filter @autotranslate/example-next-app dev
pnpm --filter @autotranslate/example-vite-react dev
```

--------------------------------

### Install @autotranslate/react

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/react/README.md

Install the React adapter and core package using pnpm.

```bash
pnpm add @autotranslate/react @autotranslate/core
```

--------------------------------

### Install @autotranslate/providers

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/providers/README.md

Install the autotranslate providers package using pnpm.

```bash
pnpm add @autotranslate/providers
```

--------------------------------

### Install and initialize autotranslate

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/next-intl.md

Commands to remove next-intl and install the necessary autotranslate packages, followed by initialization.

```bash
pnpm remove next-intl
pnpm add @autotranslate/react @autotranslate/core @autotranslate/next
pnpm add -D @autotranslate/cli
npx autotranslate init
```

--------------------------------

### Install @autotranslate/typescript-plugin

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/typescript-plugin/README.md

Install the plugin as a development dependency using pnpm.

```bash
pnpm add -D @autotranslate/typescript-plugin
```

--------------------------------

### Install and Run CLI Commands

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/cli/README.md

Install the CLI as a dev dependency and run the main commands for initialization, extraction, translation, and checking.

```bash
pnpm add -D @autotranslate/cli
npx autotranslate init
npx autotranslate extract
npx autotranslate translate
npx autotranslate check
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/CONTRIBUTING.md

Examples of commit messages for different types and scopes.

```markdown
feat(react): add useT hook with ICU param inference
fix(cli): handle missing autotranslate.config.ts
docs: clarify provider auth flow
```

--------------------------------

### Install AI provider SDK

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/quick-start.md

Install the SDK for the chosen AI provider and set the API key as an environment variable.

```bash
export ANTHROPIC_API_KEY=sk-ant-…
pnpm add ai @ai-sdk/anthropic
```

--------------------------------

### Install Core AutoTranslate Packages

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/installation.md

Install the core runtime packages for React and the CLI for development use.

```bash
pnpm add @autotranslate/react @autotranslate/core
pnpm add -D @autotranslate/cli
```

--------------------------------

### Install Dependencies for Remix

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/frameworks/remix.md

Install the necessary @autotranslate packages for Remix projects.

```bash
pnpm add @autotranslate/react @autotranslate/core
pnpm add -D @autotranslate/cli
```

```bash
pnpm add @autotranslate/zod
```

--------------------------------

### Install AI Provider SDK and Set API Key

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/gt-next.md

Installs the AI SDK for the chosen provider (Anthropic in this case) and sets the necessary API key as an environment variable.

```bash
pnpm add ai @ai-sdk/anthropic
export ANTHROPIC_API_KEY=...
```

--------------------------------

### Install Vite Adapter

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/installation.md

Install the AutoTranslate adapter for Vite, suitable for SPAs, SSR via Vike, and Astro projects.

```bash
pnpm add -D @autotranslate/vite
```

--------------------------------

### Install Autotranslate ESLint Plugin

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/guides/linting.md

Install the ESLint plugin as a development dependency using pnpm.

```bash
pnpm add -D @autotranslate/eslint-plugin
```

--------------------------------

### Install Autotranslate Packages for Next.js

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/frameworks/nextjs.md

Install the necessary Autotranslate packages for Next.js integration.

```bash
pnpm add @autotranslate/next @autotranslate/react @autotranslate/core
```

--------------------------------

### Install AI Provider Dependencies

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/installation.md

Install the 'ai' package and specific AI provider SDKs like Anthropic for lazy-loading vendor SDKs.

```bash
pnpm add @ai-sdk/anthropic   # plus `ai` is required
pnpm add ai
```

--------------------------------

### Install Autotranslate Beta

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/README.md

Install the beta version of autotranslate core. This command adds the beta package to your project dependencies.

```bash
pnpm add @autotranslate/core@beta
```

--------------------------------

### React Native: Per-feature catalog partitioning (build config)

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/cookbook/lazy-loading.md

When catalog size is a concern in React Native, consider partitioning catalogs by feature. This example shows a basic Vite `defineConfig` setup, implying a custom build script would then partition the output into feature-specific JSON files.

```typescript
defineConfig({
  // single config for the app
  content: ['src/**/*.{ts,tsx}'],
  outDir: '.translations',
});
```

--------------------------------

### Install Autotranslate Packages

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/README.md

Install the necessary autotranslate packages for React and core functionality, along with the CLI for development.

```bash
pnpm add @autotranslate/react @autotranslate/core
pnpm add -D @autotranslate/cli
npx autotranslate init
```

--------------------------------

### Re-translate Content in Vite + React Example

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/examples/vite-react/README.md

Execute the command to re-translate content for the Vite + React example. This is useful for updating translation files.

```bash
pnpm --filter @autotranslate/example-vite-react i18n
```

--------------------------------

### Install Autotranslate Dependencies

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/lingui.md

Removes Lingui packages and installs Autotranslate core and CLI packages. Also initializes Autotranslate.

```bash
pnpm remove @lingui/react @lingui/core @lingui/cli @lingui/macro \
  babel-plugin-macros @lingui/babel-plugin-extract-messages
pnpm add @autotranslate/react @autotranslate/core
pnpm add -D @autotranslate/cli
npx autotranslate init
```

--------------------------------

### Install autotranslate packages

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/gt-next.md

This command removes gt-next packages and installs the necessary autotranslate packages, including the CLI.

```bash
pnpm remove gt-next gt-react @generaltranslation/runtime
pnpm add @autotranslate/react @autotranslate/core @autotranslate/next
pnpm add -D @autotranslate/cli
npx autotranslate init
```

--------------------------------

### Generated Translation File Example

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/README.md

This is an example of a generated translation file, listing the locales and their corresponding JSON files.

```text
.translations/es.json, fr.json, ja.json …
```

--------------------------------

### Install Optional AutoTranslate Packages

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/installation.md

Install optional packages for Zod validation error translation and ESLint plugin for catching untranslated JSX and dynamic keys.

```bash
pnpm add @autotranslate/zod
pnpm add -D @autotranslate/eslint-plugin
```

--------------------------------

### Server-Component Translation Example

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/next/README.md

Translate content directly within server components using the getT helper. This example demonstrates fetching translations for a given locale.

```tsx
// app/[lang]/page.tsx
import { getT } from '@autotranslate/next';

export default async function Page({ params }: PageProps<'/[lang]'>) {
  const { lang } = await params;
  const t = await getT(lang, { fallback: 'en' });
  return <h1>{t.t('Welcome')}</h1>;
}
```

--------------------------------

### Clean Up Lingui Setup

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/lingui.md

Removes Lingui-specific directories and configuration files, and updates Babel/SWC configuration.

```bash
rm -rf locales/
rm lingui.config.js
# remove babel-plugin-macros / lingui plugin from babel/swc config
```

--------------------------------

### Add @autotranslate/core Package

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/core/README.md

Install the core package using pnpm.

```bash
pnpm add @autotranslate/core
```

--------------------------------

### Install Next.js Adapter

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/installation.md

Add the AutoTranslate adapter for Next.js applications, supporting App Router, Pages Router, RSC, and Edge.

```bash
pnpm add @autotranslate/next
```

--------------------------------

### Install autotranslate Dependencies

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/react-i18next.md

Commands to remove react-i18next related packages and install autotranslate core, react, and CLI packages.

```bash
pnpm remove react-i18next i18next i18next-http-backend i18next-browser-languagedetector
pnpm add @autotranslate/react @autotranslate/core
pnpm add -D @autotranslate/cli
npx autotranslate init
```

--------------------------------

### Install Autotranslate Zod Package

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/integrations/zod.md

Install the @autotranslate/zod package using pnpm. This package is compatible with Zod v4.

```bash
pnpm add @autotranslate/zod
```

--------------------------------

### Run Development Workflow

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/README.md

Commands to set up and run the development environment for the autotranslate monorepo. Includes installation, running tests, type checking, and linting.

```bash
pnpm install
pnpm dev         # turbo run dev across all packages
pnpm test        # vitest across the monorepo
pnpm typecheck   # composite tsc
pnpm lint        # biome check
```

--------------------------------

### Vite Plugin Setup

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/reference/api.md

Configure the Vite build process with the `autotranslate` plugin. Options include specifying the current working directory, output directory, supported locales, source files, and configuration.

```typescript
function autotranslate(options?: AutotranslatePluginOptions): Plugin;

interface AutotranslatePluginOptions {
  readonly cwd?: string;
  readonly outDir?: string;
  readonly locales?: ReadonlyArray<string>;
  readonly source?: string;
  readonly config?: AutotranslateConfig;
}
```

--------------------------------

### Add @autotranslate/ab

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/experiments/README.md

Install the package using pnpm.

```bash
pnpm add @autotranslate/ab
```

--------------------------------

### Configure provider instructions for tone and terms

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/cookbook/overrides-and-glossary.md

Set provider instructions in the configuration to guide the AI on brand voice, glossary terms, and translation rules. Changing instructions invalidates the cache.

```typescript
provider: {
  name: 'ai',
  model: 'anthropic:claude-haiku-4-5',
  apiKey: process.env.ANTHROPIC_API_KEY,
},
instruction: `
  Brand: autotranslate. Never translate or transliterate the brand name.
  Voice: friendly, modern, direct. Keep sentences short.
  Glossary: "API", "SDK", "CLI" stay in English. "monorepo" stays.
`,
```

--------------------------------

### Configure autotranslate Project

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/cli/src/agents.md

Example configuration file for autotranslate, specifying source and target locales, content paths, and translation provider details.

```typescript
import { defineConfig } from '@autotranslate/core/config';

export default defineConfig({
  source: 'en',
  targets: ['es', 'fr', 'ja'],
  content: ['src/**/*.{ts,tsx}'],
  provider: {
    name: 'ai',
    model: 'anthropic:haiku-4-5',
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
});
```

--------------------------------

### TypeScript Configuration for Type Generation

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/reference/cli.md

Example of how to include the generated types file in your tsconfig.json.

```jsonc
{
  "include": ["src", ".translations/types.d.ts"],
}
```

--------------------------------

### Select a Provider in autotranslate.config.ts

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/guides/providers.md

Configure the desired provider and its specific options in your autotranslate.config.ts file. This example shows how to set up the 'ai' provider with a specific model and API key.

```typescript
provider: {
  name: 'ai',
  model: 'anthropic:claude-haiku-4-5',
  apiKey: process.env.ANTHROPIC_API_KEY,
}
```

--------------------------------

### Example JSX with Translation Placeholder

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/README.md

This JSX snippet demonstrates how to use the `<T>` component to wrap translatable strings, with `<Var>` for dynamic content.

```tsx
<T>
  Welcome, <Var>{user.name}</Var>!
</T>
```

--------------------------------

### Create a Hybrid Translation Provider

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/cookbook/custom-provider.md

Combine different translation services based on content type. This example uses an AI provider for structured text and DeepL for plain strings, optimizing cost and quality.

```typescript
import { isStructured } from '@autotranslate/core';
import { defineProvider } from '@autotranslate/providers';
import { createAIProvider } from '@autotranslate/providers/ai';
import { createDeepLProvider } from '@autotranslate/providers/deepl';

const ai = createAIProvider({ model: 'anthropic:claude-haiku-4-5' });
const deepl = createDeepLProvider({ apiKey: process.env.DEEPL_API_KEY! });

export const hybrid = defineProvider({
  name: 'hybrid',
  signature: `hybrid:${ai.signature}+${deepl.signature}`,
  async translate(request) {
    const structured = request.items.filter((i) => isStructured(i.source));
    const plain = request.items.filter((i) => !isStructured(i.source));
    const [a, b] = await Promise.all([
      ai.translate({ ...request, items: structured }),
      deepl.translate({ ...request, items: plain }),
    ]);
    return { translations: { ...a.translations, ...b.translations } };
  },
});
```

--------------------------------

### Configure Next.js Proxy

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/next/README.md

Set up the proxy file (formerly middleware.ts) to handle locale detection and redirection. This example configures default locale and supported locales.

```typescript
// proxy.ts (was middleware.ts in Next 15)
import { createNextMiddleware } from '@autotranslate/next/middleware';

export default createNextMiddleware({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
});

export const config = {
  matcher: ['/((?!api|_next|.*\..*).*)'],
};
```

--------------------------------

### Configure AI Provider Instruction

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/reference/configuration.md

Provide a free-form system instruction for AI providers to guide tone, audience, and brand voice. Preserve product names verbatim.

```typescript
instruction: 'Translate UI copy for a developer-tools product. Match a friendly, modern voice. Preserve product names verbatim.'
```

--------------------------------

### Delete Old i18n Setup

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/react-i18next.md

Commands to remove the old `public/locales` directory and the `i18n.ts` (or equivalent) bootstrap file after migrating to autotranslate.

```bash
rm -rf public/locales/
rm src/i18n.ts   # or wherever i18next was bootstrapped
```

--------------------------------

### Migrate translations to overrides configuration

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/next-intl.md

Example showing how to convert a next-intl JSON message file into the `overrides` format in autotranslate's configuration.

```typescript
// before: messages/fr.json
{ "Cart": { "checkout": "Passer la commande" } }
// where en.json had: { "Cart": { "checkout": "Check out" } }

// after: autotranslate.config.ts
overrides: {
  fr: {
    'Check out': 'Passer la commande',
  },
}
```

--------------------------------

### Next.js Server-Side Rendering with autotranslate

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/react-i18next.md

This example demonstrates the simplified server-side rendering flow in Next.js using autotranslate's `getT` function. It replaces the need for `i18next-http-backend` and custom `serverSideTranslations` helpers.

```tsx
import { getT } from '@autotranslate/next';

export default async function Page({
  params,
}: { 
  params: Promise<{ lang: string }>;
}) {
  const { lang } = await params;
  const t = await getT(lang);
  return <h1>{t.t('Welcome')}</h1>;
}
```

--------------------------------

### Define a Minimal Custom Translation Provider

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/cookbook/custom-provider.md

Implement a basic translation provider by defining its name, signature, and an async translate function. This example uses `fetch` to call an external translation service.

```typescript
import { defineProvider } from '@autotranslate/providers';

export const myProvider = defineProvider({
  name: 'my-service',
  signature: 'my-service:v1',
  async translate({ source, target, items, instruction, signal }) {
    const response = await fetch('https://my-service.example.com/translate', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ source, target, items, instruction }),
      signal,
    });
    if (!response.ok) {
      throw new Error(`my-service responded ${response.status}`);
    }
    const json = (await response.json()) as {
      translations: Record<string, string>;
    };
    return { translations: json.translations };
  },
});
```

--------------------------------

### Create Hybrid Translation Provider Configuration

Source: https://context7.com/tamimbinhakim/autotranslate/llms.txt

Routes structured/complex messages to an AI provider and plain text strings to a more economical provider like DeepL. This configuration example shows how to set up both AI and plain text providers.

```typescript
import { createHybridProvider } from '@autotranslate/providers/hybrid';
import { createAIProvider } from '@autotranslate/providers/ai';
import { createDeepLProvider } from '@autotranslate/providers/deepl';

// autotranslate.config.ts
export default defineConfig({
  source: 'en',
  targets: ['es', 'fr', 'de'],
  content: ['src/**/*.tsx'],
  provider: {
    name: 'hybrid',
    ai: {
      name: 'ai',
      model: 'openai:gpt-4o-mini',
      apiKey: process.env.OPENAI_API_KEY,
    },
    plain: {
      name: 'deepl',
      apiKey: process.env.DEEPL_API_KEY,
    },
  },});
```

--------------------------------

### Convert JSON Translations to autotranslate Overrides

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/react-i18next.md

Example showing how to convert existing JSON translation catalogs into the `overrides` format for autotranslate configuration. The original JSON keys become the source-locale string.

```typescript
// before: public/locales/fr/translation.json
{
  "hello": {
    "world": "Bonjour"
  }
}
// and the source code: t('hello.world') with English fallback "Hello"

// after: autotranslate.config.ts
overrides: {
  fr: {
    'Hello': 'Bonjour',
  },
}
```

--------------------------------

### React Component with Translation Hooks

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/ARCHITECTURE.md

Example of using `T` and `useT` from `@autotranslate/react` to display translated strings and capture dynamic content. Ensure `@autotranslate/react` is installed and configured.

```tsx
import { T, useT, Var } from '@autotranslate/react';

export function Welcome({ name }: { name: string }) {
  const t = useT();
  return (
    <>
      <T>
        Hello, <Var>{name}</Var>!
      </T>
      <button>{t('Sign out')}</button>
    </>
  );
}
```

--------------------------------

### Edge Runtime GET Handler

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/frameworks/nextjs.md

Supply a custom loader for the Edge runtime, as the default `fs` loader uses `node:fs/promises` and is incompatible. This example demonstrates loading catalogs directly.

```typescript
// app/api/welcome/route.ts
import { getT } from '@autotranslate/next';
import en from '@/catalogs/en.json' with { type: 'json' };
import es from '@/catalogs/es.json' with { type: 'json' };

const catalogs = { en, es } as const;

export const runtime = 'edge';

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ lang: 'en' | 'es' }> },
) {
  const { lang } = await params;
  const t = await getT(lang, {
    load: (locale) => catalogs[locale as keyof typeof catalogs] ?? {},
  });
  return new Response(t.t('Welcome'));
}
```

--------------------------------

### Example Translation Key

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/zod/README.md

An example of how a Zod error key might be translated in your catalog.

```json
{
  "zod.too_small.array": "{minimum, plural, =1 {Pick at least one} other {Pick at least #}}"
}
```

--------------------------------

### Initialize AutoTranslate Configuration

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/installation.md

Run the initialization command to create the 'autotranslate.config.ts' file in your project root.

```bash
npx autotranslate init
```

--------------------------------

### Configure ESLint (Legacy .eslintrc)

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/guides/linting.md

Configure ESLint using the legacy .eslintrc file by adding the plugin and extending the recommended legacy configuration.

```jsonc
{
  "plugins": ["@autotranslate"],
  "extends": ["plugin:@autotranslate/recommended-legacy"],
}
```

--------------------------------

### Basic CLI Usage

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/reference/cli.md

The general syntax for using the autotranslate CLI. It auto-discovers configuration files.

```bash
npx autotranslate <command> [flags]
```

--------------------------------

### Middleware import comparison

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/next-intl.md

Demonstrates the different import paths for the middleware creation function in next-intl and autotranslate.

```typescript
// Locale routing
import createMiddleware from 'next-intl/middleware'; // next-intl
import { createNextMiddleware } from '@autotranslate/next/middleware'; // autotranslate
//   ↑ same API shape — same `prefix` / `cookie` strategies
```

--------------------------------

### Development Workflow for Packages

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/CONTRIBUTING.md

Commands to watch for changes and test individual packages within the monorepo.

```bash
pnpm dev                                # watch every package
pnpm --filter @autotranslate/core dev   # watch one
pnpm --filter @autotranslate/core test  # test one
```

--------------------------------

### Configure ESLint for Autotranslate

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/cli/src/agents.md

Configure your ESLint setup to include Autotranslate's recommended rules.

```javascript
// eslint.config.js
import autotranslate from '@autotranslate/eslint-plugin';
export default [autotranslate.configs.recommended];
```

--------------------------------

### Configure Global Brand Instructions

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/cookbook/branded-glossary.md

Set system-prompt-level instructions for global brand rules, including brand name handling, voice, and glossary terms. Changes to this instruction invalidate the provider cache.

```typescript
// autotranslate.config.ts
export default defineConfig({
  // …
  provider: {
    name: 'ai',
    model: 'anthropic:claude-haiku-4-5',
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
  instruction: `
Brand: autotranslate. Never translate the brand name; never transliterate.
Voice: friendly, modern, direct. Sentences short.
Glossary (always English): API, SDK, CLI, monorepo, runtime.
Glossary (always English in code-style copy): TypeScript, JavaScript, Node.js.
  `.trim(),
});
```

--------------------------------

### Server-side Translation in Loaders

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/frameworks/remix.md

Get a translator instance in a Remix loader to perform server-side translations.

```typescript
import { getT } from '@autotranslate/react/server';

export async function loader({ request }: { request: Request }) {
  const locale = resolveLocale(request);
  const t = await getT(locale, loadCatalog);
  return { greeting: t.t('Welcome, {name}!', { name: 'Ada' }) };
}
```

--------------------------------

### Code Quality and Formatting Commands

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/CONTRIBUTING.md

Commands for linting, fixing, formatting, and type checking the project using Biome and TypeScript.

```bash
pnpm lint           # check
pnpm lint:fix       # auto-fix
pnpm format         # format everything
pnpm typecheck      # full project tsc
```

--------------------------------

### Usage with Standalone t Function

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/typescript-plugin/README.md

Example of using the standalone t function from @autotranslate/core/t. The plugin checks the literal string passed to t().

```tsx
import { t } from '@autotranslate/core/t';
t('Welcome'); // ← checked
```

--------------------------------

### Configure ESLint (Flat Config, v9+)

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/guides/linting.md

Configure ESLint using the flat config system by importing the plugin and applying its recommended configuration.

```javascript
import autotranslate from '@autotranslate/eslint-plugin';

export default [autotranslate.configs.recommended];
```

--------------------------------

### Usage with useT Hook

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/typescript-plugin/README.md

Example of using the useT hook from @autotranslate/react. The plugin checks the literal string passed to t().

```tsx
import { useT } from '@autotranslate/react';
const t = useT();
t('Sign out'); // ← checked
```

--------------------------------

### Replace next-intl middleware with autotranslate middleware

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/next-intl.md

Compares the middleware setup for routing and locale detection between next-intl and autotranslate.

```typescript
// before — middleware.ts
import createMiddleware from 'next-intl/middleware';

export default createMiddleware({
  locales: ['en', 'es', 'fr', 'ja'],
  defaultLocale: 'en',
});

// after — proxy.ts (Next.js 16+) or middleware.ts (Next.js 15)
import { createNextMiddleware } from '@autotranslate/next/middleware';

export default createNextMiddleware({
  locales: ['en', 'es', 'fr', 'ja'],
  defaultLocale: 'en',
  // strategy: 'cookie',  // optional; default is 'prefix'
});

export const config = {
  matcher: ['/((?!api|_next|.*\..*).*)'],
};
```

--------------------------------

### Error handling with currentTranslator caller

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/guides/standalone-t.md

Provide a caller identifier to `currentTranslator()` to get more informative error messages if no translator is bound.

```typescript
const translator = currentTranslator('zodErrorMap');
// → "[autotranslate] No active translator (called from zodErrorMap). …"
```

--------------------------------

### AI Provider Configuration with Instruction

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/guides/providers.md

Configure the 'ai' provider using the Vercel AI SDK. Specify the model and API key, and provide a top-level instruction for system prompts like tone, audience, and brand voice. The 'maxBatchSize' option controls the number of entries batched per call.

```typescript
provider: {
  name: 'ai',
  model: 'anthropic:claude-haiku-4-5',
  apiKey: process.env.ANTHROPIC_API_KEY,
},
instruction: 'Match a casual, modern product voice.',

```

--------------------------------

### Comparing react-i18next and autotranslate Syntax

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/migrating/react-i18next.md

Illustrates the differences in syntax for plain string lookups, rich text, and plurals between react-i18next and autotranslate. Note the JSON-first vs. code-first approach.

```tsx
// Plain string lookup
t('hello.world');                                 // react-i18next — needs JSON: { hello: { world: 'Hello' } }
t('Hello');                                       // autotranslate — the literal IS the key

// Rich text
<Trans>Hello <strong>{{name}}</strong></Trans>;   // react-i18next
<T>Hello <strong><Var>{name}</Var></strong></T>;  // autotranslate

// Plural — react-i18next: needs `items_one` / `items_other` keys
t('items', { count });
// autotranslate: one inline ICU source covers every CLDR form
t('{count, plural, one {# item} other {# items}}', { count });

// Language switch
i18next.changeLanguage('fr');                                  // react-i18next — mutates global state
<TranslationProvider locale="fr" catalog={catalogs.fr} />;     // autotranslate — re-render with new locale

// On-disk shape
// react-i18next   public/locales/{lng}/translation.json   (handwritten)
// autotranslate   .translations/{locale}/**.json          (generated)
```

--------------------------------

### Structural Keys with <T>

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/concepts.md

Example of using the `<T>` component for translating structured content like JSX. The key is derived from the normalized structure of the content.

```tsx
<T>
  Hello, <Var>{name}</Var>!
</T>
```

--------------------------------

### Setting up Dictionary Mode for Translations

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/guides/strings.md

Organize translations in a dictionary file for better management. Configure the `autotranslate.config.ts` to point to your dictionary file.

```ts
// src/dictionary.ts
export default {
  dashboard: {
    title: 'Dashboard',
    greeting: 'Welcome, {name}!',
  },
  cta: {
    signIn: 'Sign in',
    signUp: 'Sign up',
  },
};

```

```ts
// autotranslate.config.ts
export default defineConfig({
  // …
  dictionary: 'src/dictionary.ts',
});
```

--------------------------------

### Creating an AI Translation Provider

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/providers/README.md

Demonstrates how to create an AI translation provider using the `createAIProvider` function. This allows integration with various AI models from vendors like Anthropic, OpenAI, and Google.

```APIDOC
## createAIProvider

### Description
Creates an AI-based translation provider.

### Parameters
#### Request Body
- **opts** (object) - Required - Options for the AI provider.
  - **model** (string) - Required - The AI model to use, in the format `<vendor>:<model-id>` (e.g., `anthropic:claude-haiku-4-5`).
  - **apiKey** (string) - Required - The API key for the chosen vendor.
  - **instruction** (string) - Optional - An instruction to guide the AI's translation style.

### Returns
- `Provider` - An object conforming to the Provider interface, with a `translate` method.

### Example
```ts
import { createAIProvider } from '@autotranslate/providers/ai';

const provider = createAIProvider({
  model: 'anthropic:claude-haiku-4-5',
  apiKey: process.env.ANTHROPIC_API_KEY,
  instruction: 'Match a casual, modern product voice.',
});

const result = await provider.translate({
  source: 'en',
  target: 'es',
  items: [
    { key: 'Sign out', source: 'Sign out' },
    { key: 'greeting', source: 'Hello, {name}!' },
  ],
});
```
```

--------------------------------

### Create AI Provider with Custom Instruction

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/providers/README.md

Use the AI provider for translations with specific instructions. Ensure the relevant API key is set in the environment.

```typescript
import { createAIProvider } from '@autotranslate/providers/ai';

const provider = createAIProvider({
  model: 'anthropic:claude-haiku-4-5',
  apiKey: process.env.ANTHROPIC_API_KEY,
  instruction: 'Match a casual, modern product voice.',
});

const result = await provider.translate({
  source: 'en',
  target: 'es',
  items: [
    { key: 'Sign out', source: 'Sign out' },
    { key: 'greeting', source: 'Hello, {name}!' },
  ],
});
```

--------------------------------

### Catalog Entry for Context-Disambiguated Variants

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/cookbook/ab-copy.md

Each variant gets its own catalog entry, identified by the `context` value. This allows for independent translation of each variant.

```jsonc
// .translations/fr/components/CtaButton.json
{
  "Sign up@@cta control": "Inscrivez-vous",
  "Start now — limited time@@cta urgent": "Commencer maintenant — durée limitée",
}
```

--------------------------------

### Use Pseudo Provider in Development

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/cookbook/debugging.md

Enable the stub provider with `pseudo: true` in `autotranslate.config.dev.ts` for development. This renders all translated strings in a distinct format (e.g., `⟦ Šíǵñ óúţ ⟧`), making it easy to spot any content that was not correctly wrapped in `<T>` or `useT()` and thus not translated.

```ts
// autotranslate.config.dev.ts
provider: { name: 'stub', pseudo: true }
```

--------------------------------

### Unit Test: Render Source Strings

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/cookbook/testing.md

Render components without a `TranslationProvider` to assert that source strings are displayed. This requires no mocks or setup.

```tsx
import { render, screen } from '@testing-library/react';
import { test, expect } from 'vitest';
import { Greeting } from './Greeting';

test('renders the source greeting', () => {
  render(<Greeting name="Ada" />);
  expect(screen.getByText('Hello, Ada!')).toBeInTheDocument();
});
```

--------------------------------

### Getting the Active Locale with useLocale

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/docs/guides/strings.md

Retrieve the current active locale string using the `useLocale` hook. The component will re-render when the locale changes.

```tsx
import { useLocale } from '@autotranslate/react';

function Footer() {
  const locale = useLocale();
  return <span>Active locale: {locale}</span>;
}
```

--------------------------------

### Creating a Stub Translation Provider

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/providers/README.md

Shows how to create a stub provider, which can be used for testing, CI, or development. It also supports pseudo-localization for surfacing untranslated UI.

```APIDOC
## createStubProvider

### Description
Creates a stub translation provider. This provider can either return translations as-is or perform pseudo-localization.

### Parameters
#### Request Body
- **opts** (object) - Optional - Options for the stub provider.
  - **pseudo** (boolean) - Optional - If true, enables pseudo-localization. Defaults to false.

### Returns
- `Provider` - An object conforming to the Provider interface, with a `translate` method.

### Example
```ts
import { createStubProvider } from '@autotranslate/providers/stub';

// For testing or CI
const stub = createStubProvider();

// For pseudo-localization to surface untranslated UI
const pseudo = createStubProvider({ pseudo: true });
```
```

--------------------------------

### Configuration Utilities

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/core/README.md

Utilities for defining and parsing autotranslate configuration.

```APIDOC
## Configuration Utilities (`@autotranslate/core/config`)

### Description
Provides functions for defining and parsing autotranslate configuration, with type safety and validation.

### Functions
- `defineConfig(config: AutotranslateConfigInput): AutotranslateConfig`
  - A type-preserving identity helper for defining configuration.
- `parseConfig(input: any): AutotranslateConfig`
  - Parses and validates configuration input.
- `safeParseConfig(input: any): { success: boolean; data?: AutotranslateConfig; error?: any }`
  - Safely parses and validates configuration input, returning a result object.
```

--------------------------------

### App Layout with Translation Provider

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/next/README.md

Integrate TranslationProvider into your app layout for server components. This example fetches translations using getT and provides them to the client.

```tsx
// app/[lang]/layout.tsx
import { TranslationProvider } from '@autotranslate/react';
import { getT } from '@autotranslate/next';

export default async function Layout({
  children,
  params,
}: LayoutProps<'/[lang]'>) {
  const { lang } = await params;
  const [t, fallback] = await Promise.all([getT(lang), getT('en')]);
  return (
    <html lang={lang}>
      <body>
        <TranslationProvider locale={lang}>{children}</TranslationProvider>
      </body>
    </html>
  );
}
```

--------------------------------

### Server Entry - getT

Source: https://github.com/tamimbinhakim/autotranslate/blob/main/packages/react/README.md

Provides a synchronous-friendly translator factory for server-side rendering (RSC, SSR, route handlers, edge functions) without React context.

```APIDOC
## Server Entry - getT

### Description
Synchronous-friendly translator factories for RSC, SSR, route handlers, and edge functions — no React context involved.

### Usage
```ts
import { getT } from '@autotranslate/react/server';

export default async function Page() {
  const t = await getT('es', () => loadCatalog('es'), () => loadCatalog('en'));
  return <h1>{t.t('Welcome')}</h1>;
}
```

### Exports
- **`getT`**: Async factory — calls your catalog loader(s).
- **`createTranslator`**: Synchronous factory (re-exported from `core`).
```