@markuplint/i18n 5.0.0-rc.2 → 5.0.0-rc.5

package/$schema.json

@@ -186,13 +186,14 @@
 			"additionalProperties": false,
 			"properties": {
 				"{0} {1}": { "type": "string" },
+				"{0} {1} has no cells beginning in it": { "type": "string" },
+				"{0} {1} have no cells beginning in them": { "type": "string" },
 				"{0:c} and {1:c}": { "type": "string" },
 				"{0:c} on {1}": { "type": "string" },
 				"{0} ({1})": { "type": "string" },
 				"{0} according to {1}": { "type": "string" },
 				"{0} are causing {1}": { "type": "string" },
 				"{0} as {1}": { "type": "string" },
-				"{0} associates only {1}": { "type": "string" },
 				"{0} behaves the same as {1} if {2}": { "type": "string" },
 				"{0} chars": { "type": "string" },
 				"{0} contradicts {1}": { "type": "string" },

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-rc.5](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.4...v5.0.0-rc.5) (2026-08-28)
+
+### Code Refactoring
+
+- **rules:** redesign v5 rule system — naming, splits, specConformance ([#3989](https://github.com/markuplint/markuplint/issues/3989)) ([e925565](https://github.com/markuplint/markuplint/commit/e925565ce537848d7d1573369723cbce724a841b)), closes [#4](https://github.com/markuplint/markuplint/issues/4) [#aside-conditional-role-mapping-aria-13](https://github.com/markuplint/markuplint/issues/aside-conditional-role-mapping-aria-13)
+
+### Features
+
+- **rules:** report HTML LS table model errors in table-row-column-alignment ([#3953](https://github.com/markuplint/markuplint/issues/3953)) ([bacdcd6](https://github.com/markuplint/markuplint/commit/bacdcd697f76300153388f5b1cabaa8504f08d1f)), closes [#3916](https://github.com/markuplint/markuplint/issues/3916) [#3915](https://github.com/markuplint/markuplint/issues/3915) [#3916](https://github.com/markuplint/markuplint/issues/3916) [#3915](https://github.com/markuplint/markuplint/issues/3915)
+
+### BREAKING CHANGES
+
+- **rules:** with no alias coverage.
+
+# [5.0.0-rc.4](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.3...v5.0.0-rc.4) (2026-04-19)
+
+**Note:** Version bump only for package @markuplint/i18n
+
+# [5.0.0-rc.3](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.2...v5.0.0-rc.3) (2026-04-19)
+
+**Note:** Version bump only for package @markuplint/i18n
+
 # [5.0.0-rc.2](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.1...v5.0.0-rc.2) (2026-04-15)
 
 ### Features

package/CLAUDE.md

@@ -0,0 +1,13 @@
+# @markuplint/i18n
+
+Constraints not derivable from code:
+
+- `$schema.json` is maintained **by hand** and uses `additionalProperties: false`.
+  Every keyword or sentence added to a locale file MUST also be added to
+  `$schema.json`, or the locale fails schema validation. Keep the files in sync.
+- `en.json` is intentionally minimal: the English sentence key itself serves as
+  the template, so `en.json` only carries entries that need capitalization or
+  special formatting. Do NOT mirror every `ja.json` entry into `en.json`.
+
+Placeholder syntax (`{0}`, `{0:c}` complement, `{0*}` no-translate) is documented
+in `src/translator.ts` JSDoc.

package/cjs/index.d.ts

@@ -1,2 +1,24 @@
+/**
+ * @module @markuplint/i18n
+ *
+ * Internationalization for markuplint rule messages.
+ *
+ * Locale dictionary contract (`locales/*.json` and `$schema.json`):
+ * - Sentence template keys are the English sentences themselves, and an untranslated
+ *   keyword falls back to its own key. Therefore `locales/en.json` needs no `sentences`
+ *   section and holds only keyword overrides where the lowercase key cannot serve as
+ *   display text (e.g. `"html elements"` → `"HTML elements"`), since keyword lookup
+ *   keys are lowercase.
+ * - `locales/ja.json` is the reference dictionary: it is expected to translate every
+ *   keyword and sentence template, and serves as the template for new languages.
+ * - `$schema.json` is the source of truth for valid keys. It intentionally declares
+ *   `additionalProperties: false` so that a keyword or sentence added to a locale file
+ *   without a matching schema entry fails validation instead of silently never matching.
+ *   The schema is shared by all locales, so adding a language requires no schema change.
+ * - Translated sentence templates may reorder placeholders freely (e.g. `"{0} is not
+ *   allowed in {1}"` → `"{1}に{0}は許可されていません"`) because placeholder numbers
+ *   refer to translator argument positions, not to their position in the English
+ *   template.
+ */
 export { translator } from './translator.js';
 export type { Translator, LocaleSet } from './types.js';

package/cjs/index.js

@@ -1,4 +1,26 @@
 "use strict";
+/**
+ * @module @markuplint/i18n
+ *
+ * Internationalization for markuplint rule messages.
+ *
+ * Locale dictionary contract (`locales/*.json` and `$schema.json`):
+ * - Sentence template keys are the English sentences themselves, and an untranslated
+ *   keyword falls back to its own key. Therefore `locales/en.json` needs no `sentences`
+ *   section and holds only keyword overrides where the lowercase key cannot serve as
+ *   display text (e.g. `"html elements"` → `"HTML elements"`), since keyword lookup
+ *   keys are lowercase.
+ * - `locales/ja.json` is the reference dictionary: it is expected to translate every
+ *   keyword and sentence template, and serves as the template for new languages.
+ * - `$schema.json` is the source of truth for valid keys. It intentionally declares
+ *   `additionalProperties: false` so that a keyword or sentence added to a locale file
+ *   without a matching schema entry fails validation instead of silently never matching.
+ *   The schema is shared by all locales, so adding a language requires no schema change.
+ * - Translated sentence templates may reorder placeholders freely (e.g. `"{0} is not
+ *   allowed in {1}"` → `"{1}に{0}は許可されていません"`) because placeholder numbers
+ *   refer to translator argument positions, not to their position in the English
+ *   template.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.translator = void 0;
 var translator_js_1 = require("./translator.js");

package/cjs/translator.d.ts

@@ -8,21 +8,21 @@ import type { LocaleSet, Primitive, Translator } from './types.js';
  * - **List formatting**: `t(["apple", "banana", "cherry"], true)` – formats an array of strings
  *   into a human-readable list (e.g. `"apple", "banana" and "cherry"`).
  *
+ * Placeholder flags carry translation intent:
+ * - `{0:c}` resolves through a `c:`-prefixed keyword (complement form); see `translateKeyword` below.
+ * - `{0*}` inserts the argument verbatim, for dynamic values such as attribute names or
+ *   user input that must not go through keyword translation.
+ *
  * @param localeSet - The locale configuration providing translations and formatting rules
  * @returns A translator function for producing localized messages
  */
 export declare function translator(localeSet?: LocaleSet): Translator;
 /**
- * Creates a tagged template literal translator function.
- *
- * Allows using template literal syntax for translations:
  * ```ts
  * const tt = taggedTemplateTranslator(localeSet);
  * const msg = tt`The ${name} is ${value}`;
  * ```
  *
  * @experimental
- * @param localeSet - The locale configuration providing translations and formatting rules
- * @returns A tagged template function that produces localized strings
  */
 export declare function taggedTemplateTranslator(localeSet?: LocaleSet): (strings: Readonly<TemplateStringsArray>, ...keys: readonly Primitive[]) => string;

package/cjs/translator.js

@@ -17,6 +17,11 @@ const defaultListFormat = {
  * - **List formatting**: `t(["apple", "banana", "cherry"], true)` – formats an array of strings
  *   into a human-readable list (e.g. `"apple", "banana" and "cherry"`).
  *
+ * Placeholder flags carry translation intent:
+ * - `{0:c}` resolves through a `c:`-prefixed keyword (complement form); see `translateKeyword` below.
+ * - `{0*}` inserts the argument verbatim, for dynamic values such as attribute names or
+ *   user input that must not go through keyword translation.
+ *
  * @param localeSet - The locale configuration providing translations and formatting rules
  * @returns A translator function for producing localized messages
  */
@@ -69,17 +74,12 @@ function translator(localeSet) {
     };
 }
 /**
- * Creates a tagged template literal translator function.
- *
- * Allows using template literal syntax for translations:
  * ```ts
  * const tt = taggedTemplateTranslator(localeSet);
  * const msg = tt`The ${name} is ${value}`;
  * ```
  *
  * @experimental
- * @param localeSet - The locale configuration providing translations and formatting rules
- * @returns A tagged template function that produces localized strings
  */
 function taggedTemplateTranslator(localeSet) {
     const t = translator(localeSet);
@@ -97,6 +97,16 @@ function taggedTemplateTranslator(localeSet) {
         return t(template, ...keys);
     };
 }
+/**
+ * Resolves a keyword to its translation in the locale set.
+ *
+ * When the `c` flag is given (from a `{n:c}` placeholder), the lookup tries the
+ * `c:`-prefixed dictionary entry first. Complement (`c:`) keywords exist for languages
+ * such as Japanese where the translation must be a predicate that attaches to the
+ * preceding subject (e.g. `c:deprecated` → 「は非推奨です」, yielding 「〇〇は非推奨です」),
+ * which cannot be produced from the plain keyword translation. The plain keyword
+ * (without `c:`) may still exist as a separate dictionary entry for non-complement use.
+ */
 function translateKeyword(keyword, flag, localeSet) {
     // No translate
     if (/^%[^%]+%$/.test(keyword)) {

package/esm/index.d.ts

@@ -1,2 +1,24 @@
+/**
+ * @module @markuplint/i18n
+ *
+ * Internationalization for markuplint rule messages.
+ *
+ * Locale dictionary contract (`locales/*.json` and `$schema.json`):
+ * - Sentence template keys are the English sentences themselves, and an untranslated
+ *   keyword falls back to its own key. Therefore `locales/en.json` needs no `sentences`
+ *   section and holds only keyword overrides where the lowercase key cannot serve as
+ *   display text (e.g. `"html elements"` → `"HTML elements"`), since keyword lookup
+ *   keys are lowercase.
+ * - `locales/ja.json` is the reference dictionary: it is expected to translate every
+ *   keyword and sentence template, and serves as the template for new languages.
+ * - `$schema.json` is the source of truth for valid keys. It intentionally declares
+ *   `additionalProperties: false` so that a keyword or sentence added to a locale file
+ *   without a matching schema entry fails validation instead of silently never matching.
+ *   The schema is shared by all locales, so adding a language requires no schema change.
+ * - Translated sentence templates may reorder placeholders freely (e.g. `"{0} is not
+ *   allowed in {1}"` → `"{1}に{0}は許可されていません"`) because placeholder numbers
+ *   refer to translator argument positions, not to their position in the English
+ *   template.
+ */
 export { translator } from './translator.js';
 export type { Translator, LocaleSet } from './types.js';

package/esm/index.mjs

@@ -1 +1,23 @@
+/**
+ * @module @markuplint/i18n
+ *
+ * Internationalization for markuplint rule messages.
+ *
+ * Locale dictionary contract (`locales/*.mjson` and `$schema.mjson`):
+ * - Sentence template keys are the English sentences themselves, and an untranslated
+ *   keyword falls back to its own key. Therefore `locales/en.mjson` needs no `sentences`
+ *   section and holds only keyword overrides where the lowercase key cannot serve as
+ *   display text (e.g. `"html elements"` → `"HTML elements"`), since keyword lookup
+ *   keys are lowercase.
+ * - `locales/ja.mjson` is the reference dictionary: it is expected to translate every
+ *   keyword and sentence template, and serves as the template for new languages.
+ * - `$schema.mjson` is the source of truth for valid keys. It intentionally declares
+ *   `additionalProperties: false` so that a keyword or sentence added to a locale file
+ *   without a matching schema entry fails validation instead of silently never matching.
+ *   The schema is shared by all locales, so adding a language requires no schema change.
+ * - Translated sentence templates may reorder placeholders freely (e.g. `"{0} is not
+ *   allowed in {1}"` → `"{1}に{0}は許可されていません"`) because placeholder numbers
+ *   refer to translator argument positions, not to their position in the English
+ *   template.
+ */
 export { translator } from './translator.mjs';

package/esm/translator.d.ts

@@ -8,21 +8,21 @@ import type { LocaleSet, Primitive, Translator } from './types.js';
  * - **List formatting**: `t(["apple", "banana", "cherry"], true)` – formats an array of strings
  *   into a human-readable list (e.g. `"apple", "banana" and "cherry"`).
  *
+ * Placeholder flags carry translation intent:
+ * - `{0:c}` resolves through a `c:`-prefixed keyword (complement form); see `translateKeyword` below.
+ * - `{0*}` inserts the argument verbatim, for dynamic values such as attribute names or
+ *   user input that must not go through keyword translation.
+ *
  * @param localeSet - The locale configuration providing translations and formatting rules
  * @returns A translator function for producing localized messages
  */
 export declare function translator(localeSet?: LocaleSet): Translator;
 /**
- * Creates a tagged template literal translator function.
- *
- * Allows using template literal syntax for translations:
  * ```ts
  * const tt = taggedTemplateTranslator(localeSet);
  * const msg = tt`The ${name} is ${value}`;
  * ```
  *
  * @experimental
- * @param localeSet - The locale configuration providing translations and formatting rules
- * @returns A tagged template function that produces localized strings
  */
 export declare function taggedTemplateTranslator(localeSet?: LocaleSet): (strings: Readonly<TemplateStringsArray>, ...keys: readonly Primitive[]) => string;

package/esm/translator.mjs

@@ -13,6 +13,11 @@ const defaultListFormat = {
  * - **List formatting**: `t(["apple", "banana", "cherry"], true)` – formats an array of strings
  *   into a human-readable list (e.g. `"apple", "banana" and "cherry"`).
  *
+ * Placeholder flags carry translation intent:
+ * - `{0:c}` resolves through a `c:`-prefixed keyword (complement form); see `translateKeyword` below.
+ * - `{0*}` inserts the argument verbatim, for dynamic values such as attribute names or
+ *   user input that must not go through keyword translation.
+ *
  * @param localeSet - The locale configuration providing translations and formatting rules
  * @returns A translator function for producing localized messages
  */
@@ -65,17 +70,12 @@ export function translator(localeSet) {
     };
 }
 /**
- * Creates a tagged template literal translator function.
- *
- * Allows using template literal syntax for translations:
  * ```ts
  * const tt = taggedTemplateTranslator(localeSet);
  * const msg = tt`The ${name} is ${value}`;
  * ```
  *
  * @experimental
- * @param localeSet - The locale configuration providing translations and formatting rules
- * @returns A tagged template function that produces localized strings
  */
 export function taggedTemplateTranslator(localeSet) {
     const t = translator(localeSet);
@@ -93,6 +93,16 @@ export function taggedTemplateTranslator(localeSet) {
         return t(template, ...keys);
     };
 }
+/**
+ * Resolves a keyword to its translation in the locale set.
+ *
+ * When the `c` flag is given (from a `{n:c}` placeholder), the lookup tries the
+ * `c:`-prefixed dictionary entry first. Complement (`c:`) keywords exist for languages
+ * such as Japanese where the translation must be a predicate that attaches to the
+ * preceding subject (e.g. `c:deprecated` → 「は非推奨です」, yielding 「〇〇は非推奨です」),
+ * which cannot be produced from the plain keyword translation. The plain keyword
+ * (without `c:`) may still exist as a separate dictionary entry for non-complement use.
+ */
 function translateKeyword(keyword, flag, localeSet) {
     // No translate
     if (/^%[^%]+%$/.test(keyword)) {

package/locales/ja.json

@@ -170,13 +170,14 @@
 	},
 	"sentences": {
 		"{0} {1}": "{0}{1}",
+		"{0} {1} has no cells beginning in it": "{0}つの{1}に開始するセルがありません",
+		"{0} {1} have no cells beginning in them": "{0}つの{1}に開始するセルがありません",
 		"{0:c} and {1:c}": "{0}且つ、{1}",
 		"{0:c} on {1}": "{1}では、{0:c}",
 		"{0} ({1})": "{0}({1})",
 		"{0} according to {1}": "{1}において、{0}",
 		"{0} are causing {1}": "{0}が{1}を引き起こしています",
 		"{0} as {1}": "{1}として{0}",
-		"{0} associates only {1}": "{0}は{1}だけを関連付けます",
 		"{0} behaves the same as {1} if {2}": "{0}は{2}の場合、{1}と同じ振る舞いをします",
 		"{0} chars": "{0}文字",
 		"{0} contradicts {1}": "{0}は{1}と矛盾しています",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/i18n",
-	"version": "5.0.0-rc.2",
+	"version": "5.0.0-rc.5",
 	"description": "Internationalization for markuplint",
 	"repository": {
 		"type": "git",
@@ -10,7 +10,7 @@
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
 	"engines": {
-		"node": ">=22"
+		"node": ">=24"
 	},
 	"main": "./cjs/index.js",
 	"types": "./cjs/index.d.ts",
@@ -45,5 +45,5 @@
 		"clean:esm": "tsc --build --clean tsconfig.build.json",
 		"clean:cjs": "tsc --build --clean tsconfig.build-cjs.json"
 	},
-	"gitHead": "e43763858d9234c417053becc73dbd088c1e7ea6"
+	"gitHead": "8d87463af2ff3f1b83fb28da20f1819362cf3555"
 }

package/SKILL.md

@@ -1,73 +0,0 @@
----
-description: Maintenance tasks for @markuplint/i18n — internationalization for markuplint
-globs:
-  - packages/@markuplint/i18n/src/**/*.ts
-  - packages/@markuplint/i18n/locales/*.json
-  - packages/@markuplint/i18n/$schema.json
-alwaysApply: false
----
-
-# @markuplint/i18n Maintenance
-
-You are maintaining `@markuplint/i18n`, the internationalization package for markuplint.
-
-## Architecture
-
-See [README.md](README.md) for the full API documentation including translator usage, placeholder syntax, and locale formatting.
-
-For detailed maintenance procedures, see [docs/maintenance.md](docs/maintenance.md) ([Japanese](docs/maintenance.ja.md)).
-
-## Key Files
-
-| File                | Role                                                                                           |
-| ------------------- | ---------------------------------------------------------------------------------------------- |
-| `locales/ja.json`   | Japanese locale dictionary (keywords + sentences + listFormat)                                 |
-| `locales/en.json`   | English locale dictionary (minimal; only entries needing capitalization or special formatting) |
-| `$schema.json`      | JSON Schema for locale files (`additionalProperties: false`)                                   |
-| `src/translator.ts` | Core translation logic                                                                         |
-| `src/types.ts`      | `LocaleSet`, `ListFormat`, `Translator` types                                                  |
-
-## Tasks
-
-### add-keyword
-
-Add a new keyword used in rule messages.
-
-1. Add to `locales/ja.json` under `keywords` (alphabetical order, lowercase key)
-   - Normal keyword: `"tag name": "タグ名"`
-   - Complement keyword (for `:c` flag): `"c:deprecated": "は非推奨です"`
-2. Add to `locales/en.json` under `keywords` only if capitalization or special formatting is needed
-3. Add to `$schema.json` under `keywords.properties` as `{ "type": "string" }`
-4. Test: `yarn test --scope @markuplint/i18n`
-5. Build: `yarn build --scope @markuplint/i18n`
-
-**Important**: `$schema.json` uses `additionalProperties: false`. A keyword not defined in the schema will cause validation errors. Always keep the three files in sync.
-
-### add-sentence
-
-Add a new sentence template for rule messages.
-
-1. Design the English template as the key
-   - Placeholders: `{0}`, `{1}`, `{2}`...
-   - Complement flag: `{0:c}` (resolves to `c:` prefixed keyword in Japanese)
-   - No-translate mark: `{0*}` (skips translation for that placeholder)
-2. Add to `locales/ja.json` under `sentences` (placeholder order may differ for natural Japanese)
-3. Add to `$schema.json` under `sentences.properties` as `{ "type": "string" }`
-4. `en.json` does not need a `sentences` entry (the English key itself serves as the template)
-5. Test: `yarn test --scope @markuplint/i18n`
-
-### add-language
-
-Add support for a new language.
-
-1. Create `locales/<lang>.json` using `ja.json` as a template
-   - `listFormat`: Define quote characters and separator for the language
-   - `keywords`: Translate all keywords
-   - `sentences`: Translate all sentence templates
-2. Add an export entry in `package.json`:
-   ```json
-   "./locales/<lang>.json": { "import": "./locales/<lang>.json", "require": "./locales/<lang>.json" }
-   ```
-3. `$schema.json` is shared across all languages (no changes needed)
-4. Add test cases in `src/index.spec.ts`
-5. Test: `yarn test --scope @markuplint/i18n`

package/docs/maintenance.ja.md

@@ -1,208 +0,0 @@
-# @markuplint/i18n メンテナンスガイド
-
-## 概要
-
-`@markuplint/i18n` パッケージは、markuplint のルールメッセージの国際化を提供します。
-
-- **ロケール辞書** (`locales/*.json`) — 言語ごとのキーワード、文テンプレート、リスト書式ルール
-- **翻訳エンジン** (`src/translator.ts`) — テンプレートのキーワード置換、補語形式、リスト整形を処理
-- **JSON Schema** (`$schema.json`) — 厳密なプロパティチェックでロケールファイルを検証
-
-### ファイル構成
-
-```
-packages/@markuplint/i18n/
-├── locales/
-│   ├── ja.json          # 日本語辞書（完全版）
-│   └── en.json          # 英語辞書（最小限のオーバーライド）
-├── src/
-│   ├── translator.ts    # 翻訳コアロジック
-│   ├── types.ts         # LocaleSet, Translator 型定義
-│   └── index.spec.ts    # テストスイート
-├── $schema.json         # ロケール JSON Schema
-└── package.json
-```
-
-## 3ファイル同期ルール
-
-キーワードや文テンプレートを追加する際、3つのファイルを同期する必要があります。
-
-| ファイル          | 役割                                                                                                                           | 必須？         |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------- |
-| `$schema.json`    | 許可されるプロパティキーを定義。`additionalProperties: false` のため、ここに定義されていないキーはバリデーションエラーになる。 | **常に必須**   |
-| `locales/ja.json` | すべてのキーワードと文テンプレートの日本語翻訳。                                                                               | **常に必須**   |
-| `locales/en.json` | 英語のオーバーライド。大文字化や特殊な書式が必要な場合のみ（例: `"html elements"` → `"HTML elements"`）。                      | 必要な場合のみ |
-
-スキーマが有効なキーの定義元です。`ja.json` にキーワードを追加しても `$schema.json` に追加しなければ、ロケールファイルのスキーマ検証が失敗します。
-
-## 単語を追加する
-
-キーワードは、ルールメッセージの構成要素として使われる単語または短いフレーズです。ロケールファイルの `keywords` セクションに定義します。
-
-### 手順
-
-1. **`ja.json`** の `keywords` にアルファベット順で追加:
-
-   ```json
-   {
-     "keywords": {
-       "focusable": "フォーカス可能"
-     }
-   }
-   ```
-
-   - キーは英語の小文字
-   - 値は日本語の翻訳
-
-2. **`en.json`** の `keywords` には必要な場合のみ追加:
-
-   ```json
-   {
-     "keywords": {
-       "html elements": "HTML elements"
-     }
-   }
-   ```
-
-   ほとんどの英語キーワードはエントリ不要です。キーがそのまま使用されます。
-
-3. **`$schema.json`** の `keywords.properties` に追加:
-
-   ```json
-   {
-     "keywords": {
-       "properties": {
-         "focusable": { "type": "string" }
-       }
-     }
-   }
-   ```
-
-4. **テスト**: `yarn test --scope @markuplint/i18n`
-5. **ビルド**: `yarn build --scope @markuplint/i18n`
-
-### 補語キーワード
-
-補語キーワードは `c:` プレフィックスを使い、プレースホルダーに `:c` フラグ（例: `{0:c}`）が付いた場合に解決されます。日本語では主語に続く述語として機能します。
-
-| ロケールのキー                           | テンプレートでの使用                         | 出力例（ja）                   |
-| ---------------------------------------- | -------------------------------------------- | ------------------------------ |
-| `"c:deprecated": "は非推奨です"`         | `"{0} is {1:c}"` + キーワード `"deprecated"` | `「要素」は非推奨です`         |
-| `"c:disallowed": "は許可されていません"` | `"{0} is {1:c}"` + キーワード `"disallowed"` | `「属性」は許可されていません` |
-| `"c:prohibited": "は禁止されています"`   | `"{0} is {1:c}"` + キーワード `"prohibited"` | `「属性」は禁止されています`   |
-
-補語キーワードを追加する際:
-
-1. `ja.json` の keywords に `"c:<word>"` を追加
-2. `$schema.json` の keywords properties に `"c:<word>"` を追加
-3. 補語なしバージョン（`c:` なし）も別のキーワードとして必要な場合がある
-
-## フレーズを追加する
-
-文テンプレートは、プレースホルダー付きのメッセージパターンを定義します。ロケールファイルの `sentences` セクションに定義します。
-
-### 手順
-
-1. **英語テンプレート**をキーとして設計:
-
-   ```
-   "{0} conflicts with {1}"
-   ```
-
-   プレースホルダー構文:
-   - `{0}`, `{1}`, `{2}` — 位置パラメータ、キーワードとして翻訳される
-   - `{0:c}` — 補語フラグ、日本語では `c:` プレフィックスキーワードに解決
-   - `{0*}` — 翻訳スキップ、値がキーワード検索なしでそのまま挿入される
-
-2. **`ja.json`** の `sentences` に追加:
-
-   ```json
-   {
-     "sentences": {
-       "{0} conflicts with {1}": "{0}は{1}と競合しています"
-     }
-   }
-   ```
-
-   日本語の自然な語順にするため、プレースホルダーの順序は英語と異なってもよい。
-
-3. **`$schema.json`** の `sentences.properties` に追加:
-
-   ```json
-   {
-     "sentences": {
-       "properties": {
-         "{0} conflicts with {1}": { "type": "string" }
-       }
-     }
-   }
-   ```
-
-4. **`en.json` に sentences エントリは不要**。英語のキー自体がテンプレートとして使用されます。翻訳が見つからない場合、translator はキーをそのまま使います。
-
-5. **テスト**: `yarn test --scope @markuplint/i18n`
-
-### プレースホルダーの並べ替え
-
-日本語と英語では語順が異なります。文テンプレートを翻訳する際、プレースホルダーは自由に並べ替えできます:
-
-- 英語: `"{0} is not allowed in {1}"`
-- 日本語: `"{1}に{0}は許可されていません"`
-
-プレースホルダーの番号は、translator に渡される引数の位置を指し、文字列内の位置ではありません。
-
-## 新しい言語を追加する
-
-まったく新しい言語のサポートを追加する手順です。
-
-### 手順
-
-1. **`locales/<lang>.json`** を `ja.json` をテンプレートにして作成:
-
-   ```json
-   {
-     "$schema": "../$schema.json",
-     "listFormat": {
-       "quoteStart": "\"",
-       "quoteEnd": "\"",
-       "separator": ", "
-     },
-     "keywords": {
-       "attribute": "<翻訳>",
-       "element": "<翻訳>"
-     },
-     "sentences": {
-       "{0} is {1}": "<翻訳テンプレート>"
-     }
-   }
-   ```
-
-   - `listFormat`: 言語に適した引用符と区切り文字を定義
-   - `keywords`: `ja.json` のすべてのキーワードを翻訳
-   - `sentences`: `ja.json` のすべての文テンプレートを翻訳
-
-2. **`package.json`** にエクスポートエントリを追加:
-
-   ```json
-   {
-     "exports": {
-       "./locales/<lang>.json": {
-         "import": "./locales/<lang>.json",
-         "require": "./locales/<lang>.json"
-       }
-     }
-   }
-   ```
-
-3. **`$schema.json` の変更は不要** — スキーマは全言語で共有されます。
-
-4. **`src/index.spec.ts`** に新しいロケールのテストケースを追加。
-
-5. **テスト**: `yarn test --scope @markuplint/i18n`
-
-## コマンドリファレンス
-
-| コマンド                              | 説明               |
-| ------------------------------------- | ------------------ |
-| `yarn test --scope @markuplint/i18n`  | テスト実行         |
-| `yarn build --scope @markuplint/i18n` | パッケージのビルド |

package/docs/maintenance.md

@@ -1,208 +0,0 @@
-# @markuplint/i18n Maintenance Guide
-
-## Overview
-
-The `@markuplint/i18n` package provides internationalization for markuplint rule messages. It consists of:
-
-- **Locale dictionaries** (`locales/*.json`) — keywords, sentence templates, and list formatting rules per language
-- **Translator engine** (`src/translator.ts`) — resolves templates with keyword substitution, complement forms, and list formatting
-- **JSON Schema** (`$schema.json`) — validates locale files with strict property checking
-
-### File Structure
-
-```
-packages/@markuplint/i18n/
-├── locales/
-│   ├── ja.json          # Japanese dictionary (complete)
-│   └── en.json          # English dictionary (minimal overrides)
-├── src/
-│   ├── translator.ts    # Core translation logic
-│   ├── types.ts         # LocaleSet, Translator types
-│   └── index.spec.ts    # Test suite
-├── $schema.json         # Locale JSON Schema
-└── package.json
-```
-
-## Three-File Synchronization Rule
-
-When adding keywords or sentences, three files must be kept in sync:
-
-| File              | Role                                                                                                                                       | Required?      |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
-| `$schema.json`    | Defines allowed property keys. Uses `additionalProperties: false`, so any key not listed here will cause a validation error.               | **Always**     |
-| `locales/ja.json` | Complete Japanese translations for all keywords and sentences.                                                                             | **Always**     |
-| `locales/en.json` | English overrides. Only needed when a keyword requires capitalization or special formatting (e.g., `"html elements"` → `"HTML elements"`). | Only if needed |
-
-The schema is the source of truth for which keys are valid. If you add a keyword to `ja.json` without adding it to `$schema.json`, the locale file will fail schema validation.
-
-## Adding a Keyword
-
-Keywords are single words or short phrases used as building blocks in rule messages. They appear in the `keywords` section of locale files.
-
-### Steps
-
-1. **Add to `ja.json`** under `keywords` in alphabetical order:
-
-   ```json
-   {
-     "keywords": {
-       "focusable": "フォーカス可能"
-     }
-   }
-   ```
-
-   - Keys must be lowercase English
-   - Values are the Japanese translations
-
-2. **Add to `en.json`** under `keywords` only if needed:
-
-   ```json
-   {
-     "keywords": {
-       "html elements": "HTML elements"
-     }
-   }
-   ```
-
-   Most English keywords do not need an entry because the key itself is used as-is.
-
-3. **Add to `$schema.json`** under `keywords.properties`:
-
-   ```json
-   {
-     "keywords": {
-       "properties": {
-         "focusable": { "type": "string" }
-       }
-     }
-   }
-   ```
-
-4. **Test**: `yarn test --scope @markuplint/i18n`
-5. **Build**: `yarn build --scope @markuplint/i18n`
-
-### Complement Keywords
-
-Complement keywords use the `c:` prefix and are resolved when a placeholder has the `:c` flag (e.g., `{0:c}`). They form a predicate that attaches to the preceding subject in Japanese.
-
-| Key in locale                            | Usage in template                            | Example output (ja)            |
-| ---------------------------------------- | -------------------------------------------- | ------------------------------ |
-| `"c:deprecated": "は非推奨です"`         | `"{0} is {1:c}"` with keyword `"deprecated"` | `「要素」は非推奨です`         |
-| `"c:disallowed": "は許可されていません"` | `"{0} is {1:c}"` with keyword `"disallowed"` | `「属性」は許可されていません` |
-| `"c:prohibited": "は禁止されています"`   | `"{0} is {1:c}"` with keyword `"prohibited"` | `「属性」は禁止されています`   |
-
-When adding a complement keyword:
-
-1. Add `"c:<word>"` to `ja.json` keywords
-2. Add `"c:<word>"` to `$schema.json` keywords properties
-3. The non-complement version (without `c:`) may also be needed as a separate keyword
-
-## Adding a Sentence Template
-
-Sentence templates define message patterns with placeholders. They appear in the `sentences` section of locale files.
-
-### Steps
-
-1. **Design the English template** as the key:
-
-   ```
-   "{0} conflicts with {1}"
-   ```
-
-   Placeholder syntax:
-   - `{0}`, `{1}`, `{2}` — positional placeholders, translated as keywords
-   - `{0:c}` — complement flag, resolves to `c:` prefixed keyword in Japanese
-   - `{0*}` — no-translate mark, the value is inserted as-is without keyword lookup
-
-2. **Add to `ja.json`** under `sentences`:
-
-   ```json
-   {
-     "sentences": {
-       "{0} conflicts with {1}": "{0}は{1}と競合しています"
-     }
-   }
-   ```
-
-   Placeholder order may differ from English to produce natural Japanese.
-
-3. **Add to `$schema.json`** under `sentences.properties`:
-
-   ```json
-   {
-     "sentences": {
-       "properties": {
-         "{0} conflicts with {1}": { "type": "string" }
-       }
-     }
-   }
-   ```
-
-4. **`en.json` does not need a sentences entry**. The English key itself serves as the template. The translator uses the key directly when no translation is found.
-
-5. **Test**: `yarn test --scope @markuplint/i18n`
-
-### Placeholder Reordering
-
-Japanese word order differs from English. When translating sentence templates, you can freely reorder placeholders:
-
-- English: `"{0} is not allowed in {1}"`
-- Japanese: `"{1}に{0}は許可されていません"`
-
-The placeholder numbers refer to the arguments passed to the translator, not their position in the string.
-
-## Adding a New Language
-
-To add support for an entirely new language:
-
-### Steps
-
-1. **Create `locales/<lang>.json`** using `ja.json` as a template:
-
-   ```json
-   {
-     "$schema": "../$schema.json",
-     "listFormat": {
-       "quoteStart": "\"",
-       "quoteEnd": "\"",
-       "separator": ", "
-     },
-     "keywords": {
-       "attribute": "<translated>",
-       "element": "<translated>"
-     },
-     "sentences": {
-       "{0} is {1}": "<translated template>"
-     }
-   }
-   ```
-
-   - `listFormat`: Define the quote characters and separators appropriate for the language
-   - `keywords`: Translate all keywords from `ja.json`
-   - `sentences`: Translate all sentence templates from `ja.json`
-
-2. **Add export entry in `package.json`**:
-
-   ```json
-   {
-     "exports": {
-       "./locales/<lang>.json": {
-         "import": "./locales/<lang>.json",
-         "require": "./locales/<lang>.json"
-       }
-     }
-   }
-   ```
-
-3. **`$schema.json` requires no changes** — the schema is shared across all languages.
-
-4. **Add test cases** in `src/index.spec.ts` to verify the new locale works correctly with the translator.
-
-5. **Test**: `yarn test --scope @markuplint/i18n`
-
-## Command Reference
-
-| Command                               | Description       |
-| ------------------------------------- | ----------------- |
-| `yarn test --scope @markuplint/i18n`  | Run tests         |
-| `yarn build --scope @markuplint/i18n` | Build the package |