Skip to content

aymericzip/intlayer-skills / skills/intlayer-usage

intlayer-usage

Verified

Provides general guidelines for using Intlayer in any project. Use when the user asks to "get started with Intlayer", "declare content files", or understand the "project structure" for internationalization.

FileKindSize
LICENCE.mdmarkdown10.7 KB
SKILL.mdskill md3.6 KB
references/concept_how-works-intlayer.mdmarkdown28.7 KB
references/concept_per-locale-file.mdmarkdown7.6 KB
references/get-started.mdmarkdown26.6 KB
references/packages_intlayer_comparePaths.mdmarkdown5.0 KB
references/packages_intlayer_exports.mdmarkdown12.4 KB
references/packages_intlayer_getCanonicalPath.mdmarkdown3.4 KB
references/packages_intlayer_getConfiguration.mdmarkdown4.1 KB
references/packages_intlayer_getDictionary.mdmarkdown4.9 KB
references/packages_intlayer_getDictionaryAsync.mdmarkdown6.3 KB
references/packages_intlayer_getEnumeration.mdmarkdown3.3 KB
references/packages_intlayer_getHTMLTextDir.mdmarkdown2.3 KB
references/packages_intlayer_getIntlayer.mdmarkdown8.7 KB
references/packages_intlayer_getIntlayerAsync.mdmarkdown6.8 KB
references/packages_intlayer_getLocale.mdmarkdown1.1 KB
references/packages_intlayer_getLocaleLang.mdmarkdown1.9 KB
references/packages_intlayer_getLocaleName.mdmarkdown3.5 KB
references/packages_intlayer_getLocalizedPath.mdmarkdown6.8 KB
references/packages_intlayer_getLocalizedUrl.mdmarkdown9.3 KB
references/packages_intlayer_getMultilingualUrls.mdmarkdown8.7 KB
references/packages_intlayer_getPathWithoutLocale.mdmarkdown1.6 KB
references/packages_intlayer_getPrefix.mdmarkdown6.0 KB
references/packages_intlayer_getTranslation.mdmarkdown3.4 KB
references/packages_intlayer_validatePrefix.mdmarkdown1.0 KB
references/packages_react-intlayer_exports.mdmarkdown13.7 KB
references/packages_vite-intlayer_exports.mdmarkdown6.0 KB
references/packages_vite-intlayer_intlayer.mdmarkdown6.0 KB
references/packages_vite-intlayer_intlayerCompiler.mdmarkdown4.2 KB
references/packages_vite-intlayer_intlayerMinify.mdmarkdown3.9 KB
references/packages_vite-intlayer_intlayerProxy.mdmarkdown7.0 KB
references/packages_vite-intlayer_intlayerPrune.mdmarkdown4.7 KB
references/why.mdmarkdown58.2 KB

references/packages_vite-intlayer_intlayerProxy.md

View on GitHub
---
createdAt: 2026-06-25
updatedAt: 2026-06-25
priority: 5
title: intlayerProxy Vite Plugin Documentation | vite-intlayer
description: Locale-routing middleware for Vite dev/preview servers and production SSR. Handles locale detection, URL redirects, and internal rewrites.
keywords:
  - intlayerProxy
  - vite
  - plugin
  - middleware
  - locale
  - routing
  - internationalization
  - i18n
  - SSR
slugs:
  - doc
  - packages
  - vite-intlayer
  - intlayerProxy
history:
  - version: 9.0.0
    date: 2026-06-25
    changes: "Merged configOptions into single options object; proxy bundled into intlayer()"
author: aymericzip
---

# intlayerProxy

`intlayerProxy` is a Vite plugin that registers locale-routing middleware for **every environment**: dev server, preview server, and production SSR (Nitro / TanStack Start).

> **Since Intlayer v9** `intlayerProxy` is automatically included inside the main [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/vite-intlayer/intlayer.md) plugin and enabled by default via `routing.enableProxy: true`. You only need to register it separately if you need lower-level control or are using it outside the standard `intlayer()` setup.

- [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/vite-intlayer/intlayer.md)

## Usage

### As part of `intlayer()` (recommended, v9+)

Pass `proxy` options to the main plugin instead of registering `intlayerProxy` separately:

```ts
// vite.config.ts
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});
```

### Standalone (when needed)

```ts
// vite.config.ts
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [intlayer()],
});
```

## Options

```ts
import type { IntlayerProxyPluginOptions } from "vite-intlayer";
```

All options are optional and passed as a single object:

