@markuplint/i18n 4.7.0 → 4.7.1

package/CHANGELOG.md

@@ -3,6 +3,10 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.7.1](https://github.com/markuplint/markuplint/compare/@markuplint/i18n@4.7.0...@markuplint/i18n@4.7.1) (2026-02-10)
+
+**Note:** Version bump only for package @markuplint/i18n
+
 # [4.7.0](https://github.com/markuplint/markuplint/compare/@markuplint/i18n@4.6.0...@markuplint/i18n@4.7.0) (2025-08-13)
 
 ### Bug Fixes

package/SKILL.md

@@ -0,0 +1,73 @@
+---
+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/cjs/translator.d.ts

@@ -1,6 +1,28 @@
 import type { LocaleSet, Primitive, Translator } from './types.js';
+/**
+ * Creates a {@link Translator} function bound to the given locale set.
+ *
+ * The returned translator supports two call signatures:
+ * - **Message template**: `t("The {0} is {1}", keyword1, keyword2)` – interpolates keywords into
+ *   a message template, looking up translations from the locale set's `sentences` and `keywords`.
+ * - **List formatting**: `t(["apple", "banana", "cherry"], true)` – formats an array of strings
+ *   into a human-readable list (e.g. `"apple", "banana" and "cherry"`).
+ *
+ * @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

@@ -8,9 +8,20 @@ const defaultListFormat = {
     separator: ', ',
     lastSeparator: ' and ',
 };
+/**
+ * Creates a {@link Translator} function bound to the given locale set.
+ *
+ * The returned translator supports two call signatures:
+ * - **Message template**: `t("The {0} is {1}", keyword1, keyword2)` – interpolates keywords into
+ *   a message template, looking up translations from the locale set's `sentences` and `keywords`.
+ * - **List formatting**: `t(["apple", "banana", "cherry"], true)` – formats an array of strings
+ *   into a human-readable list (e.g. `"apple", "banana" and "cherry"`).
+ *
+ * @param localeSet - The locale configuration providing translations and formatting rules
+ * @returns A translator function for producing localized messages
+ */
 function translator(localeSet) {
     return (messageTmpl, ...keywords) => {
-        let message = messageTmpl;
         if (typeof messageTmpl !== 'string') {
             if (messageTmpl.length === 0) {
                 return '';
@@ -40,7 +51,7 @@ function translator(localeSet) {
         messageTmpl = sentence ?? key;
         messageTmpl =
             removeNoTranslateMark(input.toLowerCase()) === messageTmpl ? removeNoTranslateMark(input) : messageTmpl;
-        message = messageTmpl.replaceAll(
+        const message = messageTmpl.replaceAll(
         // eslint-disable-next-line regexp/strict
         /{(\d+)(?::(c))?}/g, ($0, number, flag) => {
             const num = Number.parseInt(number);
@@ -58,7 +69,17 @@ 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);

package/cjs/types.d.ts

@@ -1,21 +1,71 @@
+/**
+ * A function that translates message templates or formats keyword lists
+ * according to a bound locale set.
+ *
+ * Overloads:
+ * 1. Translate a message template with keyword interpolation.
+ * 2. Format a list of keywords into a human-readable string.
+ * 3. Combined signature accepting either form.
+ */
 export interface Translator {
+    /**
+     * Translates a message template by interpolating keywords.
+     *
+     * @param messageTmpl - The message template with `{0}`, `{1}`, ... placeholders
+     * @param keywords - Values to substitute into the template
+     * @returns The translated, interpolated message string
+     */
     (messageTmpl: string, ...keywords: readonly Primitive[]): string;
+    /**
+     * Formats a list of keywords into a localized, human-readable string.
+     *
+     * @param messageTmpl - An array of keywords to format as a list
+     * @param useLastSeparator - Whether to use the "last separator" (e.g. " and ") before the final item
+     * @returns The formatted list string
+     */
     (messageTmpl: readonly string[], useLastSeparator?: boolean): string;
+    /**
+     * Combined overload accepting either a message template string or a keyword list.
+     *
+     * @param messageTmpl - A message template string or an array of keywords
+     * @param keywords - Values to substitute (when a string template is provided)
+     * @returns The translated or formatted string
+     */
     (messageTmpl: string | readonly string[], ...keywords: readonly Primitive[]): string;
 }
+/**
+ * Configuration for a specific locale, including translations and formatting rules.
+ */
 export type LocaleSet = {
+    /** The locale identifier (e.g. `"en"`, `"ja"`) */
     readonly locale: string;
+    /** Formatting rules for rendering keyword lists */
     readonly listFormat?: ListFormat;
+    /** A dictionary mapping lowercase keywords to their translations */
     readonly keywords?: LocalesKeywords;
+    /** A dictionary mapping lowercase sentence templates to their translations */
     readonly sentences?: LocalesKeywords;
 };
+/**
+ * Formatting rules for rendering a list of items as a human-readable string.
+ */
 export type ListFormat = {
+    /** Character(s) placed before each quoted item (e.g. `"`) */
     readonly quoteStart: string;
+    /** Character(s) placed after each quoted item (e.g. `"`) */
     readonly quoteEnd: string;
+    /** Separator between items (e.g. `", "`) */
     readonly separator: string;
+    /** Separator before the last item (e.g. `" and "`); falls back to `separator` if omitted */
     readonly lastSeparator?: string;
 };
+/**
+ * A primitive value type used as a keyword in translations.
+ */
 export type Primitive = string | number | boolean;
+/**
+ * A dictionary mapping message IDs (lowercase) to their translated strings.
+ */
 export type LocalesKeywords = {
     readonly [messageId: string]: string;
 };

package/docs/maintenance.ja.md

@@ -0,0 +1,207 @@
+# @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"` | `「属性」は許可されていません` |
+
+補語キーワードを追加する際:
+
+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

@@ -0,0 +1,207 @@
+# @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"` | `「属性」は許可されていません` |
+
+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 |

package/esm/translator.d.ts

@@ -1,6 +1,28 @@
 import type { LocaleSet, Primitive, Translator } from './types.js';
+/**
+ * Creates a {@link Translator} function bound to the given locale set.
+ *
+ * The returned translator supports two call signatures:
+ * - **Message template**: `t("The {0} is {1}", keyword1, keyword2)` – interpolates keywords into
+ *   a message template, looking up translations from the locale set's `sentences` and `keywords`.
+ * - **List formatting**: `t(["apple", "banana", "cherry"], true)` – formats an array of strings
+ *   into a human-readable list (e.g. `"apple", "banana" and "cherry"`).
+ *
+ * @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

@@ -4,9 +4,20 @@ const defaultListFormat = {
     separator: ', ',
     lastSeparator: ' and ',
 };
+/**
+ * Creates a {@link Translator} function bound to the given locale set.
+ *
+ * The returned translator supports two call signatures:
+ * - **Message template**: `t("The {0} is {1}", keyword1, keyword2)` – interpolates keywords into
+ *   a message template, looking up translations from the locale set's `sentences` and `keywords`.
+ * - **List formatting**: `t(["apple", "banana", "cherry"], true)` – formats an array of strings
+ *   into a human-readable list (e.g. `"apple", "banana" and "cherry"`).
+ *
+ * @param localeSet - The locale configuration providing translations and formatting rules
+ * @returns A translator function for producing localized messages
+ */
 export function translator(localeSet) {
     return (messageTmpl, ...keywords) => {
-        let message = messageTmpl;
         if (typeof messageTmpl !== 'string') {
             if (messageTmpl.length === 0) {
                 return '';
@@ -36,7 +47,7 @@ export function translator(localeSet) {
         messageTmpl = sentence ?? key;
         messageTmpl =
             removeNoTranslateMark(input.toLowerCase()) === messageTmpl ? removeNoTranslateMark(input) : messageTmpl;
-        message = messageTmpl.replaceAll(
+        const message = messageTmpl.replaceAll(
         // eslint-disable-next-line regexp/strict
         /{(\d+)(?::(c))?}/g, ($0, number, flag) => {
             const num = Number.parseInt(number);
@@ -54,7 +65,17 @@ 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);

package/esm/types.d.ts

@@ -1,21 +1,71 @@
+/**
+ * A function that translates message templates or formats keyword lists
+ * according to a bound locale set.
+ *
+ * Overloads:
+ * 1. Translate a message template with keyword interpolation.
+ * 2. Format a list of keywords into a human-readable string.
+ * 3. Combined signature accepting either form.
+ */
 export interface Translator {
+    /**
+     * Translates a message template by interpolating keywords.
+     *
+     * @param messageTmpl - The message template with `{0}`, `{1}`, ... placeholders
+     * @param keywords - Values to substitute into the template
+     * @returns The translated, interpolated message string
+     */
     (messageTmpl: string, ...keywords: readonly Primitive[]): string;
+    /**
+     * Formats a list of keywords into a localized, human-readable string.
+     *
+     * @param messageTmpl - An array of keywords to format as a list
+     * @param useLastSeparator - Whether to use the "last separator" (e.g. " and ") before the final item
+     * @returns The formatted list string
+     */
     (messageTmpl: readonly string[], useLastSeparator?: boolean): string;
+    /**
+     * Combined overload accepting either a message template string or a keyword list.
+     *
+     * @param messageTmpl - A message template string or an array of keywords
+     * @param keywords - Values to substitute (when a string template is provided)
+     * @returns The translated or formatted string
+     */
     (messageTmpl: string | readonly string[], ...keywords: readonly Primitive[]): string;
 }
+/**
+ * Configuration for a specific locale, including translations and formatting rules.
+ */
 export type LocaleSet = {
+    /** The locale identifier (e.g. `"en"`, `"ja"`) */
     readonly locale: string;
+    /** Formatting rules for rendering keyword lists */
     readonly listFormat?: ListFormat;
+    /** A dictionary mapping lowercase keywords to their translations */
     readonly keywords?: LocalesKeywords;
+    /** A dictionary mapping lowercase sentence templates to their translations */
     readonly sentences?: LocalesKeywords;
 };
+/**
+ * Formatting rules for rendering a list of items as a human-readable string.
+ */
 export type ListFormat = {
+    /** Character(s) placed before each quoted item (e.g. `"`) */
     readonly quoteStart: string;
+    /** Character(s) placed after each quoted item (e.g. `"`) */
     readonly quoteEnd: string;
+    /** Separator between items (e.g. `", "`) */
     readonly separator: string;
+    /** Separator before the last item (e.g. `" and "`); falls back to `separator` if omitted */
     readonly lastSeparator?: string;
 };
+/**
+ * A primitive value type used as a keyword in translations.
+ */
 export type Primitive = string | number | boolean;
+/**
+ * A dictionary mapping message IDs (lowercase) to their translated strings.
+ */
 export type LocalesKeywords = {
     readonly [messageId: string]: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/i18n",
-	"version": "4.7.0",
+	"version": "4.7.1",
 	"description": "Internationalization for markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
@@ -38,5 +38,5 @@
 		"clean:esm": "tsc --build --clean tsconfig.build.json",
 		"clean:cjs": "tsc --build --clean tsconfig.build-cjs.json"
 	},
-	"gitHead": "acbf53f7e30d7a59f850a0f279b617383266dab3"
+	"gitHead": "193ee7c1262bbed95424e38efdf1a8e56ff049f4"
 }