docs: translation

.eslintignore

@@ -3,6 +3,7 @@ package.json
 playwright.config.ts
 rollup.config.*
 .eslintrc.cjs
+scripts
 *.test.ts
 *.test.tsx
 *.spec.ts

.eslintrc.cjs

@@ -64,5 +64,11 @@ module.exports = {
         '@typescript-eslint/no-unused-vars': 'warn',
       },
     },
+    {
+      // `tsconfig.json` excludes `tests`, so type-aware parsing cannot reach
+      // these — without this they are a parsing error, not a lint result.
+      files: ['tests/**/*.ts'],
+      parserOptions: { project: null },
+    },
   ],
 };

.github/workflows/tests.yml

@@ -50,7 +50,9 @@ jobs:
       #   run: npm run test:exports
 
       - name: Unit tests
-        run: pnpm exec tsc --noEmit && pnpm exec vitest --run --coverage
+        # Through wireit: the examples import `state-in-url`, so the typecheck
+        # needs a built `dist/`, and `tsc` depends on `build`.
+        run: pnpm run tsc && pnpm exec vitest --run --coverage
       - name: Run codacy-coverage-reporter
         uses: codacy/codacy-coverage-reporter-action@89d6c85cfafaec52c72b6c5e8b2878d33104c699 # v1.3.0
         continue-on-error: true

AGENTS.md

@@ -13,16 +13,17 @@ files are written for that, and are far more specific than this one.
 
 This is a **pnpm** monorepo. `pnpm` is enforced (`only-allow`). Most scripts run through **wireit** (caching/dependency graph), so always invoke them via `pnpm run <script>`, not the underlying tool directly.
 
-- `pnpm run test` — full suite: `tsc` typecheck → unit tests → build all packages → exports test → integration (e2e) tests. This is what CI runs.
-- `pnpm run test:unit` — Vitest unit tests (depends on `tsc`). Runs `npx vitest` (watch by default; coverage is enabled in config).
-- `pnpm run test:int` — Playwright e2e (`--project=chromium`). Requires the demo servers running (`pnpm run start` or `pnpm run dev`).
+- `pnpm run test` — full suite: `tsc` typecheck → unit tests → build all packages → exports test → integration (e2e) tests. Everything CI checks, but not the command CI runs — `.github/workflows/tests.yml` splits it into three parallel jobs and calls the tools directly, so a break in this wiring shows up locally only.
+- `pnpm run test:unit` — Vitest unit tests (depends on `tsc`), single run, ~2s; coverage is on in the config. Use `npx vitest` directly for watch mode.
+- `pnpm run test:int` — Playwright e2e (`--project=chromium`). Starts the seven demo servers unless they are already up, and waits for all seven before the first test.
 - `pnpm run tsc` — `tsc --noEmit` typecheck only.
 - `pnpm run build` — Rollup build of the library into `dist/` (ESM `.mjs` + CJS `.js` + `.d.ts`).
 - `pnpm run dev` — library in Rollup watch mode + all example apps. Next.js 15 demo on `http://localhost:3000`.
 - `pnpm run kill` — kill hung Next/Vite/wireit processes (use this if dev/test servers hang).
 - `pnpm run cleanup` / `pnpm run reinstall` — nuke build artifacts and node_modules.
 - `pnpm run setup` — `playwright install --with-deps` (needed before e2e on a fresh machine).
 - `pnpm run test:lighthouse` — Lighthouse audits of the demo site (see below). Builds and serves it itself; nothing needs to be running first.
+- `pnpm i18n status` / `pnpm i18n:check` — the eight translations: drift from the English source, and README structure/links/anchors. `pnpm i18n:toc` rebuilds the tables of contents; `pnpm i18n:copy:check` covers the demo's copy modules.
 
 Run a single unit test: `npx vitest run packages/urlstate/encoder/encoder.test.ts` (or pass a `-t "name"` filter).
 Run a single e2e spec: `npx playwright test tests/useUrlState/main.spec.ts --project=chromium`.