| Option          | Type                                | Description                                                                                                                                        |
| --------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ignore`        | `(req: IncomingMessage) => boolean` | Predicate that excludes requests from locale routing. Return `true` to skip a request (e.g. API routes, health checks).                            |
| `configOptions` | `GetConfigurationOptions`           | Intlayer configuration overrides forwarded to `getConfiguration()`. Use when you need the proxy to read a specific config file or override values. |

### Example

```ts
intlayerProxy({
  ignore: (req) => req.url?.startsWith("/api"),
  configOptions: { configFile: "./config/intlayer.config.ts" },
});
```

## createIntlayerProxyHandler

`createIntlayerProxyHandler` creates a standalone, framework-agnostic Node.js `(req, res, next)` middleware that contains all the locale-routing logic. It is useful in environments where the Vite plugin API is unavailable (e.g. a plain Node.js server or a custom Nitro module).

```ts
import { createIntlayerProxyHandler } from "vite-intlayer";

const handler = createIntlayerProxyHandler({
  ignore: (req) => req.url?.startsWith("/api"),
  configOptions: { configFile: "./config/intlayer.config.ts" },
});

// Express / Connect
app.use(handler);
```

### Production SSR (TanStack Start / Nitro via h3)

```ts
// server/middleware/intlayerProxy.ts
import { fromNodeMiddleware } from "h3";
import { createIntlayerProxyHandler } from "vite-intlayer";

export default fromNodeMiddleware(
  createIntlayerProxyHandler({
    ignore: (req) => req.url?.startsWith("/api"),
  })
);
```

## Routing behaviour

The middleware mirrors the routing logic from `next-intlayer` middleware and supports all Intlayer routing modes.

### Routing modes

| Mode            | URL visible in browser   | Behaviour                                                                                               |
| --------------- | ------------------------ | ------------------------------------------------------------------------------------------------------- |
| `prefix`        | `/en/about`              | Default. Locale prefix in the URL. Default locale redirects to the un-prefixed URL unless `prefix-all`. |
| `prefix-all`    | `/en/about`, `/fr/about` | All locales, including default, are always prefixed.                                                    |
| `no-prefix`     | `/about`                 | No locale in the URL. Locale is stored in cookies only; URL rewrites happen internally.                 |
| `search-params` | `/about?locale=en`       | Locale passed as a query parameter. Redirects to add/update the `locale` param when missing or stale.   |

### Detection priority

1. URL path prefix (e.g. `/fr/about` → `fr`).
2. Cookie / localStorage value (`intlayer-locale`).
3. `Accept-Language` header.
4. `defaultLocale` from config.

### Automatic bypass

The middleware always passes these requests straight through without locale handling:

- Requests matching the `ignore` predicate.
- `/node_modules/**`
- `/@**` – Vite internals (`@vite/`, `@fs/`, `@id/`, etc.).
- `/_**` – server internals (`__vite_ping`, `__manifest`, etc.).
- Requests whose path ends with a file extension (static assets). If a locale prefix is present on a static asset path (e.g. `/fr/logo.png`), it is stripped so the file can be served correctly.

### Domain routing

When `routing.domains` is configured in your Intlayer config, the middleware handles cross-domain locale routing:

- A request for `/zh/about` on `intlayer.org` is redirected to `https://intlayer.zh/about` when `domains.zh = "intlayer.zh"`.
- A request to `intlayer.zh/about` is rewritten internally to `/zh/about` so the `[locale]` route parameter is populated.

### Redirect loop protection

The middleware tracks redirect counts per `originalUrl → newUrl` pair within a 2-second sliding window. More than 10 redirects within that window returns a `500` response with a descriptive error instead of looping forever.

## Nitro / production SSR (automatic injection, v9+)

When `intlayerProxy` is used as a Vite plugin, it carries a `.nitro` property. The `nitro/vite` build plugin reads this property and pushes it into `nitroConfig.modules`, so `intlayerNitroHandler` is registered as a Nitro server middleware automatically, no manual configuration is needed for production SSR.

The Nitro handler uses h3 v2's Web Fetch API event model (not `fromNodeMiddleware`) so it is compatible with all Nitro presets: Node, Bun, Deno, edge runtimes.

## Deprecated aliases

| Deprecated export          | Replacement     |
| -------------------------- | --------------- |
| `intlayerMiddleware`       | `intlayerProxy` |
| `intLayerMiddlewarePlugin` | `intlayerProxy` |
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall