chore: translate Japanese comments and docs to English

.coderabbit.yaml

@@ -1,9 +1,9 @@
 # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
-language: ja
+language: en-US
 early_access: false
 tone_instructions: |
-  日本語で簡潔かつ建設的にレビューしてください。
-  指摘の根拠（PHPのバージョン依存、型安全性、Result型の不変条件など）を明示してください。
+  Review concisely and constructively.
+  Make the rationale for each comment explicit (PHP version dependencies, type safety, Result type invariants, etc.).
 
 reviews:
   profile: assertive
@@ -29,24 +29,24 @@ reviews:
   path_instructions:
     - path: "src/**/*.php"
       instructions: |
-        - PHP 8.4 以上の構文・機能を前提にレビューする。
-        - Rust の Result<T, E> に倣った API 設計を尊重し、Ok / Err / Result の不変条件を崩していないか確認する。
-        - 例外による暗黙のエラー伝播ではなく、Result 型での明示的なエラーハンドリングを推奨する。
-        - readonly / final / 型宣言（戻り値・引数・プロパティ）の徹底をチェックする。
-        - 公開 API の破壊的変更がある場合は明示的に指摘する。
+        - Review assuming PHP 8.4+ syntax and features.
+        - Respect the API design modeled after Rust's Result<T, E>, and check that the Ok / Err / Result invariants are not broken.
+        - Prefer explicit error handling via the Result type over implicit error propagation through exceptions.
+        - Check for thorough use of readonly / final / type declarations (return, parameter, and property types).
+        - Explicitly point out any breaking changes to the public API.
     - path: "tests/**/*.php"
       instructions: |
-        - PHPUnit のテストとして、t-wada 流 TDD の Red→Green→Refactor を意識しているかをチェックする。
-        - 1 テスト 1 アサーション主義に偏りすぎず、振る舞い単位で検証されているか確認する。
-        - エッジケース（Ok/Err 双方、ネスト、map/and_then などのコンビネータ）が網羅されているかを見る。
+        - As PHPUnit tests, check whether they follow t-wada-style TDD's Red→Green→Refactor.
+        - Without over-adhering to one-assertion-per-test dogma, check that they verify behavior units.
+        - Check that edge cases are covered (both Ok/Err, nesting, combinators such as map/and_then).
     - path: "**/*.md"
       instructions: |
-        - サンプルコードは PHP 8.4+ で実行可能か確認する。
-        - README の API 説明と src の実装が一致しているかを確認する。
+        - Check that sample code is runnable on PHP 8.4+.
+        - Check that the README's API descriptions match the implementation in src.
     - path: ".github/workflows/**"
       instructions: |
-        - 使用するアクションはバージョンを固定（SHA か明示的なタグ）しているかを確認する。
-        - secrets の取り扱いに不適切なものがないかをチェックする。
+        - Check that the actions used are version-pinned (by SHA or an explicit tag).
+        - Check for any improper handling of secrets.
 
   tools:
     phpstan:

src/Err.php

