From a46ce365a124371e088605c63384557d491faeb4 Mon Sep 17 00:00:00 2001
From: cotore-game <102813037+cotore-game@users.noreply.github.com>
Date: Sun, 9 Aug 2026 04:54:01 +0900
Subject: [PATCH 1/3] docs: add English and Japanese guides

---
 CONTRIBUTING.md | 154 ++++++++++++++++
 README-JA.md    | 281 +++++++++++++++++++++++++++++
 README.md       | 467 ++++++++++++++++--------------------------------
 3 files changed, 585 insertions(+), 317 deletions(-)
 create mode 100644 CONTRIBUTING.md
 create mode 100644 README-JA.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..3d81808
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,154 @@
+# Contributing
+
+Thanks for helping improve mcserver-compose-kit. Small fixes are welcome. If a change affects commands, configuration, or generated server files, explain the user-facing effect in the pull request.
+
+## Before you start
+
+- Do not commit `config.yml`, generated `.env` files, Playit secret keys, world data, or other private server files.
+- Keep changes focused. Unrelated cleanup is easier to review in a separate pull request.
+- Use LF line endings for shell scripts and text files.
+- Keep command output plain. Avoid adding decorative emoji to shell output.
+- User-facing text belongs in the locale catalogs rather than directly in a shell script.
+
+For a larger behavioral change, opening an issue first is useful, but it is not required for documentation and translation fixes.
+
+## Development setup
+
+Clone the repository inside WSL2:
+
+```bash
+git clone https://github.com/cotore-game/mcserver-compose-kit.git
+cd mcserver-compose-kit
+```
+
+Create a branch from the current development base:
+
+```bash
+git switch develop
+git pull --ff-only
+git switch -c feat/short-description
+```
+
+Use a `fix/`, `docs/`, or `refactor/` prefix when it describes the change better. Work is normally collected in `develop`; a release pull request moves it from `develop` to `main`.
+
+You can run the checked-out version without installing it:
+
+```bash
+bash mcserver-kit --help
+bash mcserver-kit create
+```
+
+The local installer can be tested without downloading a release:
+
+```bash
+bash install.sh
+```
+
+This updates the installed program while preserving an existing user configuration and MCID templates.
+
+## Tests
+
+Run the specification tests:
+
+```bash
+bash tests/run-tests.sh
+```
+
+Run syntax and locale checks:
+
+```bash
+bash -n mcserver-kit home-tui.sh new-minecraft-server.sh setup.sh reset.sh \
+  config-tui.sh server-manager.sh server-properties-tui.sh lang.sh \
+  install.sh uninstall.sh tests/run-tests.sh
+python3 -m py_compile scripts/*.py
+python3 scripts/validate-locales.py
+```
+
+Run ShellCheck if it is installed:
+
+```bash
+shellcheck -x mcserver-kit home-tui.sh new-minecraft-server.sh setup.sh \
+  reset.sh config-tui.sh server-manager.sh server-properties-tui.sh \
+  lang.sh install.sh uninstall.sh tests/run-tests.sh
+```
+
+The ZIP import tests need both `zip` and `unzip`. They are skipped locally when `zip` is unavailable. GitHub Actions installs both packages and runs the complete suite.
+
+## Adding or changing user-facing text
+
+English is the source catalog. When adding a message:
+
+1. Add the key and English value to `locales/en.json`.
+2. Add the same key to every other `locales/*.json` file.
+3. Call it from shell code with `tr message.key`.
+4. Pass substitutions as additional arguments, for example `tr server.not_found "$server_id"`.
+5. Run the locale validator and specification tests.
+
+Do not use user input as a translation key. Keep keys stable and describe their purpose, such as `home.select_server`.
+
+Values are passed to Bash `printf`. Preserve placeholders such as `%s` and their order in every translation. Write a literal percent sign as `%%` when needed.
+
+## Adding a language
+
+Locale files use a short language code as the filename. For example, a German catalog would be `locales/de.json`.
+
+1. Copy the English catalog:
+
+   ```bash
+   cp locales/en.json locales/de.json
+   ```
+
+2. Translate values only. Do not rename, add, or remove keys.
+
+3. Keep these details unchanged where they are part of program behavior:
+
+   - placeholders such as `%s`
+   - command names such as `mcserver-kit setup`
+   - URLs and file paths
+   - JSON escapes such as `\n`
+
+4. Validate the catalog:
+
+   ```bash
+   python3 scripts/validate-locales.py
+   ```
+
+   The validator checks JSON structure, empty values, missing keys, and extra keys against `locales/en.json`.
+
+5. Preview one command without changing the saved language:
+
+   ```bash
+   bash mcserver-kit --lang de --help
+   ```
+
+6. Add the language to the interactive selector in `home-tui.sh`. The first value is the language code, the second is the label shown to users:
+
+   ```bash
+   de Deutsch OFF
+   ```
+
+7. Add a persistent CLI option in `lang.sh` and update `lang.usage` in every catalog. The existing `--en` and `--ja` branches show the expected structure.
+
+8. Add specification coverage for the new language selection and run the full test suite.
+
+9. Update the language section in `README.md` and any translated README you maintain.
+
+A language pull request should include the catalog, selector and CLI wiring, tests, and documentation together. A correction to an existing translation can usually change only the affected catalog and related documentation.
+
+Machine translation is acceptable as a draft, but please review the result in the actual TUI. Short labels, terminal width, and Minecraft terminology matter more than literal wording.
+
+## Pull requests
+
+Before opening a pull request:
+
+- Run the checks relevant to your change.
+- Confirm that no secrets or generated server data are staged.
+- Update documentation when behavior or commands change.
+- Use a clear title, preferably with a Conventional Commits prefix such as `feat:`, `fix:`, `docs:`, or `test:`.
+- Summarize what changed and how it was tested.
+
+Pull requests targeting `main` are checked by GitHub Actions. The required `test` job must pass before merging.
+
+## Releases
+
+Releases are created from tags named `v*`. The release workflow runs all checks, builds `mcserver-compose-kit.tar.gz` and its SHA-256 file, and creates a GitHub Release. Release notes are reviewed and edited after the generated draft is created.
diff --git a/README-JA.md b/README-JA.md
new file mode 100644
index 0000000..1e738d9
--- /dev/null
+++ b/README-JA.md
@@ -0,0 +1,281 @@
+# mcserver-compose-kit
+
+日本語 | [English](README.md)
+
+`mcserver-compose-kit`は、WSL2上でMinecraft Java Editionサーバーを作成・管理するツールです。配布マップなどの既存ワールドを取り込む用途を中心にしていますが、ワールドを指定せずに新規サーバーを作ることもできます。
+
+サーバーごとに独立したDocker Compose構成を作成します。`mcserver-kit`で対話式ホーム画面を開くほか、サブコマンドを直接実行することもできます。
+
+## 主な機能
+
+- フォルダまたはZIPからワールドを取り込み
+- ZIP内に余分な階層があっても`level.dat`を基準にワールドを検出
+- 保存されたMinecraftバージョンを検出し、対応するJavaイメージを提案
+- サーバーごとに`compose.yaml`、`.env`、`server.env`、`data/`を作成
+- 起動、停止、再起動、状態確認、ログ表示、Minecraft設定を一元管理
+- ホワイトリストとOPでMCIDテンプレートを再利用
+- Playitとサーバーリソースパックに対応
+- 利用可能な場合はWindowsのファイル選択画面と、日本語を入力しやすいMOTD編集画面を使用
+- JSONカタログによる英語・日本語表示
+
+## 必要な環境
+
+- WindowsとWSL2
+- 対象ディストリビューションでWSL Integrationを有効にしたDocker Desktop
+- Docker Compose v2
+- Bash
+
+インストーラーは`python3`、`unzip`、`whiptail`を確認します。Ubuntuで不足している場合は、確認後に`apt`で導入できます。
+
+インストール前にWSLのターミナルからDockerを確認してください。
+
+```bash
+docker version
+docker compose version
+```
+
+## インストール
+
+最新リリースをインストールします。
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/cotore-game/mcserver-compose-kit/main/install.sh | bash
+```
+
+バージョンを固定する場合：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/cotore-game/mcserver-compose-kit/main/install.sh | \
+  bash -s -- --version v1.0.0
+```
+
+インストーラーはリリースの圧縮ファイルを取得し、SHA-256を検証して`~/.local/share/mcserver-compose-kit`へ配置します。また、`~/.local/bin`用のPATH設定を管理ブロックとして`~/.bashrc`へ追加します。
+
+現在開いているシェルには自動反映しません。新しいターミナルを開くか、インストーラーが表示した`source`コマンドを実行してください。
+
+同じインストールコマンドを再実行すると本体を更新します。既存の設定とMCIDテンプレートは上書きしません。
+
+## 初回設定
+
+初期言語は英語です。日本語で設定する場合は、先に次を実行します。
+
+```bash
+mcserver-kit lang --ja
+```
+
+続けて初回設定を行います。
+
+```bash
+mcserver-kit setup
+```
+
+主な設定項目：
+
+- OwnerのMinecraft ID
+- Minecraft EULAへの同意
+- ホワイトリストとOPの初期設定
+- Owner以外のMCID
+- Playit設定
+- バージョンを検出できない場合のMinecraftバージョン
+- Javaメモリ
+- 作成後すぐ起動するか
+- Windowsの入力画面を使うか
+- サーバー作成先
+
+EULAへ同意し、setupを最後まで完了するまではサーバーを作成できません。
+
+## ホーム画面を開く
+
+```bash
+mcserver-kit
+```
+
+ホーム画面から、サーバー作成・管理、全体設定、MCIDテンプレート、言語、動作環境診断、ヘルプへ進めます。矢印キーで選択し、Enterで決定します。
+
+パイプやCIなどの非対話環境で引数なし実行した場合は、ホーム画面ではなくヘルプを表示します。
+
+## サーバーを作成する
+
+ホーム画面の「サーバーを作成」を選ぶか、次を実行します。
+
+```bash
+mcserver-kit create
+```
+
+ワールドのフォルダまたはZIPを選択できます。ZIPを展開した直下にもう1つフォルダがあるような構成でも、その下から`level.dat`を持つワールドを探します。
+
+`level.dat`に保存されたMinecraftバージョンを検出できた場合は、バージョン入力の初期値になります。検出できなければ、全体設定の既定値を使用します。必要なら別の値を手入力できます。
+
+入力例：
+
+```text
+26.2
+1.21
+1.21.2
+LATEST
+```
+
+`docker.java_image_tag: "auto"`では次のようにJavaイメージを選びます。
+
+| Minecraftバージョン | イメージタグ |
+| --- | --- |
+| `26.x`または`LATEST` | `java25` |
+| `1.20.5`以降の1.x | `java21` |
+| `1.18`から`1.20.4` | `java17` |
+
+それより古いバージョンは、設定ファイルでDockerイメージタグを明示してください。
+
+Javaメモリには`8`、`8G`、`8192M`などを入力できます。単位のない数値はGiBとして扱います。
+
+既定の生成先：
+
+```text
+~/minecraftServer/<server-id>/
+├── compose.yaml
+├── .env
+├── server.env
+├── README.txt
+└── data/
+    └── world/
+```
+
+作成中は現在の処理を表示します。起動前には`docker compose config --quiet`で生成したCompose構成を検証します。
+
+## サーバーを管理する
+
+管理対象の一覧：
+
+```bash
+mcserver-kit list
+```
+
+ホーム画面を使わず、サーバーIDを指定して直接操作することもできます。
+
+```bash
+mcserver-kit server <server-id> start
+mcserver-kit server <server-id> stop
+mcserver-kit server <server-id> shutdown
+mcserver-kit server <server-id> restart
+mcserver-kit server <server-id> status
+mcserver-kit server <server-id> logs
+mcserver-kit server <server-id> logs --no-follow
+mcserver-kit server <server-id> down
+mcserver-kit server <server-id> properties
+```
+
+`stop`と`shutdown`はコンテナを削除せず停止します。`down`はコンテナとネットワークを削除します。いずれもサーバーの`data/`は削除しません。
+
+## Minecraft設定を編集する
+
+ホーム画面から「サーバー設定」を開くか、次を実行します。
+
+```bash
+mcserver-kit server <server-id> properties
+```
+
+MOTD、難易度、ゲームモード、最大人数、オンラインモード、ホワイトリスト、OP、飛行、コマンドブロック、PvP、描画・シミュレーション距離、スポーン保護、ネザー、Mob/NPC生成、リソースパックなどを編集できます。
+
+ツールが管理する設定の正本は各サーバーの`server.env`です。Docker Composeが値を`itzg/minecraft-server`へ渡し、コンテナ起動時に`server.properties`へ反映します。
+
+古い形式のサーバーを初めて開く場合は、移行前に確認画面を表示します。元のComposeは`compose.yaml.mcserver-kit.bak`として保存します。
+
+## MCIDテンプレート
+
+テンプレートは次の場所にあるテキストファイルです。
+
+```text
+~/.config/mcserver-compose-kit/mcid-templates/
+```
+
+1行に1つMinecraft IDを書きます。空行と`#`以降は無視されます。`${OWNER}`は全体設定にあるOwnerのIDへ置き換わります。
+
+```text
+${OWNER}
+ExamplePlayer
+AnotherPlayer
+```
+
+ホーム画面または次のコマンドから管理できます。
+
+```bash
+mcserver-kit templates
+```
+
+## Windows入力画面
+
+有効な場合は、WSLからWindows PowerShellを呼び出し、Explorer形式のフォルダ・ZIP選択画面を開きます。MOTDもWindows側の画面で入力できるため、ターミナル上の日本語IMEでBackspaceなどが扱いにくい問題を避けられます。
+
+Windows側の画面を利用できない場合やキャンセルした場合は、ターミナル入力へ戻ります。全体設定画面から無効にするか、設定ファイルへ次を記述します。
+
+```yaml
+ui:
+  windows_dialogs: false
+```
+
+## 設定と秘密情報
+
+ユーザー設定は次に保存します。
+
+```text
+~/.config/mcserver-compose-kit/config.yml
+```
+
+一般的な項目は`mcserver-kit config`から変更できます。ファイルを直接編集することもできます。
+
+設定ファイルにはPlayitのSecret Keyが含まれる場合があります。Gitへコミットしないでください。各サーバーの`.env`と`server.env`にも非公開の値が含まれる可能性があります。
+
+## 言語
+
+表示言語を保存する場合：
+
+```bash
+mcserver-kit lang --en
+mcserver-kit lang --ja
+```
+
+1回のコマンドだけ言語を指定する場合：
+
+```bash
+mcserver-kit --lang ja --help
+```
+
+翻訳の追加・修正方法は[CONTRIBUTING.md](CONTRIBUTING.md#adding-a-language)を参照してください。
+
+## リセット・更新・アンインストール
+
+作成済みサーバーとインストール本体を残し、設定とMCIDテンプレートだけを削除します。
+
+```bash
+mcserver-kit reset
+```
+
+更新はインストーラーをもう一度実行します。既存のユーザー設定は保持されます。
+
+設定を残して本体だけを削除する場合：
+
+```bash
+mcserver-kit uninstall
+```
+
+本体とユーザー設定を削除する場合：
+
+```bash
+mcserver-kit uninstall --purge
+```
+
+アンインストール後は新しいターミナルを開いてください。現在のBashに削除済みコマンドの場所が残っている場合は、`hash -r`でキャッシュを消せます。
+
+## 注意事項
+
+- 同じホストポートを使うサーバーは同時に起動できません。
+- 同じSecret Keyを使うPlayitエージェントを同時に起動しないでください。
+- MODローダーが必要な配布マップは、現在のVANILLA用テンプレートでは設定できません。
+- サーバーの`data/`を削除するとワールドと進行状況を失います。
+
+## コントリビュート
+
+不具合報告、ドキュメント修正、翻訳の追加を歓迎します。PRを作る前に[CONTRIBUTING.md](CONTRIBUTING.md)を確認してください。
+
+## ライセンス
+
+[LICENSE](LICENSE)を参照してください。
diff --git a/README.md b/README.md
index 82be9e7..a00d1aa 100644
--- a/README.md
+++ b/README.md
@@ -1,447 +1,280 @@
-# mcserver-tool-kit
+# mcserver-compose-kit
 
-WSL2とDocker Desktopを使い、Minecraft Javaの配布ワールドから独立したサーバー構成を作る対話式ツールです。
+[日本語](README-JA.md) | English
 
-サーバーごとに`compose.yaml`、`.env`、`data/world`を生成し、確認後にそのまま起動することもできます。
+`mcserver-compose-kit` creates and manages Minecraft Java Edition servers from WSL2. It is aimed at downloaded adventure maps and other prebuilt worlds, but it also works without an imported world.
 
-## 簡単インストール
+The toolkit creates an independent Docker Compose project for each server. Run `mcserver-kit` to open the terminal dashboard, or use its subcommands directly from scripts.
 
-Docker Desktop、WSL2、Docker DesktopのWSL Integrationが設定済みであることを前提とします。
+## What it does
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/cotore-game/mcserver-compose-kit/main/install.sh | bash
-```
+- Imports a world from a folder or ZIP archive
+- Finds `level.dat` inside common nested archive layouts
+- Detects the saved Minecraft version and suggests a matching Java image
+- Creates a separate `compose.yaml`, `.env`, `server.env`, and `data/` directory for each server
+- Manages start, stop, restart, status, logs, and server settings
+- Reuses MCID templates for the whitelist and operator list
+- Supports Playit and server resource packs
+- Uses Windows file dialogs and a Windows IME-friendly MOTD editor when available
+- Provides English and Japanese messages through JSON locale catalogs
 
-バージョンを固定する場合は、`bash -s --`以降へ指定します。
+## Requirements
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/cotore-game/mcserver-compose-kit/main/install.sh | \
-  bash -s -- --version v0.2.0
-```
-
-`MCSERVER_KIT_VERSION=v0.2.0`環境変数でも指定できます。省略時は最新Releaseを使用します。
+- Windows with WSL2
+- Docker Desktop with WSL Integration enabled for your distribution
+- Docker Compose v2
+- Bash
 
-インストーラーは最新のGitHub Releaseを取得してSHA-256を検証します。不足している`python3`や`unzip`は、確認後に`sudo apt`で導入できます。インストール後は次で起動します。
+The installer checks for `python3`, `unzip`, and `whiptail`. On Ubuntu, it can install missing packages with `apt` after asking for confirmation.
 
-インストーラーは`~/.bashrc`へ管理済みのPATH設定を追加します。現在開いているターミナルには自動反映しないため、表示された`source ~/.bashrc`を実行するか、ターミナルを開き直してください。インストール直後にsetupは自動起動しません。
+Check Docker from your WSL terminal before installing:
 
 ```bash
-mcserver-kit setup
-mcserver-kit
+docker version
+docker compose version
 ```
 
-主なサブコマンド：
+## Install
+
+Install the latest release:
 
 ```bash
-mcserver-kit                 # 対話式ホーム画面を開く
-mcserver-kit create          # 新しいサーバーを作成
-mcserver-kit setup           # 初回設定・再設定
-mcserver-kit uninstall       # 設定を残してアンインストール
-mcserver-kit uninstall --purge
-mcserver-kit --help
+curl -fsSL https://raw.githubusercontent.com/cotore-game/mcserver-compose-kit/main/install.sh | bash
 ```
 
-引数なしで起動すると、ASCIIアートロゴ付きのホーム画面から、サーバー一覧・作成・起動・停止・ログ・設定・言語・診断を選べます。矢印キーで項目を選択し、Enterで決定します。スクリプトや自動化では従来どおり各サブコマンドを直接利用できます。
+Install a specific release:
 
-### Language / 言語
+```bash
+curl -fsSL https://raw.githubusercontent.com/cotore-game/mcserver-compose-kit/main/install.sh | \
+  bash -s -- --version v1.0.0
+```
 
-The default language is English. Save a persistent language preference with:
+The installer downloads the release archive, verifies its SHA-256 checksum, and installs the program under `~/.local/share/mcserver-compose-kit`. It also adds a managed PATH block for `~/.local/bin` to `~/.bashrc`.
 
-初期言語は英語です。日本語へ永続的に変更する場合：
+The current shell is not reloaded automatically. Open a new terminal, or run the `source` command printed by the installer.
 
-```bash
-mcserver-kit lang --ja
-mcserver-kit lang --en
-```
+Re-running the installer updates the program files. It does not overwrite an existing configuration or MCID templates.
 
-You can also override the language for one command only.
+## First setup
 
-コマンド1回だけ言語を上書きすることもできます。
+The default language is English. To use Japanese, set it before setup:
 
 ```bash
-mcserver-kit --lang en --help
-mcserver-kit --lang ja setup
+mcserver-kit lang --ja
 ```
 
-Translations are stored in`locales/*.json`. To add a language, copy`locales/en.json`, translate the values without changing the keys, and submit a pull request.
-
-翻訳は`locales/*.json`にあります。言語を追加する場合は`locales/en.json`を複製し、キーを変えずに値を翻訳してPRを作成してください。
+Then run:
 
 ```bash
-python3 scripts/validate-locales.py
+mcserver-kit setup
 ```
 
-CI verifies JSON syntax, empty translations, and key parity with the English catalog.
+Setup asks for:
 
-保存先は次のとおりです。
+- Owner Minecraft ID
+- Minecraft EULA acceptance
+- Whitelist and operator defaults
+- Additional MCIDs
+- Playit settings
+- Fallback Minecraft version and Java memory
+- Whether to start a server after creation by default
+- Whether to use Windows dialogs
+- Server destination directory
 
-- 本体: `~/.local/share/mcserver-compose-kit`
-- 設定とMCIDテンプレート: `~/.config/mcserver-compose-kit`
-- 起動コマンド: `~/.local/bin/mcserver-kit`
+The EULA must be accepted and setup must finish before a server can be created.
 
-同じインストールコマンドを再実行すると、本体だけを更新して設定を保持します。設定をやり直す場合：
+## Open the dashboard
 
 ```bash
-mcserver-kit setup
+mcserver-kit
 ```
 
-アンインストール時は通常、設定を残します。
+The dashboard includes server creation and management, global settings, MCID templates, language selection, diagnostics, and help. Use the arrow keys to select an item and Enter to open it.
 
-```bash
-mcserver-kit uninstall
-```
+Running `mcserver-kit` without arguments in a non-interactive environment prints help instead of opening the dashboard.
 
-設定とMCIDテンプレートも含めて削除する場合：
+## Create a server
+
+Choose **Create server** from the dashboard, or run:
 
 ```bash
-mcserver-kit uninstall --purge
+mcserver-kit create
 ```
 
-## Windows入力ダイアログ
+You can select a world folder or ZIP archive. If an archive contains an extra top-level folder, the toolkit searches below it for the directory containing `level.dat`.
 
-WSLからWindows PowerShellを呼び、ExplorerによるZIP／フォルダ選択と、Windows IMEを使えるMOTD入力画面を表示します。追加のWindowsアプリは不要です。
+The version stored in `level.dat` becomes the default at the version prompt. If it cannot be detected, the configured fallback version is used. You can always type a different value.
 
-Windowsダイアログを利用できない場合やキャンセルした場合は、従来のターミナル入力へ戻ります。無効にする場合は`config.yml`へ次を設定します。
+Examples of accepted versions:
 
-```yaml
-ui:
-  windows_dialogs: false
+```text
+26.2
+1.21
+1.21.2
+LATEST
 ```
 
-## 主な機能
+With `docker.java_image_tag: "auto"`, the Java image is selected as follows:
 
-- フォルダまたはZIP形式の配布ワールドを取り込み
-- Minecraftバージョンに合わせたJavaイメージの自動選択
-- 数字だけでも指定できるJavaメモリ設定
-- MCIDテンプレートをホワイトリストとOPの両方で再利用
-- オーナーMCIDを`${OWNER}`としてテンプレートへ展開
-- リソースパックURL、SHA-1、任意のUUIDを設定
-- Playitエージェントを同じComposeへ追加
-- 秘密情報を`config.yml`へ分離
-- 既存フォルダを上書きしない
+| Minecraft version | Image tag |
+| --- | --- |
+| `26.x` or `LATEST` | `java25` |
+| `1.20.5` and later 1.x releases | `java21` |
+| `1.18` through `1.20.4` | `java17` |
 
-## 必要な環境
+Older releases require an explicit Docker image tag in the configuration.
 
-- WSL2上のLinux
-- Docker DesktopのWSL Integration
-- Docker Compose v2
-- Bash
-- ZIPを直接取り込む場合のみ`unzip`
+Java memory accepts values such as `8`, `8G`, and `8192M`. A number without a unit is treated as GiB.
 
-確認：
+By default, servers are created in:
 
-```bash
-docker version
-docker compose version
+```text
+~/minecraftServer/<server-id>/
+├── compose.yaml
+├── .env
+├── server.env
+├── README.txt
+└── data/
+    └── world/
 ```
 
-## セットアップ
+The creation process shows its current step. Before starting a server it validates the generated Compose configuration with `docker compose config --quiet`.
+
+## Manage servers
 
-リポジトリを取得し、スクリプトへ実行権限を付けます。
+List managed servers:
 
 ```bash
-git clone <repository-url> mcserver-tool-kit
-cd mcserver-tool-kit
-chmod +x new-minecraft-server.sh
+mcserver-kit list
 ```
 
-公開用の設定例を、実設定へコピーします。
+Use the dashboard, or run a command directly:
 
 ```bash
-cp config.example.yml config.yml
-chmod 600 config.yml
+mcserver-kit server <server-id> start
+mcserver-kit server <server-id> stop
+mcserver-kit server <server-id> shutdown
+mcserver-kit server <server-id> restart
+mcserver-kit server <server-id> status
+mcserver-kit server <server-id> logs
+mcserver-kit server <server-id> logs --no-follow
+mcserver-kit server <server-id> down
+mcserver-kit server <server-id> properties
 ```
 
-`config.yml`はGit管理から除外されています。
+`stop` and `shutdown` stop the container without removing it. `down` removes the container and network. These commands do not delete the server's `data/` directory.
 
-## config.yml
+## Edit Minecraft settings
 
-```yaml
-owner:
-  minecraft_id: "c0tt0n_rain"
-
-minecraft:
-  # https://aka.ms/MinecraftEULA を確認し、同意する場合だけtrue
-  accept_eula: true
-
-paths:
-  server_root: "${HOME}/minecraftServer"
-
-defaults:
-  minecraft_version: "26.2"
-  java_memory: "8G"
-  timezone: "Asia/Tokyo"
-  max_players: 8
-  online_mode: true
-  enable_command_block: true
-  allow_flight: true
-  spawn_protection: 0
-  host_port: 25565
-
-access:
-  whitelist_enabled: true
-  whitelist_template: "default"
-  ops_enabled: true
-  ops_template: "owner"
-
-playit:
-  enabled: true
-  secret_key: "ここにPlayitのSECRET_KEY"
-  image: "ghcr.io/playit-cloud/playit-agent:0.17"
-
-docker:
-  java_image_tag: "auto"
-
-resource_pack:
-  enforce: true
-```
+Open **Server settings** from the dashboard, or run:
 
-### 秘密情報
+```bash
+mcserver-kit server <server-id> properties
+```
 
-`playit.secret_key`を含む`config.yml`は、GitHubへコミットしないでください。公開するのは空欄の`config.example.yml`だけです。
+The editor covers MOTD, difficulty, game mode, player limit, online mode, whitelist, operators, flight, command blocks, PvP, view and simulation distance, spawn protection, Nether and entity spawning, and resource packs.
 
-誤操作を防ぐため、次を確認できます。
+`server.env` is the source of truth for settings managed by the toolkit. Docker Compose passes these values to `itzg/minecraft-server`, which applies them to `server.properties` when the container starts.
 
-```bash
-git check-ignore -v config.yml
-git status --short
-```
+When an older server is opened for the first time, the editor asks before migrating it. The original Compose file is saved as `compose.yaml.mcserver-kit.bak`.
 
-## MCIDテンプレート
+## MCID templates
 
-ホワイトリストとOPは、同じ`mcid-templates`ディレクトリを参照します。
+Templates are plain text files stored in:
 
 ```text
-mcid-templates/
-├─ owner.txt
-├─ Group1.txt
-└─ Group2.txt
+~/.config/mcserver-compose-kit/mcid-templates/
 ```
 
-1行に1つMCIDを書きます。空行と`#`以降は無視されます。
+Write one Minecraft ID per line. Blank lines and text after `#` are ignored. `${OWNER}` expands to the Owner ID from the main configuration.
 
 ```text
-# config.ymlのオーナー
 ${OWNER}
-
-# 固定メンバー
 ExamplePlayer
 AnotherPlayer
 ```
 
-`owner.txt`をOP用に、`Group1.txt`をホワイトリスト用に使う、といった設定ができます。
-
-## 使用方法
+Manage templates from the dashboard or run:
 
 ```bash
-mcserver-kit create
+mcserver-kit templates
 ```
 
-入力する内容：
+## Windows dialogs
 
-1. サーバーID
-2. 表示名／MOTD
-3. Minecraftバージョン
-4. Javaメモリ
-5. 配布ワールドのルートフォルダまたはZIP
-6. ホワイトリストの有無とMCIDテンプレート
-7. OP自動付与の有無とMCIDテンプレート
-8. リソースパック配信情報
-9. Playitを使うか
+When enabled, the toolkit calls Windows PowerShell from WSL to open Explorer-based folder and ZIP selection dialogs. MOTD text can also be entered in a Windows dialog, avoiding common terminal IME editing problems.
 
-作成先は、既定で次の場所です。
+If the Windows dialog is unavailable or cancelled, input falls back to the terminal. Disable it in the global settings screen or set:
 
-```text
-~/minecraftServer/<server-id>
-```
-
-## 配布ワールドの指定
-
-指定するのは、直下に`level.dat`があるワールドのルートフォルダです。
-
-```text
-Picking Over It/
-├─ level.dat
-├─ dimensions/
-├─ datapacks/
-├─ data/
-└─ config/
-```
-
-サーバーの保存先になる`data`ディレクトリそのものを指定するわけではありません。上記フォルダ全体が、生成先の`data/world`へコピーされます。
-
-Windowsのダウンロードフォルダは、WSLから次のように指定できます。
-
-```text
-/mnt/c/Users/<Windowsユーザー名>/Downloads/<配布フォルダ>/<ワールド名>
-```
-
-## 入力書式
-
-### Minecraftバージョン
-
-ワールドのフォルダまたはZIPを選ぶと、`level.dat`に保存されたMinecraftバージョンを検出し、入力時のデフォルト値にします。Enterを押せば検出結果を採用できます。
-
-検出できなかった場合は、`config.yml`の`defaults.minecraft_version`を候補にします。配布ページで別のバージョンが指定されている場合は、そちらを手動入力してください。
-
-```text
-26.2
-1.21.2
-LATEST
+```yaml
+ui:
+  windows_dialogs: false
 ```
 
-`docker.java_image_tag: "auto"`の場合、現在は次のようにJavaイメージを選びます。
+## Configuration and secrets
 
-| Minecraft | Dockerイメージタグ |
-|---|---|
-| `26.x` / `LATEST` | `java25` |
-| `1.21` / `1.21.x` / `1.20.5`以降 | `java21` |
-| `1.18`～`1.20` / `1.18.x`～`1.20.4` | `java17` |
-
-それより古いバージョンは自動判定せず停止します。必要なJavaタグを`config.yml`へ明示してください。
-
-### Javaメモリ
+User configuration is stored at:
 
 ```text
-8       → 8G
-8G      → 8G
-8192M   → 8192M
+~/.config/mcserver-compose-kit/config.yml
 ```
 
-### 表示名／MOTD
-
-Minecraftのマルチプレイ一覧で、サーバーアドレスの下に表示される説明文です。ワールド名やフォルダ名には影響しません。
-
-### リソースパック
-
-サーバーから配信する場合、次が必要です。
-
-- HTTPSの直接ダウンロードURL
-- ZIPのSHA-1
-- 任意のResource Pack ID（UUID）
-
-MCPacksなどのMinecraft向け配信サービスを利用できます。
-
-## 生成物
-
-```text
-~/minecraftServer/<server-id>/
-├─ compose.yaml
-├─ .env
-├─ server.env
-├─ README.txt
-└─ data/
-   └─ world/
-```
+Use `mcserver-kit config` for common settings. The file can also be edited directly.
 
-- `compose.yaml`：Dockerの起動設定
-- `.env`：そのサーバー用設定とPlayit秘密鍵。権限`600`
-- `server.env`：TUIで管理するMinecraft設定の正本。権限`600`
-- `README.txt`：起動・停止手順
-- `data/`：ワールド、プレイヤー情報、進行状況
+The configuration may contain a Playit secret key. Do not commit it. Generated server `.env` and `server.env` files may also contain private values.
 
-## サーバー管理
+## Language
 
-管理対象サーバーと起動状態を一覧表示します。
+Set a persistent language:
 
 ```bash
-mcserver-kit list
-```
-
-サーバーIDを指定して、作業ディレクトリへ手動で移動せずに操作できます。
-
-```bash
-mcserver-kit server <server-id> start
-mcserver-kit server <server-id> stop
-mcserver-kit server <server-id> shutdown
-mcserver-kit server <server-id> restart
-mcserver-kit server <server-id> status
-mcserver-kit server <server-id> logs
-mcserver-kit server <server-id> logs --no-follow
-mcserver-kit server <server-id> down
+mcserver-kit lang --en
+mcserver-kit lang --ja
 ```
 
-`start`は`docker compose config --quiet`で構成を検証してから`up -d`を実行します。`stop`と`shutdown`はコンテナを保持したまま停止し、`down`はコンテナとネットワークを削除します。いずれも`data/`のワールドデータは削除しません。
-
-サーバーのMinecraft設定はTUIから一元管理できます。稼働中でも編集でき、保存後に今すぐ再作成・再起動して反映するか確認します。
+Override the language for one command:
 
 ```bash
-mcserver-kit server <server-id> properties
+mcserver-kit --lang ja --help
 ```
 
-対象はMOTD、難易度、ゲームモード、最大人数、オンラインモード、ホワイトリスト・OP、飛行、コマンドブロック、PvP、描画・シミュレーション距離、スポーン保護、ネザーやMob/NPC生成、リソースパックなどです。
+See [CONTRIBUTING.md](CONTRIBUTING.md#adding-a-language) to add or update a translation.
 
-設定の正本は各サーバーの`server.env`です。Composeがこれをitzg/minecraft-serverへ渡し、起動時に`data/server.properties`へ反映します。TUIは`.env`と`server.properties`の両方へ同じ値を書かないため、設定の同期ずれを避けられます。
+## Reset, update, and uninstall
 
-従来形式の生成済みサーバーは、初回にproperties画面を開いたときに移行するか確認します。同意すると元のComposeを`compose.yaml.mcserver-kit.bak`へ保存し、現在の`.env`、Compose環境変数、`server.properties`から`server.env`へ移行します。キャンセルした場合は変更しません。
-
-## 作成後
-
-作成中は、ワールドのコピー、設定生成、Compose検証などの現在の処理を段階表示します。
-
-最後に、Docker Composeでそのまま起動するか確認します。起動を選んだ場合は、次の処理まで自動で行います。
+Delete configuration and MCID templates while keeping installed program files and created servers:
 
 ```bash
-docker compose config --quiet
-docker compose up -d
-docker compose ps
+mcserver-kit reset
 ```
 
-初回起動ではDockerイメージの取得に時間がかかることがあります。開始前にその旨を表示し、Docker Composeの進捗をそのまま表示します。
+Update by running the installer again. Existing user configuration is kept.
 
-手動で起動する場合：
-
-構成確認：
+Remove the program but keep user configuration:
 
 ```bash
-cd ~/minecraftServer/<server-id>
-docker compose config --quiet
-```
-
-起動：
-
-```bash
-docker compose up -d
-docker compose logs -f minecraft
+mcserver-kit uninstall
 ```
 
-停止：
+Remove the program and user configuration:
 
 ```bash
-docker compose down
+mcserver-kit uninstall --purge
 ```
 
-## 注意事項
-
-- サーバーは自動起動しません。
-- 作成先が既に存在する場合は上書きせず停止します。
-- 同じホストポートを使うサーバーは同時起動できません。
-- 同じPlayitエージェント秘密鍵を使うサーバーも同時起動しないでください。
-- MODローダー必須の配布マップは、現在のVANILLA用テンプレートの対象外です。
-- `data/`を削除するとワールドと進行状況を失います。
-
-## GitHub公開前の確認
-
-```bash
-bash -n new-minecraft-server.sh
-bash tests/run-tests.sh
-git check-ignore -v config.yml
-git status --short
-```
+After uninstalling, open a new terminal. In the current Bash session, `hash -r` clears a cached command path if needed.
 
-`config.yml`や`.env`がステージ対象に含まれていないことを確認してください。
+## Limitations
 
-## テスト
+- Servers that use the same host port cannot run at the same time.
+- Do not run multiple Playit agents with the same secret key at the same time.
+- Mod-loader-specific maps are not currently configured by the vanilla template.
+- Deleting a server's `data/` directory deletes its world and progress.
 
-仕様テストは、Javaイメージの選択、`level.dat`からの保存バージョン検出、メモリとWindowsパスの正規化、入れ子になったワールドの検出、ZIPからのワールド取り込みを確認します。
+## Contributing
 
-```bash
-bash tests/run-tests.sh
-```
+Bug reports, documentation fixes, and translations are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
 
-ZIPのテストには`zip`と`unzip`が必要です。`zip`がないローカル環境ではZIPテストだけをスキップします。GitHub Actionsでは必要なコマンドを導入し、次を自動実行します。
+## License
 
-- Bash構文チェック
-- Python構文チェック
-- ShellCheck
-- 仕様テスト
+See [LICENSE](LICENSE).

From aa34fb6ac89c7fca8753ac8aeed8ae90a39e8083 Mon Sep 17 00:00:00 2001
From: cotore-game <102813037+cotore-game@users.noreply.github.com>
Date: Sun, 9 Aug 2026 04:54:01 +0900
Subject: [PATCH 2/3] chore: include contributor docs in distributions

---
 .github/workflows/release.yml | 2 ++
 install.sh                    | 6 ++++++
 tests/run-tests.sh            | 2 ++
 3 files changed, 10 insertions(+)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 37a49f8..2e2e806 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -46,6 +46,8 @@ jobs:
             config.example.yml \
             compose-example.yaml \
             README.md \
+            README-JA.md \
+            CONTRIBUTING.md \
             LICENSE \
             scripts \
             locales \
diff --git a/install.sh b/install.sh
index 0fd2cc8..4f7fc9c 100755
--- a/install.sh
+++ b/install.sh
@@ -193,6 +193,12 @@ main() {
   install -m 644 "${source_dir}/config.example.yml" "${INSTALL_DIR}/config.example.yml"
   install -m 644 "${source_dir}/compose-example.yaml" "${INSTALL_DIR}/compose-example.yaml"
   install -m 644 "${source_dir}/README.md" "${INSTALL_DIR}/README.md"
+  if [[ -f "${source_dir}/README-JA.md" ]]; then
+    install -m 644 "${source_dir}/README-JA.md" "${INSTALL_DIR}/README-JA.md"
+  fi
+  if [[ -f "${source_dir}/CONTRIBUTING.md" ]]; then
+    install -m 644 "${source_dir}/CONTRIBUTING.md" "${INSTALL_DIR}/CONTRIBUTING.md"
+  fi
   install -m 644 "${source_dir}/LICENSE" "${INSTALL_DIR}/LICENSE"
   mkdir -p "${INSTALL_DIR}/scripts"
   install -m 755 "${source_dir}/scripts/detect-world-version.py" "${INSTALL_DIR}/scripts/detect-world-version.py"
diff --git a/tests/run-tests.sh b/tests/run-tests.sh
index 53742cd..b053150 100755
--- a/tests/run-tests.sh
+++ b/tests/run-tests.sh
@@ -304,6 +304,8 @@ test_local_installation() {
   assert_equal 'present' "$([[ -x "${install_dir}/server-manager.sh" ]] && printf present)" 'the installer includes the server manager'
   assert_equal 'present' "$([[ -x "${install_dir}/server-properties-tui.sh" ]] && printf present)" 'the installer includes the properties TUI'
   assert_equal 'present' "$([[ -x "${install_dir}/home-tui.sh" ]] && printf present)" 'the installer includes the home dashboard'
+  assert_equal 'present' "$([[ -f "${install_dir}/README-JA.md" ]] && printf present)" 'the installer includes the Japanese README'
+  assert_equal 'present' "$([[ -f "${install_dir}/CONTRIBUTING.md" ]] && printf present)" 'the installer includes the contribution guide'
   assert_equal 'present' "$([[ -x "${install_dir}/scripts/server-config.py" ]] && printf present)" 'the installer includes the unified server settings editor'
   assert_equal 'en' "$(cat "${config_dir}/language")" 'the installer defaults to English'
   assert_equal '1' "$(grep -Fxc '# >>> mcserver-kit PATH >>>' "$shell_rc")" 'the installer registers one managed PATH block'

From 34ac2d1b5ace7873da07aa62ae214acda8c4a8d5 Mon Sep 17 00:00:00 2001
From: cotore-game <102813037+cotore-game@users.noreply.github.com>
Date: Mon, 10 Aug 2026 23:14:57 +0900
Subject: [PATCH 3/3] ci: test pull requests targeting develop

---
 .github/workflows/shell-tests.yml | 1 +
 CONTRIBUTING.md                   | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/shell-tests.yml b/.github/workflows/shell-tests.yml
index ae90859..2a2f1e4 100644
--- a/.github/workflows/shell-tests.yml
+++ b/.github/workflows/shell-tests.yml
@@ -8,6 +8,7 @@ on:
   pull_request:
     branches:
       - main
+      - develop
 
 permissions:
   contents: read
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3d81808..96b23fc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -147,7 +147,7 @@ Before opening a pull request:
 - Use a clear title, preferably with a Conventional Commits prefix such as `feat:`, `fix:`, `docs:`, or `test:`.
 - Summarize what changed and how it was tested.
 
-Pull requests targeting `main` are checked by GitHub Actions. The required `test` job must pass before merging.
+Pull requests targeting `develop` or `main` are checked by GitHub Actions. The required `test` job must pass before merging into `main`.
 
 ## Releases