@@ -35,6 +36,7 @@ Run a single e2e spec: `npx playwright test tests/useUrlState/main.spec.ts --pro
 - `tests/` — Playwright e2e specs (separate from the colocated `*.test.ts` unit tests).
 - `lighthouse/` — the Lighthouse suite, its own directory so the e2e config's `testDir: './tests'` cannot pick it up. Driven by `playwright.lighthouse.config.ts`.
 - `skills/` — agent skill files (`SKILL.md` per topic) that are **published as part of the npm package** (see `files` in `package.json`). `skills/_artifacts/` is dev-only and excluded from publish; `skill_spec.md` there is a useful map of the library's domains and known user failure modes.
+- `scripts/i18n/` — the translation toolkit: the locale table, the drift and structure checks, and the translator's prompt and glossary. See `scripts/i18n/AGENTS.md`.
 
 ## Architecture
 

Limits.es.md

@@ -0,0 +1,45 @@
+<!-- i18n:start -->
+[English](./Limits.md) · [简体中文](./Limits.zh-CN.md) · [日本語](./Limits.ja.md) · [한국어](./Limits.ko.md) · [Русский](./Limits.ru.md) · Español · [Português (BR)](./Limits.pt-BR.md) · [Français](./Limits.fr.md) · [Tiếng Việt](./Limits.vi.md)
+<!-- i18n:meta locale=es source=Limits.md source-blob=3c1cb46e7a6f78a1de385946dd4a7e1f66717080 status=translated -->
+<!-- i18n:end -->
+
+# Limitación del tamaño de URL y cabeceras
+
+Los navegadores modernos permiten especificar URLs muy largas, fácilmente 2MB.
+
+Pero hay algunas limitaciones por parte de servidores web y CDN. En general, **solo hasta 12KB para la URI es seguro**.
+
+## Comprobar el tamaño del JSON
+
+Puedes meter fácilmente un par de formularios enormes en la URL sin preocuparte por alcanzar el límite.
+
+```js
+var size = new TextEncoder().encode(JSON.stringify(
+    { key1: "Value 1$%^&*", key2: "⚖★☔" } // tu objeto JSON
+)).length
+var kiloBytes = Number(size / 1024).toFixed(2);
+var megaBytes = Number(kiloBytes / 1024).toFixed(2);
+console.log({ kiloBytes, megaBytes })
+```
+
+## Limitaciones
+
+La dirección URL es parte de las [cabeceras HTTP de la solicitud](https://developer.mozilla.org/en-US/docs/Glossary/Request_header); los siguientes límites se aplican a URL + cabeceras.
+
+### Vercel 14KB, límite duro
+
+[Docs](https://vercel.com/docs/errors/URL_TOO_LONG)
+
+### Apache httpd 8KB, se puede aumentar
+
+[Docs](https://httpd.apache.org/docs/2.2/mod/core.html#limitrequestline)
+
+### Nginx 8KB, se puede aumentar
+
+[Docs](http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers)
+
+### NodeJS 8KB, se puede aumentar con `--max-http-header-size=16384`
+
+[Docs](https://github.com/nodejs/node/issues/24692)
+
+[Docs2](https://stackoverflow.com/a/56954244/5538912)

Limits.fr.md

@@ -0,0 +1,45 @@
+<!-- i18n:start -->
+[English](./Limits.md) · [简体中文](./Limits.zh-CN.md) · [日本語](./Limits.ja.md) · [한국어](./Limits.ko.md) · [Русский](./Limits.ru.md) · [Español](./Limits.es.md) · [Português (BR)](./Limits.pt-BR.md) · Français · [Tiếng Việt](./Limits.vi.md)
+<!-- i18n:meta locale=fr source=Limits.md source-blob=3c1cb46e7a6f78a1de385946dd4a7e1f66717080 status=translated -->
+<!-- i18n:end -->
+
+# Limitation de la taille des URL et des en-têtes
+
+Les navigateurs modernes permettent de spécifier des URL très longues, facilement 2MB.
+
+Mais il existe certaines limitations des serveurs web et des CDN. En général, **jusqu'à 12KB seulement pour l'URI est sûr**.
+
+## Vérifier la taille du JSON
+
+Vous pouvez facilement faire tenir quelques formulaires énormes dans l'URL sans jamais vous inquiéter d'atteindre la limite.
+
+```js
+var size = new TextEncoder().encode(JSON.stringify(
+    { key1: "Value 1$%^&*", key2: "⚖★☔" } // votre objet JSON
+)).length
+var kiloBytes = Number(size / 1024).toFixed(2);
+var megaBytes = Number(kiloBytes / 1024).toFixed(2);
+console.log({ kiloBytes, megaBytes })
+```
+
+## Limitations
+
+L'adresse URL fait partie des [en-têtes HTTP de la requête](https://developer.mozilla.org/en-US/docs/Glossary/Request_header), les limites suivantes s'appliquent donc à URL + en-têtes.
+
+### Vercel 14KB, limite stricte
+
+[Docs](https://vercel.com/docs/errors/URL_TOO_LONG)
+
+### Apache httpd 8KB, peut être augmentée
+
+[Docs](https://httpd.apache.org/docs/2.2/mod/core.html#limitrequestline)
+
+### Nginx 8KB, peut être augmentée
+
+[Docs](http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers)
+
+### NodeJS 8KB, peut être augmentée avec `--max-http-header-size=16384`
+
+[Docs](https://github.com/nodejs/node/issues/24692)
+
+[Docs2](https://stackoverflow.com/a/56954244/5538912)

Limits.ja.md

@@ -0,0 +1,45 @@
+<!-- i18n:start -->
+[English](./Limits.md) · [简体中文](./Limits.zh-CN.md) · 日本語 · [한국어](./Limits.ko.md) · [Русский](./Limits.ru.md) · [Español](./Limits.es.md) · [Português (BR)](./Limits.pt-BR.md) · [Français](./Limits.fr.md) · [Tiếng Việt](./Limits.vi.md)
+<!-- i18n:meta locale=ja source=Limits.md source-blob=3c1cb46e7a6f78a1de385946dd4a7e1f66717080 status=translated -->
+<!-- i18n:end -->
+
+# URL とヘッダーのサイズ制限
+
+現代のブラウザでは非常に長い URL(簡単に 2MB)を指定できます。
+
+ただし、Web サーバーや CDN にはいくつか制限があります。一般的に、**URI については最大 12KB までが安全**です。
+
+## JSON サイズの確認
+
+上限に達する心配をせずに、いくつかの巨大なフォームを URL に簡単に収められます。
+
+```js
+var size = new TextEncoder().encode(JSON.stringify(
+    { key1: "Value 1$%^&*", key2: "⚖★☔" } // あなたの JSON オブジェクト
+)).length
+var kiloBytes = Number(size / 1024).toFixed(2);
+var megaBytes = Number(kiloBytes / 1024).toFixed(2);
+console.log({ kiloBytes, megaBytes })
+```
+
+## 制限
+
+URL アドレスは [リクエスト HTTP ヘッダー](https://developer.mozilla.org/en-US/docs/Glossary/Request_header) の一部であり、以下の制限は URL + ヘッダーに対するものです。
+
+### Vercel 14KB、ハードリミット
+
+[Docs](https://vercel.com/docs/errors/URL_TOO_LONG)
+
+### Apache httpd 8KB、増やせます
+
+[Docs](https://httpd.apache.org/docs/2.2/mod/core.html#limitrequestline)
+
+### Nginx 8KB、増やせます
+
+[Docs](http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers)
+
+### NodeJS 8KB、`--max-http-header-size=16384` で増やせます
+
+[Docs](https://github.com/nodejs/node/issues/24692)
+
+[Docs2](https://stackoverflow.com/a/56954244/5538912)

Limits.ko.md

@@ -0,0 +1,45 @@
+<!-- i18n:start -->
+[English](./Limits.md) · [简体中文](./Limits.zh-CN.md) · [日本語](./Limits.ja.md) · 한국어 · [Русский](./Limits.ru.md) · [Español](./Limits.es.md) · [Português (BR)](./Limits.pt-BR.md) · [Français](./Limits.fr.md) · [Tiếng Việt](./Limits.vi.md)
+<!-- i18n:meta locale=ko source=Limits.md source-blob=3c1cb46e7a6f78a1de385946dd4a7e1f66717080 status=translated -->
+<!-- i18n:end -->
+
+# URL 및 헤더 크기 제한
+
+최신 브라우저는 매우 긴 URL을 지정할 수 있으며, 2MB도 문제없습니다.
+
+하지만 웹 서버와 CDN에는 몇 가지 제한이 있습니다. 일반적으로 **URI는 최대 12KB까지 안전**합니다.
+
+## JSON 크기 확인
+
+제한에 걸릴 걱정 없이 여러 개의 거대한 폼을 URL에 쉽게 담을 수 있습니다.
+
+```js
+var size = new TextEncoder().encode(JSON.stringify(
+    { key1: "Value 1$%^&*", key2: "⚖★☔" } // 여러분의 JSON 객체
+)).length
+var kiloBytes = Number(size / 1024).toFixed(2);
+var megaBytes = Number(kiloBytes / 1024).toFixed(2);
+console.log({ kiloBytes, megaBytes })
+```
+
+## 제한 사항
+
+URL 주소는 [요청 HTTP 헤더](https://developer.mozilla.org/en-US/docs/Glossary/Request_header)의 일부이며, 아래 제한은 URL + 헤더에 적용됩니다.
+
+### Vercel 14KB, 하드 제한
+
+[Docs](https://vercel.com/docs/errors/URL_TOO_LONG)
+
+### Apache httpd 8KB, 늘릴 수 있음
+
+[Docs](https://httpd.apache.org/docs/2.2/mod/core.html#limitrequestline)
+
+### Nginx 8KB, 늘릴 수 있음
+
+[Docs](http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers)
+
+### NodeJS 8KB, `--max-http-header-size=16384`로 늘릴 수 있음
+
+[Docs](https://github.com/nodejs/node/issues/24692)
+
+[Docs2](https://stackoverflow.com/a/56954244/5538912)

Limits.md

@@ -1,3 +1,8 @@
+<!-- i18n:start -->
+English · [简体中文](./Limits.zh-CN.md) · [日本語](./Limits.ja.md) · [한국어](./Limits.ko.md) · [Русский](./Limits.ru.md) · [Español](./Limits.es.md) · [Português (BR)](./Limits.pt-BR.md) · [Français](./Limits.fr.md) · [Tiếng Việt](./Limits.vi.md)
+<!-- i18n:meta locale=en -->
+<!-- i18n:end -->
+
 # Limitation of URL and headers size
 
 Modern browsers allow you specify very long URLs, 2MB easily.

Limits.pt-BR.md

@@ -0,0 +1,45 @@
+<!-- i18n:start -->
+[English](./Limits.md) · [简体中文](./Limits.zh-CN.md) · [日本語](./Limits.ja.md) · [한국어](./Limits.ko.md) · [Русский](./Limits.ru.md) · [Español](./Limits.es.md) · Português (BR) · [Français](./Limits.fr.md) · [Tiếng Việt](./Limits.vi.md)
+<!-- i18n:meta locale=pt-BR source=Limits.md source-blob=3c1cb46e7a6f78a1de385946dd4a7e1f66717080 status=translated -->
+<!-- i18n:end -->
+
+# Limitação do tamanho de URL e cabeçalhos
+
+Os navegadores modernos permitem especificar URLs muito longas, facilmente 2MB.
+
+Mas há algumas limitações de servidores web e CDN. Em geral, **apenas até 12KB para a URI é seguro**.
+
+## Verificar o tamanho do JSON
+
+Você pode facilmente encaixar alguns formulários enormes na URL sem se preocupar em atingir o limite.
+
+```js
+var size = new TextEncoder().encode(JSON.stringify(
+    { key1: "Value 1$%^&*", key2: "⚖★☔" } // seu objeto JSON
+)).length
+var kiloBytes = Number(size / 1024).toFixed(2);
+var megaBytes = Number(kiloBytes / 1024).toFixed(2);
+console.log({ kiloBytes, megaBytes })
+```
+
+## Limitações
+
+O endereço URL faz parte dos [cabeçalhos HTTP da solicitação](https://developer.mozilla.org/en-US/docs/Glossary/Request_header); os limites a seguir se aplicam a URL + cabeçalhos.
+
+### Vercel 14KB, limite rígido
+
+[Docs](https://vercel.com/docs/errors/URL_TOO_LONG)
+
+### Apache httpd 8KB, pode ser aumentado
+
+[Docs](https://httpd.apache.org/docs/2.2/mod/core.html#limitrequestline)
+
+### Nginx 8KB, pode ser aumentado
+
+[Docs](http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers)
+
+### NodeJS 8KB, pode ser aumentado com `--max-http-header-size=16384`
+
+[Docs](https://github.com/nodejs/node/issues/24692)
+
+[Docs2](https://stackoverflow.com/a/56954244/5538912)

Limits.ru.md

@@ -0,0 +1,45 @@
+<!-- i18n:start -->
+[English](./Limits.md) · [简体中文](./Limits.zh-CN.md) · [日本語](./Limits.ja.md) · [한국어](./Limits.ko.md) · Русский · [Español](./Limits.es.md) · [Português (BR)](./Limits.pt-BR.md) · [Français](./Limits.fr.md) · [Tiếng Việt](./Limits.vi.md)
+<!-- i18n:meta locale=ru source=Limits.md source-blob=3c1cb46e7a6f78a1de385946dd4a7e1f66717080 status=translated -->
+<!-- i18n:end -->
+
+# Ограничение размера URL и заголовков
+
+Современные браузеры позволяют указывать очень длинные URL — легко 2MB.
+
+Но есть ограничения со стороны веб-серверов и CDN. В общем случае **безопасно до 12KB только для URI**.
+
+## Проверка размера JSON
+
+Можно легко уместить пару огромных форм в URL, не беспокоясь о достижении лимита.
+
+```js
+var size = new TextEncoder().encode(JSON.stringify(
+    { key1: "Value 1$%^&*", key2: "⚖★☔" } // ваш JSON-объект
+)).length
+var kiloBytes = Number(size / 1024).toFixed(2);
+var megaBytes = Number(kiloBytes / 1024).toFixed(2);
+console.log({ kiloBytes, megaBytes })
+```
+
+## Ограничения
+
+URL-адрес — часть [заголовков HTTP-запроса](https://developer.mozilla.org/en-US/docs/Glossary/Request_header), поэтому следующие ограничения относятся к URL + заголовкам.
+
+### Vercel 14KB, жёсткий лимит
+
+[Docs](https://vercel.com/docs/errors/URL_TOO_LONG)
+
+### Apache httpd 8KB, можно увеличить
+
+[Docs](https://httpd.apache.org/docs/2.2/mod/core.html#limitrequestline)
+
+### Nginx 8KB, можно увеличить
+
+[Docs](http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers)
+
+### NodeJS 8KB, можно увеличить через `--max-http-header-size=16384`
+
+[Docs](https://github.com/nodejs/node/issues/24692)
+
+[Docs2](https://stackoverflow.com/a/56954244/5538912)

Limits.vi.md

@@ -0,0 +1,45 @@
+<!-- i18n:start -->
+[English](./Limits.md) · [简体中文](./Limits.zh-CN.md) · [日本語](./Limits.ja.md) · [한국어](./Limits.ko.md) · [Русский](./Limits.ru.md) · [Español](./Limits.es.md) · [Português (BR)](./Limits.pt-BR.md) · [Français](./Limits.fr.md) · Tiếng Việt
+<!-- i18n:meta locale=vi source=Limits.md source-blob=3c1cb46e7a6f78a1de385946dd4a7e1f66717080 status=translated -->
+<!-- i18n:end -->
+
+# Giới hạn kích thước URL và header
+
+Các trình duyệt hiện đại cho phép bạn chỉ định URL rất dài, dễ dàng tới 2MB.
+
+Nhưng có một số giới hạn từ Web Server và CDN. Nói chung, **chỉ tối đa 12KB cho URI là an toàn**.
+
+## Kiểm tra kích thước JSON
+
+Có thể dễ dàng nhét vài biểu mẫu khổng lồ vào URL mà không bao giờ lo chạm giới hạn.
+
+```js
+var size = new TextEncoder().encode(JSON.stringify(
+    { key1: "Value 1$%^&*", key2: "⚖★☔" } // object JSON của bạn
+)).length
+var kiloBytes = Number(size / 1024).toFixed(2);
+var megaBytes = Number(kiloBytes / 1024).toFixed(2);
+console.log({ kiloBytes, megaBytes })
+```
+
+## Các giới hạn
+
+Địa chỉ URL là một phần của [header HTTP request](https://developer.mozilla.org/en-US/docs/Glossary/Request_header), các giới hạn sau áp dụng cho URL + header.
+
+### Vercel 14KB, giới hạn cứng
+
+[Docs](https://vercel.com/docs/errors/URL_TOO_LONG)
+
+### Apache httpd 8KB, có thể tăng
+
+[Docs](https://httpd.apache.org/docs/2.2/mod/core.html#limitrequestline)
+
+### Nginx 8KB, có thể tăng
+
+[Docs](http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers)
+
+### NodeJS 8KB, có thể tăng bằng `--max-http-header-size=16384`
+
+[Docs](https://github.com/nodejs/node/issues/24692)
+
+[Docs2](https://stackoverflow.com/a/56954244/5538912)