@@ -7,7 +7,7 @@
 use Override;
 
 /**
- * Err はエラー値を表します.
+ * Err represents an error value.
  *
  * @template-covariant E
  *

src/Ok.php

@@ -7,7 +7,7 @@
 use Override;
 
 /**
- * Ok は成功値を表します.
+ * Ok represents a success value.
  *
  * @template-covariant T
  *

src/Result.php

@@ -5,21 +5,21 @@
 namespace Valbeat\Result;
 
 /**
- * Result型は、成功（Ok）または失敗（Err）を表現します。
+ * The Result type represents either success (Ok) or failure (Err).
  *
- * 注意: instanceof による絞り込みでは型引数が失われます（PHPStan の既知の制限。
- * Result<int, E> が型引数なしの Ok になり unwrap() は mixed になる）。
- * 値を取り出す分岐では isOk() / isErr() で絞り込んでください。
+ * Note: narrowing via instanceof loses the type arguments (a known PHPStan
+ * limitation; Result<int, E> becomes an Ok without type arguments and unwrap()
+ * returns mixed). In branches that extract the value, narrow with isOk() / isErr().
  *
- * @template-covariant T 成功時の値の型
- * @template-covariant E 失敗時のエラーの型
+ * @template-covariant T the type of the success value
+ * @template-covariant E the type of the error value
  *
  * @phpstan-sealed Ok|Err
  */
 interface Result
 {
     /**
-     * 結果が成功（Ok）の場合に true を返します.
+     * Returns true if the result is a success (Ok).
      *
      * @phpstan-assert-if-true Ok<T> $this
      * @phpstan-assert-if-false Err<E> $this
@@ -29,7 +29,7 @@ interface Result
     public function isOk(): bool;
 
     /**
-     * 結果が成功（Ok）でありコールバックが true を返す場合に true を返します.
+     * Returns true if the result is a success (Ok) and the callback returns true.
      *
      * @param callable(T): bool $fn
      *
@@ -38,7 +38,7 @@ public function isOk(): bool;
     public function isOkAnd(callable $fn): bool;
 
     /**
-     * 結果が失敗（Err）の場合に true を返します.
+     * Returns true if the result is a failure (Err).
      *
      * @phpstan-assert-if-true Err<E> $this
      * @phpstan-assert-if-false Ok<T> $this
@@ -48,7 +48,7 @@ public function isOkAnd(callable $fn): bool;
     public function isErr(): bool;
 
     /**
-     * 結果が失敗（Err）でありコールバックが true を返す場合に true を返します.
+     * Returns true if the result is a failure (Err) and the callback returns true.
      *
      * @param callable(E): bool $fn
      *
@@ -57,47 +57,47 @@ public function isErr(): bool;
     public function isErrAnd(callable $fn): bool;
 
     /**
-     * 成功値を返します。失敗の場合は例外を投げます.
+     * Returns the success value. Throws an exception on failure.
      *
      * @return ($this is Ok<mixed> ? T : never)
      *
-     * @throws UnwrapException $this が Err の場合
+     * @throws UnwrapException if $this is Err
      */
     public function unwrap(): mixed;
 
     /**
-     * エラー値を返します。成功の場合は例外を投げます.
+     * Returns the error value. Throws an exception on success.
      *
      * @return ($this is Err<mixed> ? E : never)
      *
-     * @throws UnwrapException $this が Ok の場合
+     * @throws UnwrapException if $this is Ok
      */
     public function unwrapErr(): mixed;
 
     /**
-     * 成功値を返します。失敗の場合は指定したメッセージで例外を投げます.
+     * Returns the success value. On failure, throws an exception with the given message.
      *
-     * @param string $message 失敗時の例外メッセージ（エラー値の要約が付加されます）
+     * @param string $message the exception message on failure (a summary of the error value is appended)
      *
      * @return ($this is Ok<mixed> ? T : never)
      *
-     * @throws UnwrapException $this が Err の場合
+     * @throws UnwrapException if $this is Err
      */
     public function expect(string $message): mixed;
 
     /**
-     * エラー値を返します。成功の場合は指定したメッセージで例外を投げます.
+     * Returns the error value. On success, throws an exception with the given message.
      *
-     * @param string $message 成功時の例外メッセージ（成功値の要約が付加されます）
+     * @param string $message the exception message on success (a summary of the success value is appended)
      *
      * @return ($this is Err<mixed> ? E : never)
      *
-     * @throws UnwrapException $this が Ok の場合
+     * @throws UnwrapException if $this is Ok
      */
     public function expectErr(string $message): mixed;
 
     /**
-     * 成功値またはデフォルト値を返します.
+     * Returns the success value or a default value.
      *
      * @template U
      * @param U $default
@@ -106,7 +106,7 @@ public function expectErr(string $message): mixed;
     public function unwrapOr(mixed $default): mixed;
 
     /**
-     * 成功値またはクロージャーの結果を返します.
+     * Returns the success value or the result of the closure.
      *
      * @template U
      * @param callable(E): U $fn
@@ -116,7 +116,7 @@ public function unwrapOr(mixed $default): mixed;
     public function unwrapOrElse(callable $fn): mixed;
 
     /**
-     * 成功値に関数を適用します.
+     * Applies a function to the success value.
      *
      * @template U
      *
@@ -127,7 +127,7 @@ public function unwrapOrElse(callable $fn): mixed;
     public function map(callable $fn): self;
 
     /**
-     * エラー値に関数を適用します.
+     * Applies a function to the error value.
      *
      * @template F
      *
@@ -138,7 +138,7 @@ public function map(callable $fn): self;
     public function mapErr(callable $fn): self;
 
     /**
-     * 成功値に副作用を適用します.
+     * Applies a side effect to the success value.
      *
      * @param callable(T): void $fn
      *
@@ -147,7 +147,7 @@ public function mapErr(callable $fn): self;
     public function inspect(callable $fn): self;
 
     /**
-     * エラー値に副作用を適用します.
+     * Applies a side effect to the error value.
      *
      * @param callable(E): void $fn
      *
@@ -156,7 +156,7 @@ public function inspect(callable $fn): self;
     public function inspectErr(callable $fn): self;
 
     /**
-     * 成功値に関数を適用するか、デフォルト値を返します.
+     * Applies a function to the success value, or returns a default value.
      *
      * @template U
      *
@@ -168,7 +168,7 @@ public function inspectErr(callable $fn): self;
     public function mapOr(mixed $default, callable $fn): mixed;
 
     /**
-     * 成功値に関数を適用するか、クロージャーの結果を返します.
+     * Applies a function to the success value, or returns the result of the closure.
      *
      * @template U
      *
@@ -180,7 +180,7 @@ public function mapOr(mixed $default, callable $fn): mixed;
     public function mapOrElse(callable $defaultFn, callable $fn): mixed;
 
     /**
-     * 成功の場合は第2の結果を返し、失敗の場合は最初のエラーを返します.
+     * Returns the second result on success, or the first error on failure.
      *
      * @template U
      * @template F
@@ -192,9 +192,9 @@ public function mapOrElse(callable $defaultFn, callable $fn): mixed;
     public function and(self $res): self;
 
     /**
-     * 成功の場合は関数を適用し、失敗の場合は現在のエラーを返します.
+     * Applies a function on success, or returns the current error on failure.
      *
-     * 関数は元と異なるエラー型を返せます。エラー型は E|F に合成されます.
+     * The function may return a different error type; the error type is combined into E|F.
      *
      * @template U
      * @template F
@@ -206,7 +206,7 @@ public function and(self $res): self;
     public function andThen(callable $fn): self;
 
     /**
-     * 失敗の場合は第2の結果を返し、成功の場合は最初の値を返します.
+     * Returns the second result on failure, or the first value on success.
      *
      * @template U
      * @template F
@@ -218,9 +218,9 @@ public function andThen(callable $fn): self;
     public function or(self $res): self;
 
     /**
-     * 失敗の場合は関数を適用し、成功の場合は現在の値を返します.
+     * Applies a function on failure, or returns the current value on success.
      *
-     * 関数は元と異なる成功型を返せます。成功型は T|U に合成されます.
+     * The function may return a different success type; the success type is combined into T|U.
      *
      * @template U
      * @template F
@@ -232,15 +232,15 @@ public function or(self $res): self;
     public function orElse(callable $fn): self;
 
     /**
-     * 成功の場合はokを、失敗の場合はerrを適用します.
+     * Applies ok on success, or err on failure.
      *
      * @template U
      * @template V
      *
-     * @param callable(T): U $ok 成功値に適用する関数
-     * @param callable(E): V $err エラー値に適用する関数
+     * @param callable(T): U $ok the function applied to the success value
+     * @param callable(E): V $err the function applied to the error value
      *
-     * @return U|V 適用された関数の結果
+     * @return U|V the result of the applied function
      */
     public function match(callable $ok, callable $err): mixed;
 }

