---
title: 使い方
description: エラークラスの定義、メッセージ登録、言語切り替え、prefix、フォールバックの基本操作です。
---

## 基本の流れ [#basic-flow]

1. **エラークラスを定義する**

    `I18nErrorBase<TMeta>` を継承し、メッセージ生成用の情報を `TMeta` に定義します。

2. **言語ごとのメッセージを登録する**

    `setErrorMessage` でクラスと言語に対応するメッセージを登録します。

3. **言語を切り替えて message を読む**

    `setGlobalConfig({ lang })` で切り替え、`error.message` を読みます。

```ts
import { setGlobalConfig } from "valibot";
import { I18nErrorBase, setErrorMessage } from "i18n-error-base";

class BusinessRuleError extends I18nErrorBase<{ code: string; limit: number }> {
  public constructor(meta: { code: string; limit: number }) {
    super(meta, ({ code, limit }) => `Code: ${code}, Limit: ${limit}`);
  }
}

setErrorMessage(
  BusinessRuleError,
  ({ code, limit }) => `コード: ${code}、制限: ${limit}`,
  "ja",
);

const error = new BusinessRuleError({ code: "ERR", limit: 50 });

setGlobalConfig({ lang: "ja" });
console.log(error.message); // コード: ERR、制限: 50

setGlobalConfig({ lang: "en" });
console.log(error.message); // Code: ERR, Limit: 50
```

## エラークラスを定義する [#define-error-class]

`TMeta` はメッセージ生成用の付随情報です。`error.meta` に保持され、登録関数にも渡されます。

```ts
import { I18nErrorBase } from "i18n-error-base";

class NotFoundError extends I18nErrorBase<{ resource: string }> {}

const error = new NotFoundError({ resource: "user" }, "fallback message");
console.log(error.meta); // { resource: "user" }
```

第 2 引数は文字列か `(meta) => string` です。第 3 引数は `Error` と同じ `{ cause }` などです。

```ts
class TestError extends I18nErrorBase<{ code: string }> {}

const cause = new Error("original");
const error = new TestError({ code: "ERR" }, "something went wrong", { cause });
console.log(error.cause === cause); // true
```

`TMeta` を `undefined` にすると `meta` を省略できます。

```ts
class NoMetaError extends I18nErrorBase<undefined> {}

const a = new NoMetaError("no meta");
const b = new NoMetaError(undefined, "no meta");
console.log(a.meta); // undefined
```

:::note
直接 `new` せず、必ず継承して使ってください。登録はクラスごとのため、親への登録は子に引き継がれません。
:::

## メッセージを登録する [#register-message]

`setErrorMessage` でクラスと言語ごとの生成関数を登録します。

```ts
import { I18nErrorBase, setErrorMessage } from "i18n-error-base";

class TestError extends I18nErrorBase<{ code: string }> {}

setErrorMessage(TestError, ({ code }) => `エラーコード: ${code}`, "ja");
setErrorMessage(TestError, "something went wrong", "en");
```

文字列も指定できます。言語は配列でも指定できます。

```ts
const message = ({ code }: { code: string }) => `エラーコード: ${code}`;
setErrorMessage(TestError, message, ["ja", "ko", "zh"]);
```

同じクラスと言語への再登録は上書きされます。`instanceof` ではなく、登録時と参照時のコンストラクターが一致したときだけ使います。

:::warning[登録前のアクセスに注意]
`message` を先に読むと既定値で固定されます。登録はインスタンス生成より前に済ませてください。
:::

## 言語を切り替える [#switch-language]

Valibot のグローバル設定で切り替えます。`message` は読むたびに現在の `lang` を参照します。

```ts
import { setGlobalConfig } from "valibot";

setGlobalConfig({ lang: "ja" });
console.log(error.message); // 日本語の登録メッセージ

setGlobalConfig({ lang: "en" });
console.log(error.message); // 英語の登録メッセージまたは既定メッセージ
```

未設定の `lang` は `"en"` です。未登録の言語はコンストラクターの既定メッセージを使います。

```ts
setErrorMessage(BusinessRuleError, () => "日本語メッセージ", "ja");

setGlobalConfig({ lang: "fr" });
console.log(error.message); // "Code: ERR, Limit: 50"（既定メッセージ）
```

## 接頭辞を付ける [#prefix]

`static prefix` は解決後の先頭に付けます。翻訳・既定のどちらにも適用されます。

```ts
class PrefixedError extends I18nErrorBase<{ code: string }> {
  static {
    this.prefix = "[ERROR] ";
  }
}

setErrorMessage(PrefixedError, ({ code }) => `code is ${code}`, "ja");
const error = new PrefixedError({ code: "ERR" }, "fallback");

setGlobalConfig({ lang: "ja" });
console.log(error.message); // "[ERROR] code is ERR"

setGlobalConfig({ lang: "en" });
console.log(error.message); // "[ERROR] fallback"
```

未設定ならそのまま返ります。

## Error としての振る舞い [#error-behavior]

- `error instanceof Error`、`instanceof I18nErrorBase`、`instanceof 具象クラス` のいずれも `true` です。
- `String(error)` / `error.toString()` は解決後のメッセージを含みます（例: `"Error: ..."`）。
- `cause` を `{ cause }` で保持します。

## よくあるパターン [#common-patterns]

### 既定メッセージをコンストラクターで固定する [#fix-default-message-in-constructor]

```ts
class BusinessRuleError extends I18nErrorBase<{ code: string; limit: number }> {
  public constructor(meta: { code: string; limit: number }, options?: ErrorOptions) {
    super(meta, ({ code, limit }) => `Code: ${code}, Limit: ${limit}`, options);
  }
}
```

呼び出し側は `meta` だけ渡せばよく、既定文の重複を避けられます。

### 複数言語をまとめて登録する [#register-multiple-languages]

```ts
setErrorMessage(MyError, "エラーが発生しました", ["ja"]);
setErrorMessage(MyError, "An error occurred", ["en", "en-US"]);
```

言語コードは正規化しません。`"en"` と `"en-US"` は別キーのため、必要なコードを明示的に登録してください。