diff --git a/.github/docs/templates/online.twig b/.github/docs/templates/online.twig
index 70f98efe..dd06c807 100644
--- a/.github/docs/templates/online.twig
+++ b/.github/docs/templates/online.twig
@@ -65,7 +65,7 @@
 
         <ul class="nav nav-pills" id="docs-side-nav">
             {% for page in pages %}
-            {% if page.slug != 'pie-maintainers-handbook' %}
+            {% if page.slug != 'pie-maintainers-handbook' and page.slug[:3] != 'ja_' and page.slug[:3] != 'zh_' %}
             <li class="nav-item"><a href="#docs/{{ page.slug }}" class="nav-link fragmentRoute">{{ page.title }}</a></li>
             {% endif %}
             {% endfor %}
diff --git a/.gitignore b/.gitignore
index 49bf644b..1eb5695f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,4 @@ box.phar
 pie.phar
 /docs-package/
 CHANGELOG-*.md
+/.idea/
\ No newline at end of file
diff --git a/docs/ja/README.md b/docs/ja/README.md
new file mode 100644
index 00000000..86690c52
--- /dev/null
+++ b/docs/ja/README.md
@@ -0,0 +1,116 @@
+---
+en-revision: b595732a62673b53c2509dfeab38a71ee16c88f4
+---
+> [!WARNING]
+> This translation may not be based on the latest version, please ensure you
+> check the original English version for discrepancies.
+
+# 🥧 PIE (PHP 拡張機能インストーラー)
+
+## PIE とは？
+
+PIE は PHP 拡張機能の新しいインストーラーで、最終的に PECL を置き換えることを目的としています。
+[PHAR](https://www.php.net/manual/en/intro.phar.php) として配布され、
+Composer と同様に動作しますが、PHP パッケージをプロジェクトやライブラリに
+取り込むのではなく、PHP 拡張機能（PHP モジュールまたは Zend 拡張機能）を
+PHP インストールにインストールします。
+
+# PIE の使用 - 始めるために何が必要ですか？
+
+## 前提条件
+
+PIE を実行するには PHP 8.1 以降が必要ですが、PIE は他のインストール済み PHP バージョンに
+拡張機能をインストールできます。
+
+Linux では、ビルドツールチェーンをインストールする必要があります。Debian/Ubuntu タイプの
+システムでは、次のようなコマンドを実行できます：
+
+```shell
+sudo apt install gcc make autoconf libtool bison re2c pkg-config php-dev
+```
+
+Windows では、ビルドツールチェーンをインストールする必要はありません。Windows の PHP 拡張機能は
+拡張機能 DLL を含むプリコンパイル済みパッケージとして配布されるためです。
+
+## PIE のインストール
+
+- `pie.phar` をダウンロードします：
+  - [最新の安定版リリース](https://github.com/php/pie/releases)
+  - [最新の不安定なナイトリービルド](https://php.github.io/pie/pie-nightly.phar)
+- `gh attestation verify --owner php pie.phar` で PHAR の出所を確認します
+- その後、`php pie.phar <command>` で PIE を呼び出すことができます
+
+インストールの詳細については、[使用法](./docs/usage.md) ドキュメントを参照してください。
+このドキュメントでは、`pie.phar` を `$PATH` に移動したことを前提としています（例：非 Windows システムでは `/usr/local/bin/pie`）。
+
+## PIE を使用して単一の拡張機能をインストール
+
+`install` コマンドを使用して拡張機能をインストールできます。例えば、`example_pie_extension` 拡張機能を
+インストールするには、次を実行します：
+
+```shell
+$ pie install example/example-pie-extension
+このコマンドには管理者権限が必要な場合があり、パスワードの入力を求められることがあります。
+実行中の PHP: 8.3.10
+ターゲット PHP インストール: 8.3.10 nts、Linux/OSX/etc x86_64（/usr/bin/php8.3 から）
+パッケージが見つかりました: example/example-pie-extension:1.0.1（ext-example_pie_extension を提供）
+phpize 完了。
+設定完了。
+ビルド完了: /tmp/pie_downloader_66e0b1de73cdb6.04069773/example-example-pie-extension-769f906/modules/example_pie_extension.so
+インストール完了: /usr/lib/php/20230831/example_pie_extension.so
+php.ini に "extension=example_pie_extension" を追加する必要があります
+$
+```
+
+## PHP プロジェクトのすべての拡張機能をインストール
+
+PHP プロジェクト内で、不足しているトップレベルの拡張機能をインストールできます：
+
+```
+$ pie install
+🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
+実行中の PHP: 8.3.19
+ターゲット PHP インストール: 8.3.19 nts、Linux/OSX/etc x86_64（/usr/bin/php8.3 から）
+プロジェクト your-vendor/your-project の拡張機能を確認中
+requires: curl ✅ 既にインストール済み
+requires: intl ✅ 既にインストール済み
+requires: json ✅ 既にインストール済み
+requires: example_pie_extension ⚠️  不足
+
+以下のパッケージが適切です。どれをインストールしますか：
+  [0] なし
+  [1] asgrim/example-pie-extension: Example PIE extension
+ > 1
+   > 🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
+   > このコマンドには管理者権限が必要な場合があり、パスワードの入力を求められることがあります。
+   > 実行中の PHP: 8.3.19
+   > ターゲット PHP インストール: 8.3.19 nts、Linux/OSX/etc x86_64（/usr/bin/php8.3 から）
+   > パッケージが見つかりました: asgrim/example-pie-extension:2.0.2（ext-example_pie_extension を提供）
+   ... (省略) ...
+   > ✅ 拡張機能は /usr/bin/php8.3 で有効化され、読み込まれています
+
+拡張機能の確認が完了しました。
+```
+
+## PIE をサポートする拡張機能
+
+PIE をサポートする拡張機能のリストは
+[https://packagist.org/extensions](https://packagist.org/extensions) で確認できます。
+
+# バグ、機能のアイデア、質問、ヘルプが必要など
+
+ - アイデア、質問、またはヘルプが必要な場合は、[ディスカッション](https://github.com/php/pie/discussions) を使用してください。
+   - **新機能を貢献する前に、まずご連絡ください** - これは
+     すでに開発中の可能性があります。PHP Foundation も積極的に
+     これを開発しており、すでにパイプラインに新しい機能があります...
+ - 報告するバグがある場合は、[Issues](https://github.com/php/pie/issues) を使用してください。
+
+# 拡張機能のメンテナーです - PIE サポートを追加するにはどうすればよいですか？
+
+拡張機能のメンテナーで、拡張機能に PIE サポートを追加したい場合は、
+[拡張機能メンテナー](./docs/extension-maintainers.md) を読んでください。
+
+## その他のドキュメント...
+
+PIE の完全なドキュメントは [使用法](./docs/usage.md) ドキュメントにあります。
+
diff --git a/docs/ja/extension-maintainers.md b/docs/ja/extension-maintainers.md
new file mode 100644
index 00000000..7290a4f3
--- /dev/null
+++ b/docs/ja/extension-maintainers.md
@@ -0,0 +1,351 @@
+---
+title: 拡張機能メンテナー
+order: 3
+en-revision: b595732a62673b53c2509dfeab38a71ee16c88f4
+---
+> [!WARNING]
+> This translation may not be based on the latest version, please ensure you
+> check the original English version for discrepancies.
+
+# PIE 拡張機能メンテナーガイド
+
+## PIE のビルドとインストール手順
+
+### 非 Windows（例：Linux、OSX など）
+
+PIE は通常の [PHP 拡張機能のビルドとインストールプロセス](https://www.php.net/manual/ja/install.pecl.phpize.php)に従います：
+
+ * `phpize` で PHP API パラメータを設定します。拡張機能をインストールする人は、`phpize` がパスにない場合 `--with-phpize-path` を指定できます。
+ * `./configure` で特定のシステムのビルドパラメータとライブラリを設定します。拡張機能をインストールする人は、`composer.json` で指定した設定オプションを指定できます。これを行う方法については、[設定オプション](#configure-options)ドキュメントを参照してください。
+ * `make` で実際に拡張機能をビルドします。これは実行する並列プロセスの数を自動的に検出しようとしますが、インストールする人は `--make-parallel-jobs N` または `-jN` オプションでこれをオーバーライドできます。
+ * `make install` で設定された PHP インストールに拡張機能をインストールします。PIE がインストール場所への書き込み権限を持っていない場合、`sudo` で権限を昇格しようとします。
+
+これは、PIE を実行しているシステムに適切なビルドツールがインストールされている必要があることを意味します。拡張機能のビルドと PHP の内部動作に関する有用なリソースは [PHP Internals Book](https://www.phpinternalsbook.com/) です。
+
+### Windows
+
+Windows システムの場合、拡張機能メンテナーはプリビルドされたバイナリを提供する必要があります。PIE 用に正しい方法でこれを行う方法の詳細については、以下の [Windows サポート](#windows-support)セクションを参照してください。
+
+## 拡張機能に PIE サポートを追加する方法
+
+拡張機能に PIE サポートを追加することは比較的簡単で、通常の PHP パッケージを Packagist に追加するのと非常に似ています。
+
+### すでに PECL にある拡張機能
+
+既存の PECL 拡張機能のメンテナーの場合、以下はコンテキストのための有用な情報です：
+
+ - すでに PECL にある拡張機能の場合、PECL への公開を続けたくない場合、`package.xml` は不要です。今すぐ PECL への公開を続けたい場合は、`package.xml` を維持し続けることができます。
+ - `package.xml` は各リリースを明示的にリストします。PIE では、Packagist が通常の Composer パッケージと同じ方法でタグまたはブランチエイリアスを取得するため、これは不要になりました。これは、パッケージをリリースするには、タグとリリースをプッシュする必要があることを意味します。
+ - デフォルトの設定では、パッケージの内容はリリースのタグまたはリビジョンの [Git archive](https://git-scm.com/docs/git-archive) によって決定されます。[export-ignore](https://git-scm.com/docs/git-archive#Documentation/git-archive.txt-export-ignore) 属性を使用して、アーカイブからファイルとパスを除外できます。
+
+### 拡張機能に `composer.json` を追加
+
+PIE サポートを追加する最初のステップは、拡張機能リポジトリに `composer.json` を追加することです。ほとんどの典型的なフィールドは通常の Composer パッケージと同じですが、いくつかの注目すべき例外があります：
+
+ * `type` は PHP モジュールの場合は `php-ext`（これがほとんどの拡張機能になります）、または Zend 拡張機能の場合は `php-ext-zend` である必要があります。
+ * 追加の `php-ext` セクションが存在する可能性があります（`php-ext` 内に含めることができるディレクティブについては以下を参照）
+ * Composer パッケージ名（つまりトップレベルの `name` フィールド）は、通常の Composer パッケージ名形式に従う必要があります。つまり `<vendor>/<package>` です。
+ * ただし、PIE 拡張機能の Composer パッケージ名は、`type` フィールドが異なる場合でも、通常の PHP パッケージと同じ Composer パッケージ名を共有してはなりません。
+
+#### `php-ext` 定義
+
+##### `extension-name`
+
+`extension-name` を指定することができ、[\Php\Pie\ExtensionName::VALID_PACKAGE_NAME_REGEX](../src/ExtensionName.php) で定義されている通常の拡張機能名正規表現に準拠する必要があります。`extension-name` が指定されていない場合、`extension-name` は Composer パッケージ名から派生し、ベンダープレフィックスが削除されます。例えば、次の `composer.json` の場合：
+
+```json
+{
+    "name": "myvendor/myextension"
+}
+```
+
+拡張機能名は `myextension` として派生されます。`myvendor/` ベンダープレフィックスは削除されます。
+
+> [!WARNING]
+> Composer パッケージ名が無効な PHP 拡張機能名になる場合、`extension-name` ディレクティブを指定する必要があります。例えば、Composer パッケージ名 `myvendor/my-extension` はハイフンが許可されていないため無効な PHP 拡張機能名になるため、この Composer パッケージ名には有効な `extension-name` を指定する必要があります。
+
+`extension-name` は、Composer で `require` を使用する際の慣例である `ext-` でプレフィックスを付けるべきではありません。
+
+`extension-name` の使用例：
+
+```json
+{
+    "name": "xdebug/xdebug",
+    "php-ext": {
+        "extension-name": "xdebug"
+    }
+}
+```
+
+##### `priority`
+
+`priority` は `ini` ファイル名の一部を形成し、ターゲットプラットフォームがディレクトリ内の複数の INI ファイルを使用する場合、拡張機能の順序を制御します。
+
+##### `support-zts` と `support-nts`
+
+拡張機能が Zend Thread-Safe（ZTS）および非スレッドセーフ（NTS）モードをサポートするかどうかを示します。これらのフラグは指定されていない場合、両方ともデフォルトで `true` ですが、拡張機能がいずれかのモードをサポートしていない場合は指定する必要があり、ターゲットプラットフォームに拡張機能をインストールできないことを意味します。
+
+理論的には、`support-zts` と `support-nts` の両方に `false` を指定することは可能ですが、これはパッケージをどこにもインストールできないことを意味するため、推奨されません。
+
+##### `configure-options`
+
+これは `./configure` コマンドに渡すことができるパラメータのリストです。リストの各項目は次の JSON オブジェクトです：
+
+ * `name`、パラメータ名自体
+ * `description`、パラメータが何をするかの役立つ説明
+ * オプションで `needs-value`、PIE にパラメータが単純なフラグ（通常 `--enable-this-flag` タイプのパラメータに使用）か、パラメータに値を指定する必要があるか（通常 `--with-library-path=...` タイプのパラメータに使用され、エンドユーザーが値を指定する必要がある）を伝えるブール値
+
+エンドユーザーが PIE で拡張機能をインストールする場合、`./configure` に渡される定義済みの `configure-options` を指定できます。例えば、拡張機能が次の `composer.json` を定義している場合：
+
+```json
+{
+    "name": "myvendor/myext",
+    "php-ext": {
+        "extension-name": "myext",
+        "configure-options": [
+            {
+                "name": "enable-my-flag",
+                "description": "Should my flag be enabled",
+                "needs-value": false
+            },
+            {
+                "name": "with-some-lib",
+                "description": "Specify the path to some-lib",
+                "needs-value": true
+            }
+        ]
+    }
+}
+```
+
+次のように `pie build` または `pie install` コマンドを呼び出して、目的の設定を実現できます：
+
+ * `pie install myvendor/myext`
+   * これは単にパラメータなしで `./configure` を呼び出します
+ * `pie install myvendor/myext --enable-my-flag`
+   * これは `./configure --enable-my-flag` を呼び出します
+ * `pie install myvendor/myext --with-some-lib=/path/to/somelib`
+   * これは `./configure --with-some-lib=/path/to/somelib` を呼び出します
+ * `pie install myvendor/myext --enable-my-flag --with-some-lib=/path/to/somelib`
+   * これは `./configure --enable-my-flag --with-some-lib=/path/to/somelib` を呼び出します
+
+PIE のエンドユーザーは、拡張機能の `configure-options` 定義で定義されていない設定オプションを指定することはできません。上記と同じ `composer.json` の例を使用して、無効なオプションで PIE を呼び出す場合、例えば `pie install myvendor/myext --something-else` はエラー `The "--something-else" option does not exist.` になります。
+
+エンドユーザーが `configure-options` 定義で定義されたフラグを指定しない場合、それは `./configure` に渡されません。`configure-options` 定義でデフォルト値を指定する方法はありません。`config.m4` でこれに応じて処理する必要があります。
+
+##### `build-path`
+
+ソースコードがリポジトリのルートにない場合、`build-path` 設定を使用できます。例えば、リポジトリ構造が次のような場合：
+
+```text
+/
+  docs/
+  src/
+    config.m4
+    config.w32
+    myext.c
+    ...etc
+```
+
+この場合、実際の拡張機能ソースコードは `src/` でビルドされるため、`build-path` でこのパスを指定する必要があります：
+
+```json
+{
+    "name": "myvendor/myext",
+    "php-ext": {
+        "extension-name": "myext",
+        "build-path": "src"
+    }
+}
+```
+
+`build-path` には、置き換えられるテンプレート値を含めることができます：
+
+ * `{version}` はパッケージバージョンに置き換えられます。例えば、バージョン 1.2.3 のパッケージで `build-path` が `myext-{version}` の場合、実際のビルドパスは `myext-1.2.3` になります。
+
+##### `download-url-method`
+
+`download-url-method` ディレクティブにより、拡張機能メンテナーはソースパッケージのダウンロード動作を変更できます。
+
+ * これを `composer-default` に設定すると（指定されていない場合のデフォルト値）、Composer によって実装されたデフォルトの動作が使用されます。これは、GitHub API（または他のソースコントロールシステム）からの標準 ZIP アーカイブを使用することです。
+ * `pre-packaged-source` を使用すると、次の命名規則のいずれかに一致するリリースアセットリストでソースコードパッケージを見つけます：
+   * `php_{ExtensionName}-{Version}-src.tgz`（例：`php_myext-1.20.1-src.tgz`）
+   * `php_{ExtensionName}-{Version}-src.zip`（例：`php_myext-1.20.1-src.zip`）
+   * `{ExtensionName}-{Version}.tgz`（これは PECL パッケージとの後方互換性のため）
+
+##### `os-families` 制限
+
+`os-families` および `os-families-exclude` ディレクティブにより、拡張機能メンテナーはオペレーティングシステムの互換性を制限できます。
+
+ * `os-families` 拡張機能と互換性があるとマークする OS ファミリーの配列。（例：`"os-families": ["windows"]` は Windows でのみ利用可能な拡張機能）
+ * `os-families-exclude` 拡張機能と互換性がないとマークする OS ファミリーの配列。（例：`"os-families-exclude": ["windows"]` は Windows にインストールできない拡張機能）
+
+受け入れられる OS ファミリーのリスト："windows"、"bsd"、"darwin"、"solaris"、"linux"、"unknown"
+
+> [!WARNING]
+> `os-families` と `os-families-exclude` のうち 1 つだけを定義できます。
+
+#### 拡張機能の依存関係
+
+拡張機能作成者は `require` でいくつかの依存関係を定義できますが、実際には、ほとんどの拡張機能は、拡張機能がサポートする PHP バージョンを除いて、依存関係を定義する必要はありません。他の拡張機能への依存関係（例：`ext-json`）を定義できます。ただし、通常の PHP パッケージ（例：`monolog/monolog`）への依存関係は `require` セクションで指定すべきではありません。
+
+拡張機能が別の依存関係への依存関係を定義し、これが利用できない場合、拡張機能をインストールする人は次のようなメッセージを受け取ります：
+
+```
+Cannot use myvendor/myextension's latest version 1.2.3 as it requires
+ext-something * which is missing from your platform.
+```
+
+#### 拡張機能が動作するかどうかの確認
+
+まず、`composer validate` を使用して `composer.json` が正しくフォーマットされているか確認できます：
+
+```shell
+$ composer validate
+./composer.json is valid
+```
+
+次に、拡張機能のディレクトリで `pie install` を使用して拡張機能をインストールできます：
+
+```shell
+$ cd /path/to/my/extension
+$ pie install
+🥧 PHP Installer for Extensions (PIE) 1.0.0, from The PHP Foundation
+Installing PIE extension from /home/james/workspace/phpf/example-pie-extension
+This command may need elevated privileges, and may prompt you for your password.
+You are running PHP 8.4.8
+Target PHP installation: 8.4.8 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.4)
+Found package: asgrim/example-pie-extension:dev-main which provides ext-example_pie_extension
+Extracted asgrim/example-pie-extension:dev-main source to: /home/james/.config/pie/php8.4_572ee73609adb95bf0b8539fecdc5c0e/vendor/asgrim/example-pie-extension
+Build files cleaned up.
+phpize complete.
+Configure complete.
+Build complete: /home/james/.config/pie/php8.4_572ee73609adb95bf0b8539fecdc5c0e/vendor/asgrim/example-pie-extension/modules/example_pie_extension.so
+Cannot write to /usr/lib/php/20240924, so using sudo to elevate privileges.
+Install complete: /usr/lib/php/20240924/example_pie_extension.so
+✅ Extension is enabled and loaded in /usr/bin/php8.4
+```
+
+##### インストールせずにビルドのみ
+
+アプリケーションのビルドをテストするだけで、ターゲット PHP バージョンにインストールしない場合、まず拡張機能ディレクトリを「path」タイプのリポジトリとして追加する必要があります：
+
+```shell
+$ cd /path/to/my/extension
+$ pie repository:add path .
+🥧 PHP Installer for Extensions (PIE) 1.0.0, from The PHP Foundation
+You are running PHP 8.4.8
+Target PHP installation: 8.4.8 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.4)
+The following repositories are in use for this Target PHP:
+  - Path Repository (/home/james/workspace/phpf/example-pie-extension)
+  - Packagist
+```
+
+次に、ビルドをテストできます：
+
+```shell
+$ pie build asgrim/example-pie-extension:*@dev
+```
+
+> [!TIP]
+> 拡張機能がまだ Packagist に公開されていないため、バージョン制約として `*@dev` を指定する必要があります。そうしないと、デフォルトの安定性が `stable` であるため、PIE は拡張機能を見つけられません。
+
+### Packagist に拡張機能を提出
+
+`composer.json` をリポジトリにコミットしたら、他のパッケージと同じように Packagist に提出できます。
+
+ * [https://packagist.org/packages/submit](https://packagist.org/packages/submit) にアクセス
+ * リポジトリの URL を入力し、指示に従ってください。
+
+### Windows サポート
+
+Windows ユーザーをサポートするには、PIE は現在 DLL をオンザフライでビルドすることをサポートしていないため、プリビルドされた DLL を公開する必要があります。Windows 互換リリースの予想されるワークフローは次のとおりです：
+
+ - GitHub でリリースが行われます（現時点では GitHub のみサポート）
+ - CI パイプラインが実行され、リリースアセットをビルドします（例：GitHub Action）
+ - 結果のビルドアセットが ZIP ファイルとして GitHub リリースに公開されます
+
+ZIP ファイルの名前とその中に含まれる DLL は次のようにする必要があります：
+
+* `php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.zip`
+* 例：`php_xdebug-3.3.2-8.3-ts-vs16-x86_64.zip`
+
+これらの項目の説明：
+
+* `extension-name` 拡張機能名、例：`xdebug`
+* `tag` 例：`3.3.0alpha3` - 作成したタグ/リリースで定義
+* `php-maj/min` - 例：PHP 8.3.* の場合は `8.3`
+* `compiler` - 通常 `vc6`、`vs16` のようなもの - `php -i` の 'PHP Extension Build' フラグから取得
+* `ts|nts` - スレッドセーフまたは非スレッドセーフ
+* `arch` - 例：`x86_64`
+   * Windows：`php -i` の `Architecture` からヒントを使用（下記参照）
+   * 非 Windows：`PHP_INT_SIZE` を確認 - 32 ビットの場合は 4、64 ビットの場合は 8
+
+アーキテクチャ名は正規化が必要な場合があります。異なるプラットフォームでアーキテクチャの名前が異なるためです。PIE は次の正規化されたアーキテクチャを期待します：
+
+ * `x86_64`（`x64`、`x86_64`、`AMD64` から正規化）
+ * `arm64`（`arm64` から正規化）
+ * `x86`（その他の値）
+
+最新のマップ（ドキュメントが最新でない場合）については、`\Php\Pie\Platform\Architecture::parseArchitecture` を確認してください。
+
+#### Windows ZIP の内容
+
+プリビルドされた ZIP には、ZIP 自体と同じ名前の DLL が少なくとも含まれている必要があります。例：`php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.dll`。`.dll` は PHP 拡張機能パスに移動され、名前が変更されます。例：`C:\path\to\php\ext\php_{extension-name}.dll` に移動されます。ZIP ファイルには次のような追加のリソースが含まれる場合があります：
+
+* `php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.pdb` - これは `C:\path\to\php\ext\php_{extension-name}.dll` の隣に移動されます
+* `*.dll` - 他の `.dll` は `C:\path\to\php\php.exe` の隣に移動されます
+* その他のファイルは `C:\path\to\php\extras\{extension-name}\.` に移動されます
+
+#### Windows 公開の自動化
+
+PHP は、拡張機能メンテナーが Windows 互換アセットをビルドおよびリリースできるようにする [一連の GitHub Actions](https://github.com/php/php-windows-builder) を提供しています。これらのアクションを使用するワークフローの例：
+
+```yaml
+name: Publish Windows Releases
+on:
+   release:
+      types: [published]
+
+permissions:
+   contents: write
+
+jobs:
+   get-extension-matrix:
+      runs-on: ubuntu-latest
+      outputs:
+         matrix: ${{ steps.extension-matrix.outputs.matrix }}
+      steps:
+         - name: Checkout
+           uses: actions/checkout@v4
+         - name: Get the extension matrix
+           id: extension-matrix
+           uses: php/php-windows-builder/extension-matrix@v1
+   build:
+      needs: get-extension-matrix
+      runs-on: ${{ matrix.os }}
+      strategy:
+         matrix: ${{fromJson(needs.get-extension-matrix.outputs.matrix)}}
+      steps:
+         - name: Checkout
+           uses: actions/checkout@v4
+         - name: Build the extension
+           uses: php/php-windows-builder/extension@v1
+           with:
+              php-version: ${{ matrix.php-version }}
+              arch: ${{ matrix.arch }}
+              ts: ${{ matrix.ts }}
+   release:
+      runs-on: ubuntu-latest
+      needs: build
+      if: ${{ github.event_name == 'release' }}
+      steps:
+         - name: Upload artifact to the release
+           uses: php/php-windows-builder/release@v1
+           with:
+              release: ${{ github.event.release.tag_name }}
+              token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+出典：[https://github.com/php/php-windows-builder?tab=readme-ov-file#example-workflow-to-build-and-release-an-extension](https://github.com/php/php-windows-builder?tab=readme-ov-file#example-workflow-to-build-and-release-an-extension)
+
diff --git a/docs/ja/pie-maintainers-handbook.md b/docs/ja/pie-maintainers-handbook.md
new file mode 100644
index 00000000..0c46941b
--- /dev/null
+++ b/docs/ja/pie-maintainers-handbook.md
@@ -0,0 +1,65 @@
+---
+title: PIE メンテナーハンドブック
+order: 3
+en-revision: b595732a62673b53c2509dfeab38a71ee16c88f4
+---
+> [!WARNING]
+> This translation may not be based on the latest version, please ensure you
+> check the original English version for discrepancies.
+
+# PIE メンテナーハンドブック
+
+## ブランチ戦略
+
+現在、単一の `main` ブランチと機能ブランチを運用しています。将来、パッチバージョンをより適切にサポートするために、バージョン管理されたブランチ戦略に切り替える可能性があります。
+
+## リリースプロセス
+
+リリースする最新バージョンを持っていることを確認してください。例：
+
+```shell
+# git reset を使用（注意：`main` 上のローカルコミットは破棄されます）
+git checkout main && git fetch upstream && git reset --hard upstream/main
+# または、git pull を使用（マージコミットを避けるために `--ff-only` を使用）
+git checkout main && git pull --ff-only upstream main
+```
+
+変更履歴を準備し、リリースするバージョンとマイルストーンを設定します。例：
+
+```shell
+PIE_VERSION=1.3.0
+PIE_MILESTONE=$PIE_VERSION
+```
+
+> [!TIP]
+> プレリリースの場合、バージョン/マイルストーンを異なる値に設定できます。例：
+>
+> ```shell
+> PIE_VERSION=1.3.0-alpha.2
+> PIE_MILESTONE=1.3.0
+> ```
+>
+> これにより、`1.3.0-alpha.2` バージョンでタグ付け/リリースされますが、変更履歴は GitHub の `1.3.0` マイルストーンに基づいて生成されます。
+
+次に、変更履歴ファイルを生成します：
+
+```shell
+composer require --dev -W jwage/changelog-generator --no-interaction
+vendor/bin/changelog-generator generate --user=php --repository=pie --milestone=$PIE_MILESTONE > CHANGELOG-$PIE_VERSION.md
+git checkout -- composer.*
+composer install
+```
+
+変更履歴の内容に満足しているか確認してください。署名付きタグを作成します：
+
+```shell
+git tag -s $PIE_VERSION -F CHANGELOG-$PIE_VERSION.md
+git push upstream $PIE_VERSION
+```
+
+リリースパイプラインが実行され、**ドラフト**リリースが作成され、PHAR ファイルがビルドされて添付されます。その後、GitHub のドラフトリリースに移動し、すべてが正しいことを確認してから、リリースを公開する必要があります。
+
+```shell
+rm CHANGELOG-$PIE_VERSION.md
+```
+
diff --git a/docs/ja/supported-extensions.md b/docs/ja/supported-extensions.md
new file mode 100644
index 00000000..31e28c9c
--- /dev/null
+++ b/docs/ja/supported-extensions.md
@@ -0,0 +1,475 @@
+---
+title: サポートされている拡張機能
+order: 4
+en-revision: b595732a62673b53c2509dfeab38a71ee16c88f4
+---
+> [!WARNING]
+> This translation may not be based on the latest version, please ensure you
+> check the original English version for discrepancies.
+
+
+# サポートされている拡張機能
+
+Packagist が PIE パッケージの新しいホームであるため、サポートされている PIE 互換拡張機能の完全なリストは以下で確認できます：
+
+* **[https://packagist.org/extensions](https://packagist.org/extensions)**
+
+PIE サポートを追加するプロセスは、[拡張機能メンテナー](extension-maintainers.md)ドキュメントに記載されています。
+
+## PECL 拡張機能の移行
+
+PECL リポジトリには、まだ PIE サポートを追加していない多数の拡張機能があります。これは PECL でホストされている拡張機能のリストと、PIE サポートを追加するためのステータスです。ここに古い情報を見つけた場合は、[Pull Request](https://github.com/php/pie/pulls) を提出してください。
+
+### サポート済み
+
+以下の拡張機能はすでに PIE サポートを追加しています：
+
+| PECL 拡張機能  | PIE 拡張機能                                                                                    |
+|----------------|-----------------------------------------------------------------------------------------------------|
+| amqp           | [php-amqp/php-amqp](https://packagist.org/packages/php-amqp/php-amqp)                               |
+| APCu           | [apcu/apcu](https://packagist.org/packages/apcu/apcu)                                               |
+| apfd           | [m6w6/ext-apfd](https://packagist.org/packages/m6w6/ext-apfd)                                       |
+| ast            | [nikic/php-ast](https://packagist.org/packages/nikic/php-ast)                                       |
+| bcmath         | php/bcmath                                                                                          |
+| bitset         | [pecl/bitset](https://packagist.org/packages/pecl/bitset)                                           |
+| brotli         | [kjdev/brotli](https://packagist.org/packages/kjdev/brotli)                                         |
+| bz2            | php/bz2                                                                                             |
+| calendar       | php/calendar                                                                                        |
+| CSV            | [girgias/csv](https://packagist.org/packages/girgias/csv)                                           |
+| ctype          | php/ctype                                                                                           |
+| curl           | php/curl                                                                                            |
+| dba            | php/dba                                                                                             |
+| decimal        | [php-decimal/ext-decimal](https://packagist.org/packages/php-decimal/ext-decimal)                   |
+| dio            | [pecl/dio](https://packagist.org/packages/pecl/dio)                                                 |
+| dom            | php/dom                                                                                             |
+| ds             | [php-ds/ext-ds](https://packagist.org/packages/php-ds/ext-ds)                                       |
+| enchant        | php/enchant                                                                                         |
+| exif           | php/exif                                                                                            |
+| ev             | [osmanov/pecl-ev](https://packagist.org/packages/osmanov/pecl-ev)                                   |
+| event          | [osmanov/pecl-event](https://packagist.org/packages/osmanov/pecl-event)                             |
+| ffi            | php/ffi                                                                                             |
+| geospatial     | [php-geospatial/geospatial](https://packagist.org/packages/php-geospatial/geospatial)               |
+| gettext        | php/gettext                                                                                         |
+| gmp            | php/gmp                                                                                             |
+| gpio           | [embedded-php/gpio](https://packagist.org/packages/embedded-php/gpio)                               |
+| i2c            | [embedded-php/i2c](https://packagist.org/packages/embedded-php/i2c)                                 |
+| iconv          | php/iconv                                                                                           |
+| imagick        | [imagick/imagick](https://packagist.org/packages/imagick/imagick)                                   |
+| inotify        | [arnaud-lb/inotify](https://packagist.org/packages/arnaud-lb/inotify)                               |
+| intl           | php/intl                                                                                            |
+| jsonpath       | [supermetrics/jsonpath](https://packagist.org/packages/supermetrics/jsonpath)                       |
+| ldap           | php/ldap                                                                                            |
+| mailparse      | [pecl/mailparse](https://packagist.org/packages/pecl/mailparse)                                     |
+| mbstring       | php/mbstring                                                                                        |
+| mcrypt         | [pecl/mcrypt](https://packagist.org/packages/pecl/mcrypt)                                           |
+| memcached      | [php-memcached/php-memcached](https://packagist.org/packages/php-memcached/php-memcached)           |
+| memprof        | [arnaud-lb/memprof](https://packagist.org/packages/arnaud-lb/memprof)                               |
+| mongodb        | [mongodb/mongodb-extension](https://packagist.org/packages/mongodb/mongodb-extension)               |
+| mysqlnd        | php/mysqlnd                                                                                         |
+| mysqli         | php/mysqli                                                                                          |
+| opcache        | php/opcache                                                                                         |
+| opentelemetry  | [open-telemetry/ext-opentelemetry](https://packagist.org/packages/open-telemetry/ext-opentelemetry) |
+| parallel       | [pecl/parallel](https://packagist.org/packages/pecl/parallel)                                       |
+| pcov           | [pecl/pcov](https://packagist.org/packages/pecl/pcov)                                               |
+| pcntl          | php/pcntl                                                                                           |
+| pdo            | php/pdo                                                                                             |
+| pdo_mysql      | php/pdo_mysql                                                                                       |
+| pdo_pgsql      | php/pdo_pgsql                                                                                       |
+| pdo_sqlite     | php/pdo_sqlite                                                                                      |
+| pgsql          | php/pgsql                                                                                           |
+| posix          | php/posix                                                                                           |
+| rdkafka        | [rdkafka/rdkafka](https://packagist.org/packages/rdkafka/rdkafka)                                   |
+| readline       | php/readline                                                                                        |
+| redis          | [phpredis/phpredis](https://packagist.org/packages/phpredis/phpredis)                               |
+| relay          | [cachewerk/relay](https://packagist.org/packages/cachewerk/ext-relay)                               |
+| rpminfo        | [remi/rpminfo](https://packagist.org/packages/remi/rpminfo)                                         |
+| selinux        | [pecl/selinux](https://packagist.org/packages/pecl/selinux)                                         |
+| session        | php/session                                                                                         |
+| shmop          | php/shmop                                                                                           |
+| simdjson       | [awesome/simdjson_plus](https://packagist.org/packages/awesome/simdjson_plus)                       |
+| simplexml      | php/simplexml                                                                                       |
+| snmp           | php/snmp                                                                                            |
+| soap           | php/soap                                                                                            |
+| sockets        | php/sockets                                                                                         |
+| sodium         | php/sodium                                                                                          |                                                                              
+| spi            | [embedded-php/spi](https://packagist.org/packages/embedded-php/spi)                                 |
+| sqlite3        | php/sqlite3                                                                                         |
+| swoole         | [swoole/swoole](https://packagist.org/packages/swoole/swoole)                                       |
+| sysvmsg        | php/sysvmsg                                                                                         |
+| sysvsem        | php/sysvsem                                                                                         |
+| sysvshm        | php/sysvshm                                                                                         |
+| tidy           | php/tidy                                                                                            |
+| timezonedb     | [pecl/timezonedb](https://packagist.org/packages/pecl/timezonedb)                                   |
+| translit       | [derickr/translit](https://packagist.org/packages/derickr/translit)                                 |
+| uart           | [embedded-php/uart](https://packagist.org/packages/embedded-php/uart)                               |
+| uuid           | [pecl/uuid](https://packagist.org/packages/pecl/uuid)                                               |
+| vld            | [derickr/vld](https://packagist.org/packages/derickr/vld)                                           |
+| win32service   | [win32service/win32service](https://packagist.org/packages/win32service/win32service)               |
+| xattr          | [pecl/xattr](https://packagist.org/packages/pecl/xattr)                                             |
+| Xdebug         | [xdebug/xdebug](https://packagist.org/packages/xdebug/xdebug)                                       |
+| xlswriter      | [viest/xlswriter](https://packagist.org/packages/viest/xlswriter)                                   |
+| xml            | php/xml                                                                                             |
+| xmlreader      | php/xmlreader                                                                                       |
+| xmlwriter      | php/xmlwriter                                                                                       |
+| xsl            | php/xsl                                                                                             |
+| xpass          | [remi/xpass](https://packagist.org/packages/remi/xpass)                                             |
+| zip            | php/zip, [pecl/zip](https://packagist.org/packages/pecl/zip)                                        |
+| zlib           | php/zlib                                                                                            |
+| zstd           | [kjdev/zstd](https://packagist.org/packages/kjdev/zstd)                                             |
+
+### 進行中
+
+以下の拡張機能は PIE サポートを追加する取り組みが始まっています：
+
+| PECL 拡張機能  | ステータス                                                                                      |
+|----------------|--------------------------------------------------------------------------------------------------|
+| base58         | ⏰ PR: [jasny/base58-php-ext#14](https://github.com/jasny/base58-php-ext/pull/14)                 |
+| crypto         | ⏰ PR: [bukka/php-crypto#43](https://github.com/bukka/php-crypto/pull/43)                         |
+| dbase          | ⏰ PR: [php/pecl-database-dbase#6](https://github.com/php/pecl-database-dbase/pull/6)             |
+| hdr_histogram  | ⏰ 近日公開: [beberlei/hdrhistogram](https://packagist.org/packages/beberlei/hdrhistogram)     |
+| hrtime         | ⏰ PR: [php/pecl-datetime-hrtime#1](https://github.com/php/pecl-datetime-hrtime/pull/1)           |
+| memcache       | ⏰ PR: [websupport-sk/pecl-memcache#116](https://github.com/websupport-sk/pecl-memcache/pull/116) |
+| yaml           | ⏰ PR: [php/pecl-file_formats-yaml#88](https://github.com/php/pecl-file_formats-yaml/pull/88)     |
+
+### 未開始 / 不明
+
+以下の拡張機能は PECL に存在していますが、PIE サポートをまだ追加していないか、そのステータスが不明です。
+
+* ahocorasick
+* AOP
+* ApacheAccessor
+* apcu_bc
+* APM
+* augeas
+* awscrt
+* bloomy
+* bsdiff
+* bz2_filter
+* cairo_wrapper
+* cassandra
+* cld
+* clips
+* clucene
+* cmark
+* componere
+* couchbase
+* courierauth
+* crack_dll
+* CUBRID
+* cvsclient
+* cybermut
+* datadog_trace
+* dazuko
+* docblock
+* doublemetaphone
+* Druid
+* ecasound
+* ecma_intl
+* eio
+* env
+* esmtp
+* excimer
+* expect
+* fann
+* framegrab
+* functional
+* gearman
+* gender
+* geoip
+* gmagick
+* gnupg
+* graphdat
+* gRPC
+* handlebars
+* hprose
+* http_message
+* ibm_db2
+* ice
+* idn
+* igbinary
+* imap
+* immutable_cache
+* IMS
+* intercept
+* ion
+* ip2location
+* ip2proxy
+* isis
+* jsmin
+* json_post
+* jsonc
+* jsonnet
+* krb5
+* leveldb
+* libsodium
+* lua
+* LuaSandbox
+* lzf
+* markdown
+* maxminddb
+* mcrypt_filter
+* memoize
+* meta
+* mogilefs
+* Molten
+* Mosquitto
+* mqseries
+* msgpack
+* mustache
+* mysql_xdevapi
+* mysqlnd_azure
+* mysqlnd_krb
+* namazu
+* nsq
+* oauth
+* ocal
+* oci8
+* openal
+* opencensus
+* opengl
+* openswoole
+* PAM
+* params
+* parle
+* pcs
+* pcsc
+* PDO_CUBRID
+* PDO_IBM
+* PDO_OCI
+* PDO_SQLANYWHERE
+* pdo_sqlsrv
+* PDO_TAOS
+* pecl_http
+* perforce
+* Phalcon
+* php_trie
+* phpy
+* pinpoint_php
+* PKCS11
+* pledge
+* pq
+* propro
+* protobuf
+* ps
+* pspell
+* psr
+* qqwry
+* quickhash
+* radius
+* raphf
+* rar
+* ref
+* request
+* rnp
+* rrd
+* runkit7
+* sandbox
+* sasl
+* scoutapm
+* scrypt
+* sdl
+* sdl_image
+* sdl_mixer
+* sdl_ttf
+* SeasClick
+* SeasLog
+* SeasSnowflake
+* shape
+* simple_kafka_client
+* skywalking
+* skywalking_agent
+* smbclient
+* solr
+* spplus
+* spread
+* sqlsrv
+* ssdeep
+* ssh2
+* stackdriver_debugger
+* statgrab
+* stem
+* stomp
+* svm
+* svn
+* swoole_serialize
+* syck
+* sync
+* taint
+* tcc
+* TCLink
+* tcpwrap
+* tdb
+* teds
+* Tensor
+* termbox
+* TextCat
+* timecop
+* trace
+* trader
+* tvision
+* ui
+* uopz
+* uploadprogress
+* uv
+* v8
+* v8js
+* var_representation
+* varnish
+* vips
+* wasm
+* weakreference_bc
+* WinBinder
+* WinCache
+* xdiff
+* xhprof
+* xmldiff
+* XMLRPCi
+* xxtea
+* yac
+* yaconf
+* Yaf
+* yar
+* yaz
+* yp
+* zephir_parser
+* zeroconf
+* zlib_filter
+* zookeeper
+
+### 廃止
+
+以下の拡張機能は廃止されていると考えられています：
+
+* amfext
+* APC
+* apd
+* apn
+* archive
+* ares
+* automap
+* axis2
+* bbcode
+* bcompiler
+* big_int
+* binpack
+* BLENC
+* cairo
+* chdb
+* classkit
+* coin_acceptor
+* colorer
+* crack
+* cybercash
+* cyrus
+* DBDO
+* dbplus
+* DBus
+* dbx
+* dom_varimport
+* drizzle
+* enchant
+* fam
+* ffi
+* FreeImage
+* fribidi
+* funcall
+* fuse
+* GDChart
+* gupnp
+* haru
+* hidef
+* html_parse
+* htscanner
+* huffman
+* id3
+* imlib2
+* inclued
+* ingres
+* ircclient
+* Judy
+* kadm5
+* KTaglib
+* lapack
+* lchash
+* libevent
+* maxdb
+* mcve
+* mdbtools
+* memsession
+* memtrack
+* mnogosearch
+* mongo
+* mono
+* mysqlnd_memcache
+* mysqlnd_ms
+* mysqlnd_ngen
+* mysqlnd_qc
+* mysqlnd_uh
+* ncurses
+* Net_Gopher
+* netools
+* newt
+* odbtp
+* oggvorbis
+* opendirectory
+* operator
+* optimizer
+* orng
+* panda
+* Paradox
+* Parse_Tree
+* parsekit
+* pdflib
+* PDO_4D
+* PDO_IDS
+* pdo_user
+* PECL_Gen
+* perl
+* phdfs
+* PHK
+* POP3
+* proctitle
+* protocolbuffers
+* pthreads
+* python
+* qb
+* re2
+* riak
+* rpmreader
+* rsvg
+* rsync
+* runkit
+* sam
+* scream
+* sdo
+* sphinx
+* spidermonkey
+* SPL_Types
+* stats
+* strict
+* sundown
+* swish
+* tidy
+* tk
+* tokyo_tyrant
+* txforward
+* udis86
+* uri_template
+* Valkyrie
+* vpopmail
+* wbxml
+* Weakref
+* win32ps
+* win32ps_dll
+* win32std
+* wxwidgets
+* xcommerce
+* xmlrpc
+* xmms
+* xmp
+* xrange
+* xslcache
+* yami
+* ZendOptimizerPlus
+* zmq
+
diff --git a/docs/ja/usage.md b/docs/ja/usage.md
new file mode 100644
index 00000000..029f114e
--- /dev/null
+++ b/docs/ja/usage.md
@@ -0,0 +1,328 @@
+---
+title: PIE の使用
+order: 2
+en-revision: b595732a62673b53c2509dfeab38a71ee16c88f4
+---
+> [!WARNING]
+> This translation may not be based on the latest version, please ensure you
+> check the original English version for discrepancies.
+
+# PIE 使用ガイド
+
+## PIE のインストール
+
+### 手動インストール
+
+- [最新リリース](https://github.com/php/pie/releases)から `pie.phar` をダウンロード
+- `gh attestation verify --owner php pie.phar` で PHAR のソースを検証
+    - このステップには [`gh` CLI コマンド](https://github.com/cli/cli/)が必要です。
+- `php pie.phar <command>` で PIE を呼び出すことができます
+- オプション：`pie.phar` を `$PATH` にコピー、例：`cp pie.phar /usr/local/bin/pie`
+    - PIE を `$PATH` にコピーした場合、`pie <command>` で PIE を呼び出すことができます
+
+このドキュメントでは、`pie.phar` を `$PATH` に移動したと仮定しています。例えば、非 Windows システムでは `/usr/local/bin/pie` です。
+
+### ワンライナー
+
+これは署名を検証しないため、実行するリスクはご自身で負担することになりますが、非 Windows システムで PIE を `/usr/local/bin/pie` に配置します：
+
+```shell
+curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar \
+  && gh attestation verify --owner php /tmp/pie.phar \
+  && sudo mv /tmp/pie.phar /usr/local/bin/pie \
+  && sudo chmod +x /usr/local/bin/pie
+```
+
+### Docker インストール
+
+PIE はバイナリのみの Docker イメージとして公開されているため、Docker ビルド中に簡単にインストールできます：
+
+```Dockerfile
+COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie
+```
+
+`bin` タグ（最新のバイナリのみのイメージを表す）の代わりに、明示的なバージョン（`x.y.z-bin` 形式）を使用することもできます。利用可能なタグを見つけるには [GitHub registry](https://ghcr.io/php/pie) を使用してください。
+
+> [!IMPORTANT]
+> バイナリのみのイメージには PHP ランタイムが含まれていないため、PIE を_実行_することはできません。これは PHAR ファイルを配布する別の方法に過ぎず、PIE のランタイム要件は自分で満たす必要があります。
+
+#### Dockerfile での PIE の動作例
+
+これは Docker イメージ内で PIE を使用して拡張機能をインストールする方法の例です。Composer と同様に、`unzip`、[Zip](https://www.php.net/manual/ja/book.zip.php) 拡張機能、または `git` のようなものが必要です。
+
+```Dockerfile
+FROM php:8.4-cli
+
+# PIE が .zip ファイルを展開するために使用する `unzip` パッケージを追加
+RUN export DEBIAN_FRONTEND="noninteractive"; \
+    set -eux; \
+    apt-get update; apt-get install -y --no-install-recommends unzip; \
+    rm -rf /var/lib/apt/lists/*
+
+# 最新の `:bin` リリースから pie.phar をコピー
+COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie
+
+# PIE を使用して拡張機能をインストール...
+RUN pie install asgrim/example-pie-extension
+```
+
+インストールしたい拡張機能に追加のライブラリや他の依存関係が必要な場合は、それらを事前にインストールする必要があります。
+
+## PIE の前提条件
+
+PIE の実行には PHP 8.1 以降が必要です。ただし、古いバージョンの PHP 用の拡張機能をインストールするために PIE を使用することはできます。
+
+PHP に加えて、PIE は拡張機能をダウンロード、ビルド、インストールするために、システムに以下のツールが必要です：
+
+- PIE を実行する PHP バージョンで有効化された `zip` 拡張機能、または拡張機能のソースコードをダウンロードするための `git`
+- 拡張機能をビルドするための `autoconf`、`automake`、`libtool`、`m4`、`make`、`gcc`
+- 拡張機能のビルドを準備するための PHP 開発ツール（`php-config` や `phpize` など）
+
+また、各拡張機能には独自の要件（追加のライブラリなど）がある場合があります。
+
+> [!TIP]
+> 正しい前提条件がインストールされていない状態で PIE を実行すると、*Box Requirements Checker* からエラーが表示される場合があります。とにかく実行を試みたい場合は、環境変数 `BOX_REQUIREMENT_CHECKER=0` を指定してください。
+>
+> Linux での例：
+> ```shell
+> $ BOX_REQUIREMENT_CHECKER=0 pie install foo/bar
+> ```
+
+### Linux の使用
+
+Debian ベースのシステムでは、以下のコマンドで必要なツールをインストールできます：
+
+```shell
+sudo apt-get install git autoconf automake libtool m4 make gcc
+```
+
+Red Hat ベースのシステムでは、以下のコマンドで必要なツールをインストールできます：
+
+```shell
+sudo yum install git autoconf automake libtool m4 make gcc
+```
+
+### macOS の使用
+
+macOS では、[Homebrew](https://brew.sh) を使用して必要なツールをインストールできます：
+
+```shell
+brew install git autoconf automake libtool m4 make gcc
+```
+
+### Windows の使用
+
+Windows では、拡張機能は通常、プリコンパイル済みのバイナリとして配布されます。拡張機能を自分でビルドする代わりに、DLL ファイルとしてダウンロードされ、PHP 拡張機能ディレクトリに配置されます。
+
+## 拡張機能のダウンロード、ビルド、またはインストール
+
+PIE には以下の機能があります：
+
+ - `pie download ...` で拡張機能のみをダウンロード
+ - `pie build ...` で拡張機能をダウンロードしてビルド
+ - または、最も一般的な、`pie install ...` で拡張機能をダウンロード、ビルド、インストール
+
+PIE で拡張機能をインストールする場合、その Composer パッケージ名を使用する必要があります。PIE 互換パッケージのリストは [https://packagist.org/extensions](https://packagist.org/extensions) で確認できます。
+
+拡張機能名がわかったら、以下のようにインストールできます：
+
+```shell
+pie install <vendor>/<package>
+
+# 例：
+pie install xdebug/xdebug
+```
+
+これにより、PIE を呼び出すために使用された PHP バージョンに Xdebug 拡張機能がインストールされ、その PHP バージョンと互換性のある Xdebug の最新安定版が使用されます。
+
+### 異なる PHP バージョン用の拡張機能を PIE でインストール
+
+異なるバージョンの PHP 用の拡張機能をインストールしようとしている場合、非 Windows システムでは `--with-php-config` オプションで指定できます：
+
+```shell
+pie install --with-php-config=/usr/bin/php-config7.2 my/extension
+```
+
+Windows では、`--with-php-path` オプションを使用して `php` 実行可能ファイル自体のパスを指定できます。これは Windows での例で、PHP 8.1 を使用して PIE を実行していますが、PHP 8.3 用の拡張機能をダウンロードしたい場合です：
+
+```shell
+> C:\php-8.1.7\php.exe C:\pie.phar install --with-php-path=C:\php-8.3.6\php.exe example/example-pie-extension
+```
+
+ターゲット PHP バージョンに対応する `phpize` コマンドを使用する必要がある場合もあります。これは `--with-phpize-path` オプションで指定できます：
+
+```shell
+pie install --with-phpize-path=/usr/bin/phpize7.2 my/extension
+```
+
+### バージョン制約と安定性
+
+PIE で拡張機能をインストールする際に、オプションでバージョン制約を指定できます：
+
+```bash
+pie install <vendor>/<package>:<version-constraint>
+```
+
+`version-constraint` が指定された場合、許可されたバージョンと一致する場合、そのバージョンをインストールしようとします。バージョン制約は Composer と同じ形式で解決され、最小安定性も考慮されます。
+
+* `^1.0` は、セマンティックバージョニングに従って、`1.0.0` 以上で後方互換性のある最新の安定版をインストールします。
+  [詳細は Composer ドキュメントを参照](https://getcomposer.org/doc/articles/versions.md#caret-version-range-)。
+* `^2.3@beta` は、`2.3.0` 以上で後方互換性のある最新のベータ版をインストールします（例：`2.3.0-beta.3`）。
+* `dev-main` は、コマンド実行時の `main` ブランチの最新コミットをインストールします。これは Windows バイナリを含むリリースがないため、Windows では機能しません。
+* `dev-main#07f454ad797c30651be8356466685b15331f72ff` は、`#` の後のコミット sha で示される特定のコミットをインストールします。この場合、コミット `07f454ad797c30651be8356466685b15331f72ff` がインストールされます。これは Windows バイナリを含むリリースがないため、Windows では機能しません。
+
+`version-constraint` が指定されると、チェックされ、ターゲット PHP バージョンの `pie.json` に直接追加されます。例：
+
+```shell
+$ pie install "xdebug/xdebug:^3.4.3 || 3.4.1"
+```
+
+これにより、`pie.json` に以下が設定されます：
+
+```json
+{
+    "require": {
+        "xdebug/xdebug": "^3.4.3 || 3.4.1"
+    }
+}
+```
+
+`version-constraint` が指定されていない場合、互換性のある最新の安定版をインストールしようとします。PIE は常に安定版を優先します。
+
+### 設定オプションの指定
+
+拡張機能をコンパイルする際、一部の拡張機能では `./configure` コマンドに追加のパラメータを渡す必要があります。これらは通常、特定の機能を有効化または無効化するため、または自動検出されないライブラリのパスを提供するために使用されます。
+
+拡張機能で利用可能な設定オプションを確認するには、`pie info <vendor>/<package>` を使用します。これにより、次のようなリストが返されます：
+
+```text
+Configure options:
+    --enable-some-functionality  (whether to enable some additional functionality provided)
+    --with-some-library-name=?  (Path for some-library)
+```
+
+上記の例の拡張機能は、指定された設定オプションなし、一部、またはすべてを使用してインストールできます。いくつかの例：
+
+```shell
+pie install example/some-extension
+pie install example/some-extension --enable-some-functionality
+pie install example/some-extension --with-some-library-name=/path/to/the/lib
+pie install example/some-extension --with-some-library-name=/path/to/the/lib --enable-some-functionality
+```
+
+### INI ファイルの設定
+
+PIE は、適切な INI ファイルに `extension=...` または `zend_extension=...` を追加することで、拡張機能を自動的に有効化しようとします。この動作を無効にしたい場合は、`pie install` コマンドに `--skip-enable-extension` フラグを渡してください。拡張機能を有効化しようとする際には、以下の技術が使用されます：
+
+ * deb.sury.org ディストリビューションを使用している場合は `phpenmod`
+ * Docker の PHP イメージを使用している場合は `docker-php-ext-enable`
+ * 「追加の .ini ファイル」パスが設定されている場合は、そのパスに新しいファイルを追加
+ * 標準の php.ini が設定されている場合は、php.ini に追記
+
+これらの技術がいずれも機能しない場合、または `--skip-enable-extension` フラグを使用した場合、PIE は拡張機能が有効化されなかったことを警告し、拡張機能を自分で有効化する必要があることを通知します。
+
+### Packagist.org 以外のリポジトリの追加
+
+Packagist.org 以外のパッケージリポジトリ（[Private Packagist](https://packagist.com/) など）から拡張機能をインストールしたい場合や、ローカルディレクトリからインストールしたい場合があります。PIE は Composer をベースにしているため、他のリポジトリタイプを使用できます：
+
+* `pie repository:add [--with-php-config=...] path /path/to/your/local/extension`
+* `pie repository:add [--with-php-config=...] vcs https://github.com/youruser/yourextension`
+* `pie repository:add [--with-php-config=...] composer https://repo.packagist.com/your-private-packagist/`
+* `pie repository:add [--with-php-config=...] composer packagist.org`
+
+`repository:*` コマンドはすべて、オプションの `--with-php-config` フラグをサポートしており、使用する PHP インストールを指定できます（例えば、1 台のマシンに複数の PHP インストールがある場合）。追加されたリポジトリは、逆の `repository:remove` コマンドを使用して削除することもできます：
+
+* `pie repository:remove [--with-php-config=...] /path/to/your/local/extension`
+* `pie repository:remove [--with-php-config=...] https://github.com/youruser/yourextension`
+* `pie repository:remove [--with-php-config=...] https://repo.packagist.com/your-private-packagist/`
+* `pie repository:remove [--with-php-config=...] packagist.org`
+
+`repository:remove` ではリポジトリタイプを指定する必要はなく、URL だけを指定します。
+
+ターゲット PHP インストールのリポジトリをリストするには：
+
+* `pie repository:list [--with-php-config=...]`
+
+## プロジェクトに不足している拡張機能の確認とインストール
+
+PHP プロジェクトの作業ディレクトリにいる場合、`pie install` を使用してプロジェクトが必要とする拡張機能が存在するかどうかを確認できます。拡張機能が不足している場合、PIE はインストール候補を見つけて、インストールするかどうかをインタラクティブに尋ねます。例：
+
+```
+$ pie install
+🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
+You are running PHP 8.3.19
+Target PHP installation: 8.3.19 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.3)
+Checking extensions for your project your-vendor/your-project
+requires: curl ✅ Already installed
+requires: intl ✅ Already installed
+requires: json ✅ Already installed
+requires: example_pie_extension ⚠️  Missing
+
+The following packages may be suitable, which would you like to install:
+  [0] None
+  [1] asgrim/example-pie-extension: Example PIE extension
+ > 1
+   > 🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
+   > This command may need elevated privileges, and may prompt you for your password.
+   > You are running PHP 8.3.19
+   > Target PHP installation: 8.3.19 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.3)
+   > Found package: asgrim/example-pie-extension:2.0.2 which provides ext-example_pie_extension
+   ... (snip) ...
+   > ✅ Extension is enabled and loaded in /usr/bin/php8.3
+
+Finished checking extensions.
+```
+
+## PECL との比較
+
+PIE は PECL の代替品であるため、PECL でよく知られているコマンドと PIE での同等のコマンドの比較を以下に示します。一部の概念は PIE では異なるか省略されている場合があります。これは新しいツールには適用されない可能性があるためです。
+
+| PECL                           | PIE                                                                                                                     |
+|--------------------------------|-------------------------------------------------------------------------------------------------------------------------|
+| `pecl build xdebug`            | `pie build xdebug/xdebug`                                                                                               |
+| `pecl bundle xdebug`           | `pie download xdebug/xdebug`                                                                                            |
+| `pecl channel-add channel.xml` | `pie repository:add vcs https://github.com/my/extension`                                                                |
+| `pecl channel-alias`           |                                                                                                                         |
+| `pecl channel-delete channel`  | `pie repository:remove https://github.com/my/extension`                                                                 |
+| `pecl channel-discover`        |                                                                                                                         |
+| `pecl channel-login`           |                                                                                                                         |
+| `pecl channel-logout`          |                                                                                                                         |
+| `pecl channel-update`          |                                                                                                                         |
+| `pecl clear-cache`             |                                                                                                                         |
+| `pecl config-create`           |                                                                                                                         |
+| `pecl config-get`              |                                                                                                                         |
+| `pecl config-help`             |                                                                                                                         |
+| `pecl config-set`              |                                                                                                                         |
+| `pecl config-show`             |                                                                                                                         |
+| `pecl convert`                 |                                                                                                                         |
+| `pecl cvsdiff`                 |                                                                                                                         |
+| `pecl cvstag`                  |                                                                                                                         |
+| `pecl download xdebug`         | `pie download xdebug/xdebug`                                                                                            |
+| `pecl download-all`            |                                                                                                                         |
+| `pecl info xdebug`             | `pie info xdebug/xdebug`                                                                                                |
+| `pecl install xdebug`          | `pie install xdebug/xdebug`                                                                                             |
+| `pecl list`                    | `pie show`                                                                                                              |
+| `pecl list-all`                | [Packagist 拡張機能リスト](https://packagist.org/extensions)を参照                                                       |
+| `pecl list-channels`           | `pie repository:list`                                                                                                   |
+| `pecl list-files`              |                                                                                                                         |
+| `pecl list-upgrades`           |                                                                                                                         |
+| `pecl login`                   |                                                                                                                         |
+| `pecl logout`                  |                                                                                                                         |
+| `pecl makerpm`                 |                                                                                                                         |
+| `pecl package`                 | Linux - リリースをタグ付けするだけ。Windows - [`php/php-windows-builder` action](https://github.com/php/php-windows-builder) を使用 |
+| `pecl package-dependencies`    |                                                                                                                         |
+| `pecl package-validate`        | 拡張機能のチェックアウトで：`composer validate`                                                                          |
+| `pecl pickle`                  |                                                                                                                         |
+| `pecl remote-info xdebug`      | `pie info xdebug/xdebug`                                                                                                |
+| `pecl remote-list`             | [Packagist 拡張機能リスト](https://packagist.org/extensions)を参照                                                       |
+| `pecl run-scripts`             |                                                                                                                         |
+| `pecl run-tests`               |                                                                                                                         |
+| `pecl search`                  | [Packagist 拡張機能リスト](https://packagist.org/extensions)を参照                                                       |
+| `pecl shell-test`              |                                                                                                                         |
+| `pecl sign`                    |                                                                                                                         |
+| `pecl svntag`                  |                                                                                                                         |
+| `pecl uninstall`               |                                                                                                                         |
+| `pecl update-channels`         |                                                                                                                         |
+| `pecl upgrade xdebug`          | `pie install xdebug/xdebug`                                                                                             |
+| `pecl upgrade-all`             |                                                                                                                         |
+
diff --git a/docs/zh/README.md b/docs/zh/README.md
new file mode 100644
index 00000000..6897beb7
--- /dev/null
+++ b/docs/zh/README.md
@@ -0,0 +1,112 @@
+---
+en-revision: b595732a62673b53c2509dfeab38a71ee16c88f4
+---
+> [!WARNING]
+> This translation may not be based on the latest version, please ensure you
+> check the original English version for discrepancies.
+
+# 🥧 PIE (PHP 扩展安装器)
+
+## 什么是 PIE？
+
+PIE 是一个新的 PHP 扩展安装器，旨在最终替代 PECL。
+它以 [PHAR](https://www.php.net/manual/en/intro.phar.php) 格式分发，
+就像 Composer 一样，工作方式也类似，但它将 PHP 扩展（PHP 模块或 Zend 扩展）
+安装到您的 PHP 安装中，而不是将 PHP 包拉入您的项目或库。
+
+# 使用 PIE - 我需要什么才能开始？
+
+## 先决条件
+
+您需要 PHP 8.1 或更高版本来运行 PIE，但 PIE 可以将扩展安装到任何其他已安装的 PHP 版本。
+
+在 Linux 上，您需要安装构建工具链。在 Debian/Ubuntu 类型的系统上，您可以运行：
+
+```shell
+sudo apt install gcc make autoconf libtool bison re2c pkg-config php-dev
+```
+
+在 Windows 上，您不需要安装任何构建工具链，因为 Windows 的 PHP 扩展
+以预编译包的形式分发，包含扩展 DLL。
+
+## 安装 PIE
+
+- 下载 `pie.phar`，可以通过以下方式：
+  - [最新稳定版本](https://github.com/php/pie/releases)
+  - [最新不稳定夜间构建版本](https://php.github.io/pie/pie-nightly.phar)
+- 使用 `gh attestation verify --owner php pie.phar` 验证 PHAR 的来源
+- 然后您可以使用 `php pie.phar <command>` 调用 PIE
+
+更多安装详情可以在 [使用文档](./docs/usage.md) 中找到。
+本文档假设您已将 `pie.phar` 移动到您的 `$PATH` 中，例如在非 Windows 系统上为 `/usr/local/bin/pie`。
+
+## 使用 PIE 安装单个扩展
+
+您可以使用 `install` 命令安装扩展。例如，要安装 `example_pie_extension` 扩展，您可以运行：
+
+```shell
+$ pie install example/example-pie-extension
+此命令可能需要提升权限，并可能提示您输入密码。
+您正在运行 PHP 8.3.10
+目标 PHP 安装：8.3.10 nts，在 Linux/OSX/etc x86_64 上（来自 /usr/bin/php8.3）
+找到包：example/example-pie-extension:1.0.1，提供 ext-example_pie_extension
+phpize 完成。
+配置完成。
+构建完成：/tmp/pie_downloader_66e0b1de73cdb6.04069773/example-example-pie-extension-769f906/modules/example_pie_extension.so
+安装完成：/usr/lib/php/20230831/example_pie_extension.so
+您现在必须在 php.ini 中添加 "extension=example_pie_extension"
+$
+```
+
+## 为 PHP 项目安装所有扩展
+
+在您的 PHP 项目中，您可以安装任何缺失的顶级扩展：
+
+```
+$ pie install
+🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
+您正在运行 PHP 8.3.19
+目标 PHP 安装：8.3.19 nts，在 Linux/OSX/etc x86_64 上（来自 /usr/bin/php8.3）
+检查您的项目 your-vendor/your-project 的扩展
+requires: curl ✅ 已安装
+requires: intl ✅ 已安装
+requires: json ✅ 已安装
+requires: example_pie_extension ⚠️  缺失
+
+以下包可能合适，您想安装哪个：
+  [0] 无
+  [1] asgrim/example-pie-extension: Example PIE extension
+ > 1
+   > 🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
+   > 此命令可能需要提升权限，并可能提示您输入密码。
+   > 您正在运行 PHP 8.3.19
+   > 目标 PHP 安装：8.3.19 nts，在 Linux/OSX/etc x86_64 上（来自 /usr/bin/php8.3）
+   > 找到包：asgrim/example-pie-extension:2.0.2，提供 ext-example_pie_extension
+   ... (省略) ...
+   > ✅ 扩展已在 /usr/bin/php8.3 中启用并加载
+
+完成扩展检查。
+```
+
+## 支持 PIE 的扩展
+
+支持 PIE 的扩展列表可以在
+[https://packagist.org/extensions](https://packagist.org/extensions) 上找到。
+
+# 我有错误、功能想法、问题、需要帮助等。
+
+ - 如果您有想法、问题或需要帮助，请使用 [讨论区](https://github.com/php/pie/discussions)。
+   - **在贡献新功能之前，请先与我们联系** - 这可能是
+     我们已经正在开发的内容，因为 PHP Foundation 也在积极
+     开发这个项目，并且已经有一些新功能正在开发中...
+ - 如果您有错误要报告，请使用 [问题](https://github.com/php/pie/issues)。
+
+# 我是扩展维护者 - 如何添加 PIE 支持？
+
+如果您是想要为您的扩展添加 PIE 支持的扩展维护者，
+请阅读 [扩展维护者文档](./docs/extension-maintainers.md)。
+
+## 更多文档...
+
+PIE 的完整文档可以在 [使用文档](./docs/usage.md) 中找到。
+
diff --git a/docs/zh/extension-maintainers.md b/docs/zh/extension-maintainers.md
new file mode 100644
index 00000000..ad13811b
--- /dev/null
+++ b/docs/zh/extension-maintainers.md
@@ -0,0 +1,351 @@
+---
+title: 扩展维护者
+order: 3
+en-revision: b595732a62673b53c2509dfeab38a71ee16c88f4
+---
+> [!WARNING]
+> This translation may not be based on the latest version, please ensure you
+> check the original English version for discrepancies.
+
+# PIE 扩展维护者指南
+
+## PIE 构建和安装步骤
+
+### 非 Windows（例如 Linux、OSX 等）
+
+PIE 遵循通常的 [PHP 扩展构建和安装过程](https://www.php.net/manual/zh/install.pecl.phpize.php)，即：
+
+ * `phpize` 用于设置 PHP API 参数。如果 `phpize` 不在路径中，安装扩展的人可以指定 `--with-phpize-path`。
+ * `./configure` 用于为特定系统配置构建参数和库。安装扩展的人可以指定您在 `composer.json` 中指定的配置选项。有关如何执行此操作，请参阅[配置选项](#configure-options)文档。
+ * `make` 实际构建扩展。这将尝试自动检测要运行的并行进程数，但安装的人可以使用 `--make-parallel-jobs N` 或 `-jN` 选项覆盖此设置。
+ * `make install` 将扩展安装到配置的 PHP 安装中。如果 PIE 没有写入安装位置的权限，它将尝试使用 `sudo` 提升权限。
+
+请注意，这意味着运行 PIE 的系统需要安装适当的构建工具。有关构建扩展和 PHP 内部工作原理的有用资源是 [PHP Internals Book](https://www.phpinternalsbook.com/)。
+
+### Windows
+
+对于 Windows 系统，扩展维护者必须提供预构建的二进制文件。有关如何以正确的方式为 PIE 执行此操作的详细信息，请参阅下面的 [Windows 支持](#windows-support)部分。
+
+## 如何为您的扩展添加 PIE 支持
+
+为您的扩展添加 PIE 支持相对简单，流程与将常规 PHP 包添加到 Packagist 非常相似。
+
+### 已在 PECL 上的扩展
+
+如果您是现有 PECL 扩展的维护者，以下是一些有用的上下文信息：
+
+ - 对于已在 PECL 中的扩展，如果您不再想发布到 PECL，则不再需要 `package.xml`。如果您现在想继续发布到 PECL，则可以继续维护 `package.xml`。
+ - `package.xml` 明确列出每个版本。使用 PIE，这不再需要，因为 Packagist 会像常规 Composer 包一样获取标签或分支别名。这意味着要发布您的包，您需要推送标签和发布版本。
+ - 在默认设置中，包的内容由标签或发布版本的 [Git archive](https://git-scm.com/docs/git-archive) 确定。您可以使用 [export-ignore](https://git-scm.com/docs/git-archive#Documentation/git-archive.txt-export-ignore) 属性从存档中排除文件和路径。
+
+### 向扩展添加 `composer.json`
+
+添加 PIE 支持的第一步是向扩展仓库添加 `composer.json`。大多数典型字段与常规 Composer 包相同，但有几个值得注意的例外：
+
+ * `type` 必须是 `php-ext`（用于 PHP 模块，这将是大多数扩展）或 `php-ext-zend`（用于 Zend 扩展）。
+ * 可以存在额外的 `php-ext` 部分（请参阅下面有关 `php-ext` 中可以包含的指令）
+ * Composer 包名称（即顶级 `name` 字段）必须遵循通常的 Composer 包名称格式，即 `<vendor>/<package>`。
+ * 但是，请注意，PIE 扩展的 Composer 包名称不得与常规 PHP 包共享相同的 Composer 包名称，即使它们具有不同的 `type` 字段。
+
+#### `php-ext` 定义
+
+##### `extension-name`
+
+可以指定 `extension-name`，并且必须符合通常的扩展名称正则表达式，该表达式在 [\Php\Pie\ExtensionName::VALID_PACKAGE_NAME_REGEX](../src/ExtensionName.php) 中定义。如果未指定 `extension-name`，则 `extension-name` 将从 Composer 包名称派生，删除供应商前缀。例如，给定一个 `composer.json`：
+
+```json
+{
+    "name": "myvendor/myextension"
+}
+```
+
+扩展名称将派生为 `myextension`。`myvendor/` 供应商前缀被删除。
+
+> [!WARNING]
+> 如果您的 Composer 包名称会导致无效的 PHP 扩展名称，您必须指定 `extension-name` 指令。例如，Composer 包名称 `myvendor/my-extension` 会导致无效的 PHP 扩展名称，因为不允许使用连字符，因此您必须为此 Composer 包名称指定有效的 `extension-name`。
+
+`extension-name` 不应以 `ext-` 为前缀，这是 Composer 在使用 `require` 时的约定。
+
+使用 `extension-name` 的示例：
+
+```json
+{
+    "name": "xdebug/xdebug",
+    "php-ext": {
+        "extension-name": "xdebug"
+    }
+}
+```
+
+##### `priority`
+
+`priority` 构成 `ini` 文件名的一部分，用于控制扩展的顺序，如果目标平台使用目录中的多个 INI 文件。
+
+##### `support-zts` 和 `support-nts`
+
+指示扩展是否支持 Zend Thread-Safe（ZTS）和非线程安全（NTS）模式。如果未指定，这两个标志都默认为 `true`，但如果您的扩展不支持任一模式，则必须指定，这将意味着扩展无法在目标平台上安装。
+
+理论上，可以为 `support-zts` 和 `support-nts` 都指定 `false`，但这将意味着您的包无法在任何地方安装，因此不建议这样做。
+
+##### `configure-options`
+
+这是可以传递给 `./configure` 命令的参数列表。列表的每个项目都是一个 JSON 对象，包含：
+
+ * `name`，参数名称本身
+ * `description`，参数作用的有用描述
+ * 可选的 `needs-value`，一个布尔值，告诉 PIE 参数是简单标志（通常用于 `--enable-this-flag` 类型参数），还是参数应该有一个指定的值（通常用于 `--with-library-path=...` 类型参数，其中最终用户必须提供一个值）
+
+当最终用户使用 PIE 安装扩展时，他们可以指定传递给 `./configure` 的任何已定义的 `configure-options`。例如，如果扩展定义了以下 `composer.json`：
+
+```json
+{
+    "name": "myvendor/myext",
+    "php-ext": {
+        "extension-name": "myext",
+        "configure-options": [
+            {
+                "name": "enable-my-flag",
+                "description": "Should my flag be enabled",
+                "needs-value": false
+            },
+            {
+                "name": "with-some-lib",
+                "description": "Specify the path to some-lib",
+                "needs-value": true
+            }
+        ]
+    }
+}
+```
+
+然后可以以以下方式调用 `pie build` 或 `pie install` 命令以实现所需的配置：
+
+ * `pie install myvendor/myext`
+   * 这将简单地调用 `./configure` 而不带任何参数
+ * `pie install myvendor/myext --enable-my-flag`
+   * 这将调用 `./configure --enable-my-flag`
+ * `pie install myvendor/myext --with-some-lib=/path/to/somelib`
+   * 这将调用 `./configure --with-some-lib=/path/to/somelib`
+ * `pie install myvendor/myext --enable-my-flag --with-some-lib=/path/to/somelib`
+   * 这将调用 `./configure --enable-my-flag --with-some-lib=/path/to/somelib`
+
+请注意，PIE 的最终用户无法指定未在您的扩展的 `configure-options` 定义中定义的配置选项。使用上面相同的 `composer.json` 示例，使用无效选项调用 PIE，例如 `pie install myvendor/myext --something-else` 将导致错误 `The "--something-else" option does not exist.`。
+
+如果最终用户未指定 `configure-options` 定义中定义的标志，则不会将其传递给 `./configure`。无法在 `configure-options` 定义中指定默认值。您的 `config.m4` 应相应地处理此问题。
+
+##### `build-path`
+
+如果源代码不在仓库的根目录中，可以使用 `build-path` 设置。例如，如果您的仓库结构如下：
+
+```text
+/
+  docs/
+  src/
+    config.m4
+    config.w32
+    myext.c
+    ...etc
+```
+
+在这种情况下，实际的扩展源代码将在 `src/` 中构建，因此您应该在 `build-path` 中指定此路径，例如：
+
+```json
+{
+    "name": "myvendor/myext",
+    "php-ext": {
+        "extension-name": "myext",
+        "build-path": "src"
+    }
+}
+```
+
+`build-path` 可以包含一些被替换的模板值：
+
+ * `{version}` 将被替换为包版本。例如，版本为 1.2.3 的包，`build-path` 为 `myext-{version}`，实际构建路径将变为 `myext-1.2.3`。
+
+##### `download-url-method`
+
+`download-url-method` 指令允许扩展维护者更改下载源包的行为。
+
+ * 将其设置为 `composer-default`（如果未指定则为默认值），将使用 Composer 实现的默认行为，即使用来自 GitHub API（或其他源代码控制系统）的标准 ZIP 存档。
+ * 使用 `pre-packaged-source` 将在发布资源列表中定位源代码包，该包基于以下命名约定之一：
+   * `php_{ExtensionName}-{Version}-src.tgz`（例如 `php_myext-1.20.1-src.tgz`）
+   * `php_{ExtensionName}-{Version}-src.zip`（例如 `php_myext-1.20.1-src.zip`）
+   * `{ExtensionName}-{Version}.tgz`（这是为了与 PECL 包向后兼容）
+
+##### `os-families` 限制
+
+`os-families` 和 `os-families-exclude` 指令允许扩展维护者限制操作系统兼容性。
+
+ * `os-families` 一个操作系统家族的数组，用于标记与扩展兼容。（例如 `"os-families": ["windows"]` 表示仅在 Windows 上可用的扩展）
+ * `os-families-exclude` 一个操作系统家族的数组，用于标记与扩展不兼容。（例如 `"os-families-exclude": ["windows"]` 表示无法在 Windows 上安装的扩展）
+
+接受的操作系统家族列表："windows"、"bsd"、"darwin"、"solaris"、"linux"、"unknown"
+
+> [!WARNING]
+> 只能定义 `os-families` 和 `os-families-exclude` 之一。
+
+#### 扩展依赖项
+
+扩展作者可以在 `require` 中定义一些依赖项，但实际上，大多数扩展不需要定义依赖项，除了扩展支持的 PHP 版本。可以定义对其他扩展的依赖项，例如 `ext-json`。但是，不应在 `require` 部分指定对常规 PHP 包（如 `monolog/monolog`）的依赖项。
+
+值得注意的是，如果您的扩展确实定义了对另一个依赖项的依赖，并且此依赖项不可用，则安装您的扩展的人将收到如下消息：
+
+```
+Cannot use myvendor/myextension's latest version 1.2.3 as it requires
+ext-something * which is missing from your platform.
+```
+
+#### 检查扩展是否能工作
+
+首先，您可以使用 `composer validate` 检查您的 `composer.json` 格式是否正确，例如：
+
+```shell
+$ composer validate
+./composer.json is valid
+```
+
+然后，您可以在扩展目录中使用 `pie install` 安装扩展：
+
+```shell
+$ cd /path/to/my/extension
+$ pie install
+🥧 PHP Installer for Extensions (PIE) 1.0.0, from The PHP Foundation
+Installing PIE extension from /home/james/workspace/phpf/example-pie-extension
+This command may need elevated privileges, and may prompt you for your password.
+You are running PHP 8.4.8
+Target PHP installation: 8.4.8 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.4)
+Found package: asgrim/example-pie-extension:dev-main which provides ext-example_pie_extension
+Extracted asgrim/example-pie-extension:dev-main source to: /home/james/.config/pie/php8.4_572ee73609adb95bf0b8539fecdc5c0e/vendor/asgrim/example-pie-extension
+Build files cleaned up.
+phpize complete.
+Configure complete.
+Build complete: /home/james/.config/pie/php8.4_572ee73609adb95bf0b8539fecdc5c0e/vendor/asgrim/example-pie-extension/modules/example_pie_extension.so
+Cannot write to /usr/lib/php/20240924, so using sudo to elevate privileges.
+Install complete: /usr/lib/php/20240924/example_pie_extension.so
+✅ Extension is enabled and loaded in /usr/bin/php8.4
+```
+
+##### 仅构建不安装
+
+如果您只想测试应用程序的构建而不将其安装到目标 PHP 版本，您首先需要将扩展目录添加为"path"类型仓库：
+
+```shell
+$ cd /path/to/my/extension
+$ pie repository:add path .
+🥧 PHP Installer for Extensions (PIE) 1.0.0, from The PHP Foundation
+You are running PHP 8.4.8
+Target PHP installation: 8.4.8 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.4)
+The following repositories are in use for this Target PHP:
+  - Path Repository (/home/james/workspace/phpf/example-pie-extension)
+  - Packagist
+```
+
+然后，您可以测试它是否构建：
+
+```shell
+$ pie build asgrim/example-pie-extension:*@dev
+```
+
+> [!TIP]
+> 由于您的扩展尚未发布到 Packagist，因此应指定 `*@dev` 作为版本约束，否则 PIE 将找不到您的扩展，因为默认稳定性为 `stable`。
+
+### 将扩展提交到 Packagist
+
+将 `composer.json` 提交到仓库后，您可以像提交任何其他包一样将其提交到 Packagist。
+
+ * 前往 [https://packagist.org/packages/submit](https://packagist.org/packages/submit)
+ * 输入您的仓库的 URL 并按照说明操作。
+
+### Windows 支持
+
+为了支持 Windows 用户，您必须发布预构建的 DLL，因为 PIE 目前不支持即时构建 DLL。Windows 兼容版本的预期工作流程是：
+
+ - 在 GitHub 上进行发布（目前仅支持 GitHub）
+ - CI 流水线运行以构建发布资源，例如在 GitHub Action 中
+ - 生成的构建资源以 ZIP 文件形式发布到 GitHub 发布版本
+
+ZIP 文件的名称以及其中包含的 DLL 必须是：
+
+* `php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.zip`
+* 示例：`php_xdebug-3.3.2-8.3-ts-vs16-x86_64.zip`
+
+这些项目的描述：
+
+* `extension-name` 扩展名称，例如 `xdebug`
+* `tag` 例如 `3.3.0alpha3` - 由您制作的标签/发布版本定义
+* `php-maj/min` - 例如 `8.3` 表示 PHP 8.3.*
+* `compiler` - 通常是像 `vc6`、`vs16` 这样的东西 - 从 `php -i` 中的 'PHP Extension Build' 标志获取
+* `ts|nts` - 线程安全或非线程安全。
+* `arch` - 例如 `x86_64`。
+   * Windows：使用 `php -i` 中 `Architecture` 的提示（见下文）
+   * 非 Windows：检查 `PHP_INT_SIZE` - 32 位为 4，64 位为 8。
+
+请注意，架构名称可能需要规范化，因为不同平台对架构的命名不同。PIE 期望以下规范化的架构：
+
+ * `x86_64`（从 `x64`、`x86_64`、`AMD64` 规范化）
+ * `arm64`（从 `arm64` 规范化）
+ * `x86`（任何其他值）
+
+有关最新映射（如果文档不是最新的），请查看 `\Php\Pie\Platform\Architecture::parseArchitecture`。
+
+#### Windows ZIP 的内容
+
+预构建的 ZIP 应至少包含一个与 ZIP 本身命名相同的 DLL，例如 `php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.dll`。`.dll` 将被移动到 PHP 扩展路径并重命名，例如移动到 `C:\path\to\php\ext\php_{extension-name}.dll`。ZIP 文件可能包含额外的资源，例如：
+
+* `php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.pdb` - 这将被移动到 `C:\path\to\php\ext\php_{extension-name}.dll` 旁边
+* `*.dll` - 任何其他 `.dll` 都将被移动到 `C:\path\to\php\php.exe` 旁边
+* 任何其他文件，将被移动到 `C:\path\to\php\extras\{extension-name}\.`
+
+#### Windows 发布的自动化
+
+PHP 提供了一组 [GitHub Actions](https://github.com/php/php-windows-builder)，使扩展维护者能够构建和发布 Windows 兼容资源。使用这些操作的示例工作流程：
+
+```yaml
+name: Publish Windows Releases
+on:
+   release:
+      types: [published]
+
+permissions:
+   contents: write
+
+jobs:
+   get-extension-matrix:
+      runs-on: ubuntu-latest
+      outputs:
+         matrix: ${{ steps.extension-matrix.outputs.matrix }}
+      steps:
+         - name: Checkout
+           uses: actions/checkout@v4
+         - name: Get the extension matrix
+           id: extension-matrix
+           uses: php/php-windows-builder/extension-matrix@v1
+   build:
+      needs: get-extension-matrix
+      runs-on: ${{ matrix.os }}
+      strategy:
+         matrix: ${{fromJson(needs.get-extension-matrix.outputs.matrix)}}
+      steps:
+         - name: Checkout
+           uses: actions/checkout@v4
+         - name: Build the extension
+           uses: php/php-windows-builder/extension@v1
+           with:
+              php-version: ${{ matrix.php-version }}
+              arch: ${{ matrix.arch }}
+              ts: ${{ matrix.ts }}
+   release:
+      runs-on: ubuntu-latest
+      needs: build
+      if: ${{ github.event_name == 'release' }}
+      steps:
+         - name: Upload artifact to the release
+           uses: php/php-windows-builder/release@v1
+           with:
+              release: ${{ github.event.release.tag_name }}
+              token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+来源：[https://github.com/php/php-windows-builder?tab=readme-ov-file#example-workflow-to-build-and-release-an-extension](https://github.com/php/php-windows-builder?tab=readme-ov-file#example-workflow-to-build-and-release-an-extension)
+
diff --git a/docs/zh/pie-maintainers-handbook.md b/docs/zh/pie-maintainers-handbook.md
new file mode 100644
index 00000000..bf8b3b72
--- /dev/null
+++ b/docs/zh/pie-maintainers-handbook.md
@@ -0,0 +1,65 @@
+---
+title: PIE 维护者手册
+order: 3
+en-revision: b595732a62673b53c2509dfeab38a71ee16c88f4
+---
+> [!WARNING]
+> This translation may not be based on the latest version, please ensure you
+> check the original English version for discrepancies.
+
+# PIE 维护者手册
+
+## 分支策略
+
+目前，我们使用单一的 `main` 分支和功能分支。未来，为了更好地支持补丁版本，我们可能会切换到版本化分支策略。
+
+## 发布流程
+
+确保您拥有要发布的最新版本，例如：
+
+```shell
+# 使用 git reset（注意：会丢弃 `main` 上的任何本地提交）
+git checkout main && git fetch upstream && git reset --hard upstream/main
+# 或者，使用 git pull（使用 `--ff-only` 避免创建合并提交）
+git checkout main && git pull --ff-only upstream main
+```
+
+准备变更日志，设置要发布的版本和里程碑，例如：
+
+```shell
+PIE_VERSION=1.3.0
+PIE_MILESTONE=$PIE_VERSION
+```
+
+> [!TIP]
+> 对于预发布版本，您可以将版本/里程碑设置为不同的值，例如：
+>
+> ```shell
+> PIE_VERSION=1.3.0-alpha.2
+> PIE_MILESTONE=1.3.0
+> ```
+>
+> 这将使用 `1.3.0-alpha.2` 版本进行标记/发布，但会基于 GitHub 中的 `1.3.0` 里程碑生成变更日志。
+
+然后生成变更日志文件：
+
+```shell
+composer require --dev -W jwage/changelog-generator --no-interaction
+vendor/bin/changelog-generator generate --user=php --repository=pie --milestone=$PIE_MILESTONE > CHANGELOG-$PIE_VERSION.md
+git checkout -- composer.*
+composer install
+```
+
+检查您是否对变更日志的内容满意。创建一个签名标签：
+
+```shell
+git tag -s $PIE_VERSION -F CHANGELOG-$PIE_VERSION.md
+git push upstream $PIE_VERSION
+```
+
+发布流水线将运行，它将创建一个**草稿**发布版本，构建 PHAR 文件并附加它。然后，您必须转到 GitHub 上的草稿发布版本，验证一切正确，然后发布该发布版本。
+
+```shell
+rm CHANGELOG-$PIE_VERSION.md
+```
+
diff --git a/docs/zh/supported-extensions.md b/docs/zh/supported-extensions.md
new file mode 100644
index 00000000..043e2ae7
--- /dev/null
+++ b/docs/zh/supported-extensions.md
@@ -0,0 +1,475 @@
+---
+title: 支持的扩展
+order: 4
+en-revision: b595732a62673b53c2509dfeab38a71ee16c88f4
+---
+> [!WARNING]
+> This translation may not be based on the latest version, please ensure you
+> check the original English version for discrepancies.
+
+
+# 支持的扩展
+
+由于 Packagist 是 PIE 包的新家，完整的支持、兼容 PIE 的扩展列表可以在以下位置找到：
+
+* **[https://packagist.org/extensions](https://packagist.org/extensions)**
+
+添加 PIE 支持的过程在[扩展维护者](extension-maintainers.md)文档中有记录。
+
+## PECL 扩展迁移
+
+PECL 仓库仍然有大量尚未添加 PIE 支持的扩展。这是 PECL 上托管的扩展列表，以及它们添加 PIE 支持的状态。如果您发现此处有过时的信息，请提交 [Pull Request](https://github.com/php/pie/pulls)。
+
+### 已支持
+
+以下扩展已经添加了 PIE 支持：
+
+| PECL 扩展      | PIE 扩展                                                                                        |
+|----------------|-----------------------------------------------------------------------------------------------------|
+| amqp           | [php-amqp/php-amqp](https://packagist.org/packages/php-amqp/php-amqp)                               |
+| APCu           | [apcu/apcu](https://packagist.org/packages/apcu/apcu)                                               |
+| apfd           | [m6w6/ext-apfd](https://packagist.org/packages/m6w6/ext-apfd)                                       |
+| ast            | [nikic/php-ast](https://packagist.org/packages/nikic/php-ast)                                       |
+| bcmath         | php/bcmath                                                                                          |
+| bitset         | [pecl/bitset](https://packagist.org/packages/pecl/bitset)                                           |
+| brotli         | [kjdev/brotli](https://packagist.org/packages/kjdev/brotli)                                         |
+| bz2            | php/bz2                                                                                             |
+| calendar       | php/calendar                                                                                        |
+| CSV            | [girgias/csv](https://packagist.org/packages/girgias/csv)                                           |
+| ctype          | php/ctype                                                                                           |
+| curl           | php/curl                                                                                            |
+| dba            | php/dba                                                                                             |
+| decimal        | [php-decimal/ext-decimal](https://packagist.org/packages/php-decimal/ext-decimal)                   |
+| dio            | [pecl/dio](https://packagist.org/packages/pecl/dio)                                                 |
+| dom            | php/dom                                                                                             |
+| ds             | [php-ds/ext-ds](https://packagist.org/packages/php-ds/ext-ds)                                       |
+| enchant        | php/enchant                                                                                         |
+| exif           | php/exif                                                                                            |
+| ev             | [osmanov/pecl-ev](https://packagist.org/packages/osmanov/pecl-ev)                                   |
+| event          | [osmanov/pecl-event](https://packagist.org/packages/osmanov/pecl-event)                             |
+| ffi            | php/ffi                                                                                             |
+| geospatial     | [php-geospatial/geospatial](https://packagist.org/packages/php-geospatial/geospatial)               |
+| gettext        | php/gettext                                                                                         |
+| gmp            | php/gmp                                                                                             |
+| gpio           | [embedded-php/gpio](https://packagist.org/packages/embedded-php/gpio)                               |
+| i2c            | [embedded-php/i2c](https://packagist.org/packages/embedded-php/i2c)                                 |
+| iconv          | php/iconv                                                                                           |
+| imagick        | [imagick/imagick](https://packagist.org/packages/imagick/imagick)                                   |
+| inotify        | [arnaud-lb/inotify](https://packagist.org/packages/arnaud-lb/inotify)                               |
+| intl           | php/intl                                                                                            |
+| jsonpath       | [supermetrics/jsonpath](https://packagist.org/packages/supermetrics/jsonpath)                       |
+| ldap           | php/ldap                                                                                            |
+| mailparse      | [pecl/mailparse](https://packagist.org/packages/pecl/mailparse)                                     |
+| mbstring       | php/mbstring                                                                                        |
+| mcrypt         | [pecl/mcrypt](https://packagist.org/packages/pecl/mcrypt)                                           |
+| memcached      | [php-memcached/php-memcached](https://packagist.org/packages/php-memcached/php-memcached)           |
+| memprof        | [arnaud-lb/memprof](https://packagist.org/packages/arnaud-lb/memprof)                               |
+| mongodb        | [mongodb/mongodb-extension](https://packagist.org/packages/mongodb/mongodb-extension)               |
+| mysqlnd        | php/mysqlnd                                                                                         |
+| mysqli         | php/mysqli                                                                                          |
+| opcache        | php/opcache                                                                                         |
+| opentelemetry  | [open-telemetry/ext-opentelemetry](https://packagist.org/packages/open-telemetry/ext-opentelemetry) |
+| parallel       | [pecl/parallel](https://packagist.org/packages/pecl/parallel)                                       |
+| pcov           | [pecl/pcov](https://packagist.org/packages/pecl/pcov)                                               |
+| pcntl          | php/pcntl                                                                                           |
+| pdo            | php/pdo                                                                                             |
+| pdo_mysql      | php/pdo_mysql                                                                                       |
+| pdo_pgsql      | php/pdo_pgsql                                                                                       |
+| pdo_sqlite     | php/pdo_sqlite                                                                                      |
+| pgsql          | php/pgsql                                                                                           |
+| posix          | php/posix                                                                                           |
+| rdkafka        | [rdkafka/rdkafka](https://packagist.org/packages/rdkafka/rdkafka)                                   |
+| readline       | php/readline                                                                                        |
+| redis          | [phpredis/phpredis](https://packagist.org/packages/phpredis/phpredis)                               |
+| relay          | [cachewerk/relay](https://packagist.org/packages/cachewerk/ext-relay)                               |
+| rpminfo        | [remi/rpminfo](https://packagist.org/packages/remi/rpminfo)                                         |
+| selinux        | [pecl/selinux](https://packagist.org/packages/pecl/selinux)                                         |
+| session        | php/session                                                                                         |
+| shmop          | php/shmop                                                                                           |
+| simdjson       | [awesome/simdjson_plus](https://packagist.org/packages/awesome/simdjson_plus)                       |
+| simplexml      | php/simplexml                                                                                       |
+| snmp           | php/snmp                                                                                            |
+| soap           | php/soap                                                                                            |
+| sockets        | php/sockets                                                                                         |
+| sodium         | php/sodium                                                                                          |                                                                              
+| spi            | [embedded-php/spi](https://packagist.org/packages/embedded-php/spi)                                 |
+| sqlite3        | php/sqlite3                                                                                         |
+| swoole         | [swoole/swoole](https://packagist.org/packages/swoole/swoole)                                       |
+| sysvmsg        | php/sysvmsg                                                                                         |
+| sysvsem        | php/sysvsem                                                                                         |
+| sysvshm        | php/sysvshm                                                                                         |
+| tidy           | php/tidy                                                                                            |
+| timezonedb     | [pecl/timezonedb](https://packagist.org/packages/pecl/timezonedb)                                   |
+| translit       | [derickr/translit](https://packagist.org/packages/derickr/translit)                                 |
+| uart           | [embedded-php/uart](https://packagist.org/packages/embedded-php/uart)                               |
+| uuid           | [pecl/uuid](https://packagist.org/packages/pecl/uuid)                                               |
+| vld            | [derickr/vld](https://packagist.org/packages/derickr/vld)                                           |
+| win32service   | [win32service/win32service](https://packagist.org/packages/win32service/win32service)               |
+| xattr          | [pecl/xattr](https://packagist.org/packages/pecl/xattr)                                             |
+| Xdebug         | [xdebug/xdebug](https://packagist.org/packages/xdebug/xdebug)                                       |
+| xlswriter      | [viest/xlswriter](https://packagist.org/packages/viest/xlswriter)                                   |
+| xml            | php/xml                                                                                             |
+| xmlreader      | php/xmlreader                                                                                       |
+| xmlwriter      | php/xmlwriter                                                                                       |
+| xsl            | php/xsl                                                                                             |
+| xpass          | [remi/xpass](https://packagist.org/packages/remi/xpass)                                             |
+| zip            | php/zip, [pecl/zip](https://packagist.org/packages/pecl/zip)                                        |
+| zlib           | php/zlib                                                                                            |
+| zstd           | [kjdev/zstd](https://packagist.org/packages/kjdev/zstd)                                             |
+
+### 进行中
+
+以下扩展已开始努力添加 PIE 支持：
+
+| PECL 扩展      | 状态                                                                                           |
+|----------------|--------------------------------------------------------------------------------------------------|
+| base58         | ⏰ PR: [jasny/base58-php-ext#14](https://github.com/jasny/base58-php-ext/pull/14)                 |
+| crypto         | ⏰ PR: [bukka/php-crypto#43](https://github.com/bukka/php-crypto/pull/43)                         |
+| dbase          | ⏰ PR: [php/pecl-database-dbase#6](https://github.com/php/pecl-database-dbase/pull/6)             |
+| hdr_histogram  | ⏰ 即将推出: [beberlei/hdrhistogram](https://packagist.org/packages/beberlei/hdrhistogram)     |
+| hrtime         | ⏰ PR: [php/pecl-datetime-hrtime#1](https://github.com/php/pecl-datetime-hrtime/pull/1)           |
+| memcache       | ⏰ PR: [websupport-sk/pecl-memcache#116](https://github.com/websupport-sk/pecl-memcache/pull/116) |
+| yaml           | ⏰ PR: [php/pecl-file_formats-yaml#88](https://github.com/php/pecl-file_formats-yaml/pull/88)     |
+
+### 未开始 / 未知
+
+以下扩展存在于 PECL 上，但尚未添加 PIE 支持，或其状态未知。
+
+* ahocorasick
+* AOP
+* ApacheAccessor
+* apcu_bc
+* APM
+* augeas
+* awscrt
+* bloomy
+* bsdiff
+* bz2_filter
+* cairo_wrapper
+* cassandra
+* cld
+* clips
+* clucene
+* cmark
+* componere
+* couchbase
+* courierauth
+* crack_dll
+* CUBRID
+* cvsclient
+* cybermut
+* datadog_trace
+* dazuko
+* docblock
+* doublemetaphone
+* Druid
+* ecasound
+* ecma_intl
+* eio
+* env
+* esmtp
+* excimer
+* expect
+* fann
+* framegrab
+* functional
+* gearman
+* gender
+* geoip
+* gmagick
+* gnupg
+* graphdat
+* gRPC
+* handlebars
+* hprose
+* http_message
+* ibm_db2
+* ice
+* idn
+* igbinary
+* imap
+* immutable_cache
+* IMS
+* intercept
+* ion
+* ip2location
+* ip2proxy
+* isis
+* jsmin
+* json_post
+* jsonc
+* jsonnet
+* krb5
+* leveldb
+* libsodium
+* lua
+* LuaSandbox
+* lzf
+* markdown
+* maxminddb
+* mcrypt_filter
+* memoize
+* meta
+* mogilefs
+* Molten
+* Mosquitto
+* mqseries
+* msgpack
+* mustache
+* mysql_xdevapi
+* mysqlnd_azure
+* mysqlnd_krb
+* namazu
+* nsq
+* oauth
+* ocal
+* oci8
+* openal
+* opencensus
+* opengl
+* openswoole
+* PAM
+* params
+* parle
+* pcs
+* pcsc
+* PDO_CUBRID
+* PDO_IBM
+* PDO_OCI
+* PDO_SQLANYWHERE
+* pdo_sqlsrv
+* PDO_TAOS
+* pecl_http
+* perforce
+* Phalcon
+* php_trie
+* phpy
+* pinpoint_php
+* PKCS11
+* pledge
+* pq
+* propro
+* protobuf
+* ps
+* pspell
+* psr
+* qqwry
+* quickhash
+* radius
+* raphf
+* rar
+* ref
+* request
+* rnp
+* rrd
+* runkit7
+* sandbox
+* sasl
+* scoutapm
+* scrypt
+* sdl
+* sdl_image
+* sdl_mixer
+* sdl_ttf
+* SeasClick
+* SeasLog
+* SeasSnowflake
+* shape
+* simple_kafka_client
+* skywalking
+* skywalking_agent
+* smbclient
+* solr
+* spplus
+* spread
+* sqlsrv
+* ssdeep
+* ssh2
+* stackdriver_debugger
+* statgrab
+* stem
+* stomp
+* svm
+* svn
+* swoole_serialize
+* syck
+* sync
+* taint
+* tcc
+* TCLink
+* tcpwrap
+* tdb
+* teds
+* Tensor
+* termbox
+* TextCat
+* timecop
+* trace
+* trader
+* tvision
+* ui
+* uopz
+* uploadprogress
+* uv
+* v8
+* v8js
+* var_representation
+* varnish
+* vips
+* wasm
+* weakreference_bc
+* WinBinder
+* WinCache
+* xdiff
+* xhprof
+* xmldiff
+* XMLRPCi
+* xxtea
+* yac
+* yaconf
+* Yaf
+* yar
+* yaz
+* yp
+* zephir_parser
+* zeroconf
+* zlib_filter
+* zookeeper
+
+### 已废弃
+
+以下扩展被认为已废弃：
+
+* amfext
+* APC
+* apd
+* apn
+* archive
+* ares
+* automap
+* axis2
+* bbcode
+* bcompiler
+* big_int
+* binpack
+* BLENC
+* cairo
+* chdb
+* classkit
+* coin_acceptor
+* colorer
+* crack
+* cybercash
+* cyrus
+* DBDO
+* dbplus
+* DBus
+* dbx
+* dom_varimport
+* drizzle
+* enchant
+* fam
+* ffi
+* FreeImage
+* fribidi
+* funcall
+* fuse
+* GDChart
+* gupnp
+* haru
+* hidef
+* html_parse
+* htscanner
+* huffman
+* id3
+* imlib2
+* inclued
+* ingres
+* ircclient
+* Judy
+* kadm5
+* KTaglib
+* lapack
+* lchash
+* libevent
+* maxdb
+* mcve
+* mdbtools
+* memsession
+* memtrack
+* mnogosearch
+* mongo
+* mono
+* mysqlnd_memcache
+* mysqlnd_ms
+* mysqlnd_ngen
+* mysqlnd_qc
+* mysqlnd_uh
+* ncurses
+* Net_Gopher
+* netools
+* newt
+* odbtp
+* oggvorbis
+* opendirectory
+* operator
+* optimizer
+* orng
+* panda
+* Paradox
+* Parse_Tree
+* parsekit
+* pdflib
+* PDO_4D
+* PDO_IDS
+* pdo_user
+* PECL_Gen
+* perl
+* phdfs
+* PHK
+* POP3
+* proctitle
+* protocolbuffers
+* pthreads
+* python
+* qb
+* re2
+* riak
+* rpmreader
+* rsvg
+* rsync
+* runkit
+* sam
+* scream
+* sdo
+* sphinx
+* spidermonkey
+* SPL_Types
+* stats
+* strict
+* sundown
+* swish
+* tidy
+* tk
+* tokyo_tyrant
+* txforward
+* udis86
+* uri_template
+* Valkyrie
+* vpopmail
+* wbxml
+* Weakref
+* win32ps
+* win32ps_dll
+* win32std
+* wxwidgets
+* xcommerce
+* xmlrpc
+* xmms
+* xmp
+* xrange
+* xslcache
+* yami
+* ZendOptimizerPlus
+* zmq
+
diff --git a/docs/zh/usage.md b/docs/zh/usage.md
new file mode 100644
index 00000000..a8410daf
--- /dev/null
+++ b/docs/zh/usage.md
@@ -0,0 +1,328 @@
+---
+title: 使用 PIE
+order: 2
+en-revision: b595732a62673b53c2509dfeab38a71ee16c88f4
+---
+> [!WARNING]
+> This translation may not be based on the latest version, please ensure you
+> check the original English version for discrepancies.
+
+# PIE 使用指南
+
+## 安装 PIE
+
+### 手动安装
+
+- 从[最新发布版本](https://github.com/php/pie/releases)下载 `pie.phar`
+- 使用 `gh attestation verify --owner php pie.phar` 验证 PHAR 的来源
+    - 注意此步骤需要安装 [`gh` CLI 命令](https://github.com/cli/cli/)。
+- 然后可以使用 `php pie.phar <command>` 调用 PIE
+- 可选：将 `pie.phar` 复制到您的 `$PATH`，例如 `cp pie.phar /usr/local/bin/pie`
+    - 如果将 PIE 复制到 `$PATH`，则可以使用 `pie <command>` 调用 PIE
+
+本文档假设您已将 `pie.phar` 移动到 `$PATH`，例如非 Windows 系统上的 `/usr/local/bin/pie`。
+
+### 一键安装
+
+注意这不会验证任何签名，您需要自行承担运行风险，但这会将 PIE 放入非 Windows 系统的 `/usr/local/bin/pie`：
+
+```shell
+curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar \
+  && gh attestation verify --owner php /tmp/pie.phar \
+  && sudo mv /tmp/pie.phar /usr/local/bin/pie \
+  && sudo chmod +x /usr/local/bin/pie
+```
+
+### Docker 安装
+
+PIE 以纯二进制 Docker 镜像发布，因此您可以在 Docker 构建期间轻松安装：
+
+```Dockerfile
+COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie
+```
+
+除了 `bin` 标签（代表最新的纯二进制镜像）外，您还可以使用明确的版本（格式为 `x.y.z-bin`）。使用 [GitHub registry](https://ghcr.io/php/pie) 查找可用标签。
+
+> [!IMPORTANT]
+> 纯二进制镜像不包含 PHP 运行时，因此您不能使用它们来_运行_ PIE。这只是分发 PHAR 文件的另一种方式，您仍然需要自己满足 PIE 的运行时要求。
+
+#### 在 Dockerfile 中使用 PIE 的示例
+
+这是如何在 Docker 镜像中使用 PIE 安装扩展的示例。注意，与 Composer 类似，您需要安装 `unzip`、[Zip](https://www.php.net/manual/zh/book.zip.php) 扩展或 `git`。
+
+```Dockerfile
+FROM php:8.4-cli
+
+# 添加 PIE 用于解压 .zip 文件的 `unzip` 包
+RUN export DEBIAN_FRONTEND="noninteractive"; \
+    set -eux; \
+    apt-get update; apt-get install -y --no-install-recommends unzip; \
+    rm -rf /var/lib/apt/lists/*
+
+# 从最新的 `:bin` 发布版本复制 pie.phar
+COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie
+
+# 使用 PIE 安装扩展...
+RUN pie install asgrim/example-pie-extension
+```
+
+如果您想安装的扩展需要额外的库或其他依赖项，则必须事先安装这些依赖项。
+
+## PIE 的先决条件
+
+运行 PIE 需要 PHP 8.1 或更高版本。但是，您仍然可以使用 PIE 为较旧版本的 PHP 安装扩展。
+
+除了 PHP，PIE 还需要系统上有以下工具才能下载、构建和安装扩展：
+
+- 为运行 PIE 的 PHP 版本启用 `zip` 扩展，或使用 `git` 下载扩展源代码
+- `autoconf`、`automake`、`libtool`、`m4`、`make` 和 `gcc` 来构建扩展
+- PHP 开发工具（如 `php-config` 和 `phpize`）以准备构建扩展。
+
+此外，每个扩展可能有自己的要求，例如额外的库。
+
+> [!TIP]
+> 如果在未安装正确先决条件的情况下运行 PIE，您可能会收到来自 *Box Requirements Checker* 的错误。如果您想尝试运行，请指定环境变量 `BOX_REQUIREMENT_CHECKER=0`。
+>
+> Linux 上的示例：
+> ```shell
+> $ BOX_REQUIREMENT_CHECKER=0 pie install foo/bar
+> ```
+
+### 使用 Linux
+
+在基于 Debian 的系统上，您可以使用以下命令安装所需工具：
+
+```shell
+sudo apt-get install git autoconf automake libtool m4 make gcc
+```
+
+在基于 Red Hat 的系统上，您可以使用以下命令安装所需工具：
+
+```shell
+sudo yum install git autoconf automake libtool m4 make gcc
+```
+
+### 使用 macOS
+
+在 macOS 上，您可以使用 [Homebrew](https://brew.sh) 安装所需工具：
+
+```shell
+brew install git autoconf automake libtool m4 make gcc
+```
+
+### 使用 Windows
+
+在 Windows 上，扩展通常作为预编译的二进制文件分发。您无需自己构建扩展，而是将其作为 DLL 文件下载并放置在 PHP 扩展目录中。
+
+## 下载、构建或安装扩展
+
+PIE 能够：
+
+ - 仅下载扩展，使用 `pie download ...`，
+ - 下载并构建扩展，使用 `pie build ...`，
+ - 或最常见的，下载、构建和安装扩展，使用 `pie install ...`
+
+使用 PIE 安装扩展时，必须使用其 Composer 包名称。您可以在 [https://packagist.org/extensions](https://packagist.org/extensions) 上找到 PIE 兼容包的列表。
+
+知道扩展名称后，您可以使用以下命令安装：
+
+```shell
+pie install <vendor>/<package>
+
+# 例如：
+pie install xdebug/xdebug
+```
+
+这将把 Xdebug 扩展安装到用于调用 PIE 的 PHP 版本中，使用与该 PHP 版本兼容的最新稳定版本的 Xdebug。
+
+### 使用 PIE 为不同的 PHP 版本安装扩展
+
+如果您试图为不同版本的 PHP 安装扩展，在非 Windows 系统上可以使用 `--with-php-config` 选项指定：
+
+```shell
+pie install --with-php-config=/usr/bin/php-config7.2 my/extension
+```
+
+在 Windows 上，您可以使用 `--with-php-path` 选项提供 `php` 可执行文件本身的路径。这是 Windows 上的一个示例，其中使用 PHP 8.1 运行 PIE，但我们想为 PHP 8.3 下载扩展：
+
+```shell
+> C:\php-8.1.7\php.exe C:\pie.phar install --with-php-path=C:\php-8.3.6\php.exe example/example-pie-extension
+```
+
+您可能还需要为目标 PHP 版本使用相应的 `phpize` 命令，可以使用 `--with-phpize-path` 选项指定：
+
+```shell
+pie install --with-phpize-path=/usr/bin/phpize7.2 my/extension
+```
+
+### 版本约束和稳定性
+
+使用 PIE 安装扩展时，可以选择指定版本约束：
+
+```bash
+pie install <vendor>/<package>:<version-constraint>
+```
+
+如果给出 `version-constraint`，则尝试安装与允许版本匹配的该版本。版本约束使用与 Composer 相同的格式解析，以及最小稳定性。
+
+* `^1.0` 将安装与 `1.0.0` 及以上版本向后兼容的最新稳定版本，根据语义化版本。
+  [详见 Composer 文档](https://getcomposer.org/doc/articles/versions.md#caret-version-range-)。
+* `^2.3@beta` 将安装与 `2.3.0` 及以上版本向后兼容的最新 beta 版本（例如 `2.3.0-beta.3`）。
+* `dev-main` 将安装命令执行时 `main` 分支上的最新提交。这不适用于 Windows，因为没有带 Windows 二进制文件的发布版本。
+* `dev-main#07f454ad797c30651be8356466685b15331f72ff` 将安装 `#` 后的提交 sha 表示的特定提交，在这种情况下将安装提交 `07f454ad797c30651be8356466685b15331f72ff`。这不适用于 Windows，因为没有带 Windows 二进制文件的发布版本。
+
+当给出 `version-constraint` 时，它会被检查并直接添加到目标 PHP 版本的 `pie.json` 中，例如：
+
+```shell
+$ pie install "xdebug/xdebug:^3.4.3 || 3.4.1"
+```
+
+将在 `pie.json` 中设置以下内容：
+
+```json
+{
+    "require": {
+        "xdebug/xdebug": "^3.4.3 || 3.4.1"
+    }
+}
+```
+
+如果未给出 `version-constraint`，则尝试安装任何兼容的最新稳定版本。PIE 始终优先选择稳定版本。
+
+### 指定配置选项
+
+编译扩展时，某些扩展需要向 `./configure` 命令传递额外参数。这些参数通常用于启用或禁用某些功能，或提供未自动检测到的库路径。
+
+要确定扩展可用的配置选项，可以使用 `pie info <vendor>/<package>`，它将返回一个列表，例如：
+
+```text
+Configure options:
+    --enable-some-functionality  (whether to enable some additional functionality provided)
+    --with-some-library-name=?  (Path for some-library)
+```
+
+然后可以使用无、部分或全部指定的配置选项安装上述示例扩展，一些示例：
+
+```shell
+pie install example/some-extension
+pie install example/some-extension --enable-some-functionality
+pie install example/some-extension --with-some-library-name=/path/to/the/lib
+pie install example/some-extension --with-some-library-name=/path/to/the/lib --enable-some-functionality
+```
+
+### 配置 INI 文件
+
+PIE 会自动尝试通过在适当的 INI 文件中添加 `extension=...` 或 `zend_extension=...` 来启用扩展。如果您想禁用此行为，请在 `pie install` 命令中传递 `--skip-enable-extension` 标志。尝试启用扩展时使用以下技术：
+
+ * 如果使用 deb.sury.org 发行版，使用 `phpenmod`
+ * 如果使用 Docker 的 PHP 镜像，使用 `docker-php-ext-enable`
+ * 如果配置了"附加 .ini 文件"路径，则添加新文件到该路径
+ * 如果配置了标准 php.ini，则追加到 php.ini
+
+如果这些技术都不起作用，或者您使用了 `--skip-enable-extension` 标志，PIE 将警告您扩展未启用，并注意您必须自己启用扩展。
+
+### 添加非 Packagist.org 仓库
+
+有时您可能想从 Packagist.org 以外的包仓库（如 [Private Packagist](https://packagist.com/)）安装扩展，或从本地目录安装。由于 PIE 很大程度上基于 Composer，可以使用其他一些仓库类型：
+
+* `pie repository:add [--with-php-config=...] path /path/to/your/local/extension`
+* `pie repository:add [--with-php-config=...] vcs https://github.com/youruser/yourextension`
+* `pie repository:add [--with-php-config=...] composer https://repo.packagist.com/your-private-packagist/`
+* `pie repository:add [--with-php-config=...] composer packagist.org`
+
+`repository:*` 命令都支持可选的 `--with-php-config` 标志，允许您指定要使用的 PHP 安装（例如，如果一台机器上有多个 PHP 安装）。上述添加的仓库也可以使用相反的 `repository:remove` 命令删除：
+
+* `pie repository:remove [--with-php-config=...] /path/to/your/local/extension`
+* `pie repository:remove [--with-php-config=...] https://github.com/youruser/yourextension`
+* `pie repository:remove [--with-php-config=...] https://repo.packagist.com/your-private-packagist/`
+* `pie repository:remove [--with-php-config=...] packagist.org`
+
+注意，在 `repository:remove` 中不需要指定仓库类型，只需提供 URL。
+
+您可以使用以下命令列出目标 PHP 安装的仓库：
+
+* `pie repository:list [--with-php-config=...]`
+
+## 检查并安装项目缺失的扩展
+
+当在 PHP 项目工作目录中时，可以使用 `pie install` 来检查项目所需的扩展是否存在。如果缺少扩展，PIE 将尝试找到安装候选并以交互方式询问您是否要安装。例如：
+
+```
+$ pie install
+🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
+You are running PHP 8.3.19
+Target PHP installation: 8.3.19 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.3)
+Checking extensions for your project your-vendor/your-project
+requires: curl ✅ Already installed
+requires: intl ✅ Already installed
+requires: json ✅ Already installed
+requires: example_pie_extension ⚠️  Missing
+
+The following packages may be suitable, which would you like to install:
+  [0] None
+  [1] asgrim/example-pie-extension: Example PIE extension
+ > 1
+   > 🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
+   > This command may need elevated privileges, and may prompt you for your password.
+   > You are running PHP 8.3.19
+   > Target PHP installation: 8.3.19 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.3)
+   > Found package: asgrim/example-pie-extension:2.0.2 which provides ext-example_pie_extension
+   ... (snip) ...
+   > ✅ Extension is enabled and loaded in /usr/bin/php8.3
+
+Finished checking extensions.
+```
+
+## 与 PECL 的比较
+
+由于 PIE 是 PECL 的替代品，这里是您可能熟悉的 PECL 命令与 PIE 中近似等效命令的比较。请注意，某些概念在 PIE 中有所不同或被省略，因为它们可能不适用于新工具。
+
+| PECL                           | PIE                                                                                                                     |
+|--------------------------------|-------------------------------------------------------------------------------------------------------------------------|
+| `pecl build xdebug`            | `pie build xdebug/xdebug`                                                                                               |
+| `pecl bundle xdebug`           | `pie download xdebug/xdebug`                                                                                            |
+| `pecl channel-add channel.xml` | `pie repository:add vcs https://github.com/my/extension`                                                                |
+| `pecl channel-alias`           |                                                                                                                         |
+| `pecl channel-delete channel`  | `pie repository:remove https://github.com/my/extension`                                                                 |
+| `pecl channel-discover`        |                                                                                                                         |
+| `pecl channel-login`           |                                                                                                                         |
+| `pecl channel-logout`          |                                                                                                                         |
+| `pecl channel-update`          |                                                                                                                         |
+| `pecl clear-cache`             |                                                                                                                         |
+| `pecl config-create`           |                                                                                                                         |
+| `pecl config-get`              |                                                                                                                         |
+| `pecl config-help`             |                                                                                                                         |
+| `pecl config-set`              |                                                                                                                         |
+| `pecl config-show`             |                                                                                                                         |
+| `pecl convert`                 |                                                                                                                         |
+| `pecl cvsdiff`                 |                                                                                                                         |
+| `pecl cvstag`                  |                                                                                                                         |
+| `pecl download xdebug`         | `pie download xdebug/xdebug`                                                                                            |
+| `pecl download-all`            |                                                                                                                         |
+| `pecl info xdebug`             | `pie info xdebug/xdebug`                                                                                                |
+| `pecl install xdebug`          | `pie install xdebug/xdebug`                                                                                             |
+| `pecl list`                    | `pie show`                                                                                                              |
+| `pecl list-all`                | 访问 [Packagist 扩展列表](https://packagist.org/extensions)                                                             |
+| `pecl list-channels`           | `pie repository:list`                                                                                                   |
+| `pecl list-files`              |                                                                                                                         |
+| `pecl list-upgrades`           |                                                                                                                         |
+| `pecl login`                   |                                                                                                                         |
+| `pecl logout`                  |                                                                                                                         |
+| `pecl makerpm`                 |                                                                                                                         |
+| `pecl package`                 | Linux - 仅标记发布版本。Windows - 使用 [`php/php-windows-builder` action](https://github.com/php/php-windows-builder)   |
+| `pecl package-dependencies`    |                                                                                                                         |
+| `pecl package-validate`        | 在您的扩展检出中：`composer validate`                                                                                   |
+| `pecl pickle`                  |                                                                                                                         |
+| `pecl remote-info xdebug`      | `pie info xdebug/xdebug`                                                                                                |
+| `pecl remote-list`             | 访问 [Packagist 扩展列表](https://packagist.org/extensions)                                                             |
+| `pecl run-scripts`             |                                                                                                                         |
+| `pecl run-tests`               |                                                                                                                         |
+| `pecl search`                  | 访问 [Packagist 扩展列表](https://packagist.org/extensions)                                                             |
+| `pecl shell-test`              |                                                                                                                         |
+| `pecl sign`                    |                                                                                                                         |
+| `pecl svntag`                  |                                                                                                                         |
+| `pecl uninstall`               |                                                                                                                         |
+| `pecl update-channels`         |                                                                                                                         |
+| `pecl upgrade xdebug`          | `pie install xdebug/xdebug`                                                                                             |
+| `pecl upgrade-all`             |                                                                                                                         |
+