src/Results.php

@@ -5,12 +5,12 @@
 namespace Valbeat\Result;
 
 /**
- * Result を生成・合成する静的ヘルパーです.
+ * Static helpers for creating and composing Results.
  */
 final class Results
 {
     /**
-     * 静的ヘルパーのためインスタンス化を禁止します.
+     * Prevents instantiation since this is a static helper.
      *
      * @codeCoverageIgnore
      */
@@ -19,10 +19,10 @@ private function __construct()
     }
 
     /**
-     * 例外を投げうる処理を実行し、結果を Result に包みます.
+     * Executes a callable that may throw and wraps the result in a Result.
      *
-     * 成功時は戻り値を Ok に、\Throwable が送出された場合は Err に包んで返します.
-     * 例外ベースの既存コードを Result の世界に持ち込む入口として使います.
+     * On success the return value is wrapped in Ok; if a \Throwable is thrown it is wrapped in Err.
+     * Use it as an entry point for bringing existing exception-based code into the Result world.
      *
      * @template T
      *
@@ -40,9 +40,9 @@ public static function try(callable $fn): Result
     }
 
     /**
-     * 複数の Result を 1 つに合成します.
+     * Combines multiple Results into one.
      *
-     * すべて成功なら値のリストを Ok で返し、失敗が含まれる場合は最初の Err を返します.
+     * If all are successes, returns the list of values as an Ok; if any failure is present, returns the first Err.
      *
      * @template T
      * @template E
@@ -65,11 +65,11 @@ public static function combine(iterable $results): Result
     }
 
     /**
-     * ネストした Result を 1 段平坦化します.
+     * Flattens a nested Result by one level.
      *
-     * インスタンスメソッドにしないのは、PHPStan の条件型ではテンプレート T を
-     * Result<U, F> に分解できない（infer がない）ため。静的ヘルパーなら
-     * パラメータ側のテンプレートで内側の型を正確に推論できます.
+     * This is not an instance method because PHPStan's conditional types cannot
+     * decompose the template T into Result<U, F> (there is no infer). As a static
+     * helper, the inner type can be inferred precisely from the parameter-side template.
      *
      * @template T
      * @template E1