pqcli-ja 1.1.0__tar.gz

pqcli_ja-1.1.0/.claude/settings.local.json

@@ -0,0 +1,53 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3 -c \"import babel; print\\(babel.__version__\\)\")",
+      "Bash(grep -rn 'caption = \\\\|Task\\(\\\\s*$\\\\|Task\\(\"' pqcli/mechanic.py)",
+      "Bash(python3 -)",
+      "Bash(python3 -c 'import ast,sys,pathlib *)",
+      "Bash(uv sync *)",
+      "Bash(uv run *)",
+      "Bash(PQCLI_LANG=en uv run python /tmp/smoke.py)",
+      "Bash(PQCLI_LANG=ja uv run python /tmp/smoke.py)",
+      "Bash(env -u PQCLI_LANG -u LANG -u LC_ALL -u LANGUAGE uv run python -c ' *)",
+      "Bash(PQCLI_LANG=zz_ZZ uv run python -c ' *)",
+      "Bash(LANG=ja_JP.UTF-8 env -u PQCLI_LANG uv run python -c ' *)",
+      "Bash(rm -rf /tmp/pqhome)",
+      "Bash(mkdir -p /tmp/pqhome/pqcli)",
+      "Bash(PQCLI_LANG=en uv run python /tmp/mkchar.py /tmp/pqhome/pqcli/save.dat)",
+      "Bash(python3 -c ' *)",
+      "Bash(git stash *)",
+      "Bash(grep -v '^|  *|$')",
+      "Bash(rm -rf pqhome2)",
+      "Bash(mkdir -p pqhome2/pqcli)",
+      "Bash(cp pqhome/pqcli/save.dat pqhome2/pqcli/)",
+      "Bash(XDG_CONFIG_HOME=/tmp/pqhome2 PQCLI_LANG=ja timeout 8 uv run python -m pqcli --basic)",
+      "Bash(grep -rn --include='*.py' -E '\\(^|[^a-zA-Z0-9_]\\)_\\([^a-zA-Z0-9_\\(]|$\\)' pqcli/)",
+      "Bash(XDG_CONFIG_HOME=/tmp/pqhome2 PQCLI_LANG=ja timeout 12 uv run python -m pqcli --basic --no-save)",
+      "Bash(XDG_CONFIG_HOME=/tmp/pqhome2 PQCLI_LANG=en timeout 12 uv run python -m pqcli --basic --no-save)",
+      "Bash(PQCLI_LANG=ja uv run python -m pqcli --help)",
+      "Bash(PQCLI_LANG=en uv run python -m pqcli --help)",
+      "Bash(XDG_CONFIG_HOME=/tmp/pqfresh PQCLI_LANG=ja timeout 10 uv run python -m pqcli --basic)",
+      "Bash(uv build *)",
+      "Bash(unzip -l /tmp/wheeltest/*.whl)",
+      "Bash(uv venv *)",
+      "Bash(VIRTUAL_ENV=/tmp/cleanenv uv pip install --quiet /tmp/wheeltest/*.whl)",
+      "Bash(XDG_CONFIG_HOME=/tmp/pqhome2 PQCLI_LANG=ja timeout 10 /tmp/cleanenv/bin/pqcli --basic --no-save)",
+      "Bash(XDG_CONFIG_HOME=/tmp/pqhome2 PQCLI_LANG=en timeout 10 /tmp/cleanenv/bin/pqcli --basic --no-save)",
+      "Bash(/tmp/cleanenv/bin/python -c \"import babel\")",
+      "Bash(brew upgrade *)",
+      "Bash(echo \"  \\(uv run pqcli: exit=$? — no saves in default location is expected\\)\")",
+      "Bash(git log *)",
+      "Bash(git rm *)",
+      "Bash(unzip -l /tmp/wt2/*.whl)",
+      "Bash(PQCLI_LANG=ja uv run python -c \"from pqcli.lingo import act_name; print\\(' ja ->', act_name\\(2\\)\\)\")",
+      "Bash(PQCLI_LANG=en uv run python -c \"from pqcli.lingo import act_name; print\\(' en ->', act_name\\(2\\)\\)\")",
+      "Bash(git checkout *)",
+      "Bash(git add *)",
+      "Bash(git restore *)",
+      "Bash(git commit *)",
+      "Bash(git ls-remote *)",
+      "Bash(curl *)"
+    ]
+  }
+}

pqcli_ja-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  checks:
+    name: lint, catalogs and golden output
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync
+      # isort, black, the compiled catalogs and the golden dump, in one pass.
+      - run: uv run pre-commit run --all-files --show-diff-on-failure
+      # .mo files are not in git, so prove the build hook still puts them in
+      # the distribution -- otherwise a release would silently ship no
+      # translations at all.
+      - run: rm -f pqcli/locale/*/LC_MESSAGES/*.mo && uv build
+      - name: the built wheel carries the compiled catalogs
+        run: |
+          python -c "
+          import glob, zipfile, sys
+          wheel = sorted(glob.glob('dist/*.whl'))[-1]
+          names = zipfile.ZipFile(wheel).namelist()
+          found = [n for n in names if n.endswith('.mo')]
+          print('catalogs in wheel:', found)
+          sys.exit(0 if found else 1)
+          "
+
+  supported-pythons:
+    name: python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --python ${{ matrix.python }}
+      # The classifiers claim these versions, so prove the game runs on them.
+      - run: uv run --python ${{ matrix.python }} python tools/golden.py --check
+      - run: uv run --python ${{ matrix.python }} pqcli --help

pqcli_ja-1.1.0/.gitignore

@@ -0,0 +1,9 @@
+dist/
+build/
+__pycache__
+
+# Vim undo files
+*.un~
+
+# Compiled catalogs are build output; hatch_build.py generates them.
+*.mo

pqcli_ja-1.1.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+
+- repo: https://github.com/pycqa/isort
+  rev: 5.13.2
+  hooks:
+  - id: isort
+    additional_dependencies: [toml]
+- repo: https://github.com/psf/black
+  rev: 24.4.2
+  hooks:
+  - id: black
+- repo: local
+  hooks:
+  - id: compile-catalogs
+    name: compile gettext catalogs
+    description: the game loads the .mo files, so a stale one silently ships the old text
+    entry: uv run pybabel compile -d pqcli/locale -D pqcli
+    language: system
+    files: ^pqcli/locale/.*\.(po|pot)$
+    pass_filenames: false
+  - id: golden-output
+    name: golden output unchanged
+    description: catches unintended changes to what the game displays in English
+    entry: uv run python tools/golden.py --check
+    language: system
+    files: ^(pqcli/.*\.py|tools/golden.*)$
+    pass_filenames: false

pqcli_ja-1.1.0/CONTRIBUTING.ja.md

@@ -0,0 +1,104 @@
+# 開発・翻訳への参加
+
+*[English](CONTRIBUTING.md) | 日本語*
+
+貢献の種類によって必要な準備が大きく違うので、目的に合う方を読んでください。
+
+## 翻訳する
+
+必要なのは `.po` エディタだけです。Python もビルドツールも要りません。
+[Poedit](https://poedit.net/) は無料で Windows・macOS・Linux で動きます。
+普通のテキストエディタでも構いません。
+
+1. `pqcli/locale/<言語>/LC_MESSAGES/pqcli.po` を開きます。日本語なら
+   `pqcli/locale/ja/LC_MESSAGES/pqcli.po` です。
+2. 訳したい `msgstr` を埋めます。
+3. その `.po` だけを含む pull request を送ります。
+
+これで全部です。**コンパイルは不要**です。`.mo` はビルド生成物で git 管理外、
+リリースをビルドする時に生成されます。
+
+途中まででも歓迎します。未訳の項目は英語にフォールバックするので、10件だけ
+訳して止めてもゲームは問題なく遊べます。現時点で日本語は 982 件中 207 件です。
+
+### 何を訳すことになるか
+
+100件ほどが UI のラベルと文の骨格で、残りはゲームデータ（モンスター名・呪文名・
+種族名・クラス名・アイテム名・装備名）です。本番はこちらで、Progress Quest は
+RPG のパロディなので中身は言葉遊びです。`Cone of Annoyance`、`Slime Finger`、
+`Battle-Ghoul` といった調子で、笑いを他言語で保つのは翻訳というより創作です。
+直訳より「面白さが伝わる名前」を優先してください。同じ名前は出現箇所すべてで
+統一してください。
+
+文の骨格は `Executing {monster}` のような形です。`{...}` は残したまま、
+日本語として自然な位置に動かして構いません。語順を入れ替えられるようにするために
+文字列連結ではなくプレースホルダにしてあります。
+
+### `pqcli/config.py` は編集しないでください
+
+このファイルの英語文字列は表示用ではなく**識別子**です。コードもセーブファイルも
+msgid も、すべてこの文字列を共通の名前として参照しています。ここを書き換えると
+全カタログとの対応が壊れます。翻訳は必ず `msgstr` の追加で行ってください。
+
+### 新しい言語を追加する
+
+```console
+uv run pybabel init -i pqcli/locale/pqcli.pot -d pqcli/locale -l de -D pqcli
+```
+
+言語によっては、カタログだけでは表現できない文法（冠詞・複数形・助数詞・形容詞の
+位置）が必要になります。それは `pqcli/lingo/<言語>.py` に書き、
+`pqcli/lingo/__init__.py` の `_BACKENDS` に登録します。**自分の言語で実際に
+異なる規則だけ**を定義すれば十分で、それ以外は英語にフォールバックします。
+関数2つだけのバックエンドでも動きます。
+
+## コードを変更する
+
+```console
+git clone https://github.com/hannibal414/pq-cli.git
+cd pq-cli
+uv sync
+uv run pre-commit install
+
+# 英語以外で起動するために一度だけ実行:
+uv run pybabel compile -d pqcli/locale -D pqcli
+
+uv run pqcli
+```
+
+テストスイートはありません。代わりに `tools/golden.py` があります。シードを
+固定した5本のシミュレーションを走らせて表示される文字列をすべてダンプし、
+`golden-output` フックが `tools/golden_expected.txt` と突き合わせます。
+
+差分が出ても即バグとは限りません。それは**あなたの変更が表示に与えた影響の
+一覧**です。読んだうえで意図どおりなら記録し直してください。
+
+```console
+uv run python tools/golden.py --update
+```
+
+翻訳作業でこのダンプが変わることはないので、カタログを編集している間フックは
+静かなままです。
+
+### ソースに文字列を追加する
+
+`pqcli.i18n` の `_()` で囲み、文字列を連結せずに**1文まるごとを1つの msgid**に
+して名前付きプレースホルダを使ってください。
+
+```python
+# 良い例 — msgid が1つで、翻訳者が語順を変えられる
+_("Selling {item}").format(item=name)
+
+# 悪い例 — 英語の語順がコードに焼き付く
+_("Selling ") + name
+```
+
+セーブファイルに保存されるテキストは、描画済みの文字列ではなく `pqcli.text` の
+フレーズにしてください。言語切替のあとに再描画できるようにするためです。
+`_` は gettext の関数なので、これを import しているモジュールで
+使い捨て変数名（`for _ in range(...)`）として使わないでください。
+
+## 本家について
+
+このリポジトリは [rr-/pq-cli](https://github.com/rr-/pq-cli) のフォークです。
+日本語化に関係しない変更は、本家に送った方が良い場合があります。

pqcli_ja-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# Contributing
+
+*English | [日本語](CONTRIBUTING.ja.md)*
+
+Two kinds of contribution need very different setups, so pick the one you are
+here for.
+
+## Translating
+
+You need a `.po` editor and nothing else — no Python, no build tools.
+[Poedit](https://poedit.net/) is free and runs on Windows, macOS and Linux;
+any text editor works too.
+
+1. Open `pqcli/locale/<language>/LC_MESSAGES/pqcli.po` — for Japanese that is
+   `pqcli/locale/ja/LC_MESSAGES/pqcli.po`.
+2. Fill in the `msgstr` lines you want to translate.
+3. Open a pull request containing only that `.po` file.
+
+That is the whole process. You do **not** need to compile anything: `.mo`
+files are build output, are not in git, and are generated when a release is
+built.
+
+Partial work is welcome. Anything left untranslated falls back to English, so
+translating ten entries and stopping leaves the game perfectly playable. As of
+writing, Japanese covers 207 of 982 messages.
+
+### What the strings are
+
+Roughly a hundred are interface text and sentence frames. The rest are game
+data — monster, spell, race, class, item and equipment names — and those are
+where the work is, because Progress Quest is a parody: `Cone of Annoyance`,
+`Slime Finger`, `Battle-Ghoul`. Keeping a joke funny in another language is
+rewriting, not lookup. Prefer a name that lands over one that is literal, and
+keep a given name identical everywhere it appears.
+
+A sentence frame looks like `Executing {monster}`. Keep the `{...}` markers,
+but move them wherever your language needs them — that is exactly why they are
+markers instead of glued-together words.
+
+### Do not edit `pqcli/config.py`
+
+The English strings in that file are identities, not display text: the code,
+the save files and the msgids all agree on them. Changing one there breaks the
+link to every catalog. Translate by adding a `msgstr`, always.
+
+### Starting a new language
+
+```console
+uv run pybabel init -i pqcli/locale/pqcli.pot -d pqcli/locale -l de -D pqcli
+```
+
+Some languages also need grammar the catalog cannot express — articles,
+plurals, counters, adjective placement. Those live in `pqcli/lingo/<lang>.py`,
+registered in `_BACKENDS` in `pqcli/lingo/__init__.py`. Define only the rules
+your language actually differs on; everything else falls back to English, so a
+two-function backend is a perfectly good start.
+
+## Changing the code
+
+```console
+git clone https://github.com/hannibal414/pq-cli.git
+cd pq-cli
+uv sync
+uv run pre-commit install
+
+# Once, so the game can run in a language other than English:
+uv run pybabel compile -d pqcli/locale -D pqcli
+
+uv run pqcli
+```
+
+There is no test suite. `tools/golden.py` stands in for one: it runs five
+seeded simulations and dumps every string they display, and the
+`golden-output` pre-commit hook diffs that against `tools/golden_expected.txt`.
+
+A diff there is not automatically a bug — it is the list of display changes
+your commit makes. Read it. If it is what you intended, record it:
+
+```console
+uv run python tools/golden.py --update
+```
+
+Translation work never changes that dump, so the hook stays quiet while you
+are editing catalogs.
+
+### Adding a string to the source
+
+Wrap it with `_()` from `pqcli.i18n`, and keep a whole sentence in one msgid
+with named placeholders rather than concatenating pieces:
+
+```python
+# good -- one msgid, the translator can reorder it
+_("Selling {item}").format(item=name)
+
+# bad -- English word order is now baked into the code
+_("Selling ") + name
+```
+
+Text that gets stored in a save file should be a phrase from `pqcli.text`
+rather than a rendered string, so it can be re-rendered after a language
+change. `_` is the gettext function: never use it as a throwaway variable in a
+module that imports it.
+
+## Upstream
+
+This is a fork of [rr-/pq-cli](https://github.com/rr-/pq-cli). Changes that are
+not about localization are often better sent there.

pqcli_ja-1.1.0/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY . .
+
+RUN pip install --no-cache-dir .
+
+CMD ["pqcli", "--basic"]

pqcli_ja-1.1.0/LICENSE.md

@@ -0,0 +1,24 @@
+The MIT License (MIT)
+=====================
+
+Copyright © `2018` `Marcin Kurczewski`
+
+Copyright © `2026` `hannibal414` (Japanese localization and related changes)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pqcli_ja-1.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.5
+Name: pqcli-ja
+Version: 1.1.0
+Summary: Progress Quest: the CLI edition, with Japanese localization
+Project-URL: Repository, https://github.com/hannibal414/pq-cli.git
+Project-URL: Upstream project, https://github.com/rr-/pq-cli
+Author-email: Laura Kurczewska <dash@wind.garden>
+Maintainer-email: hannibal414 <207813470+hannibal414@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Japanese
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Role-Playing
+Classifier: Topic :: Games/Entertainment :: Simulation
+Requires-Python: <4.0,>=3.10
+Requires-Dist: wcwidth<1.0.0,>=0.2.5
+Requires-Dist: xdg-base-dirs<7.0.0,>=6.0.0
+Provides-Extra: windows
+Requires-Dist: windows-curses<3.0.0,>=2.3.0; extra == 'windows'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img alt="Progress Quest" src="http://progressquest.com/pq.png">
+</p>
+
+*English | [日本語](README.ja.md)*
+
+Relive the great adventure… this time in the terminal realm!
+
+- Progress Quest site:  http://progressquest.com/
+- Online version:       http://progressquest.com/play/
+- Original version:     https://bitbucket.org/grumdrig/pq
+
+This is a fork of [rr-/pq-cli](https://github.com/rr-/pq-cli) by Laura
+Kurczewska, adding Japanese localization and the machinery that makes the whole
+game — not just its prose — translatable. The original MIT licence and
+copyright are kept in `LICENSE.md`.
+
+## Features
+
+- Faithful port of the game logic
+- Saves (with backups) to `$XDG_CONFIG_HOME/pqcli/save.dat`
+- Terminal interface that comes in 2 flavors:
+    - Rich and colorful (`--curses`, default)
+    - Minimal, suitable for raw grind (`--basic`)
+- Ideal to run on your server
+
+## How it looks like
+
+Curses interface:
+
+![Screenshot](screen-curses-logo.png)
+![Screenshot](screen-curses.png)
+
+Basic interface:
+
+![Screenshot](screen-basic.png)
+
+## How to install
+
+If you have Python 3.10 or newer, just run `pip install --user pqcli-ja` and
+you're good to go! Then type `pqcli` to run the game.
+
+This is the Japanese edition, published to PyPI as `pqcli-ja`. The original
+English-only game is a separate package named `pqcli`; both install a command
+called `pqcli`, so install only one of them in a given environment.
+
+In case if you want to use the git version, the process is just a bit more complex:
+
+```console
+$ git clone https://github.com/hannibal414/pq-cli.git
+$ cd pq-cli
+$ pip install --user .
+```
+
+## Docker / Docker Compose
+
+The repository includes a `Dockerfile` and `docker-compose.yml` that run the
+game with `--basic` and keep save data in a persistent named volume.
+
+There is no registry pipeline required for this setup: build locally, then run
+with Compose.
+
+```console
+# Build image locally from the Dockerfile
+docker compose build
+
+# First run (interactive): create your character in the shared save volume
+docker compose run --rm pqcli-init
+
+# Later runs on a server (detached, default save slot 1):
+docker compose up -d pqcli
+
+# List existing saves in the same volume:
+docker compose run --rm pqcli-init pqcli --basic --list-saves
+
+# Change detached slot if needed (example: slot 2):
+PQCLI_SAVE_SLOT=2 docker compose up -d pqcli
+
+# Follow logs / stop detached container:
+docker compose logs -f pqcli
+docker compose stop pqcli
+```
+
+On first run, if no save data exists in the mounted volume, `pqcli` will
+automatically launch an interactive character-creation bootstrap in CLI mode
+before starting the normal interface.
+
+For server usage, run first-time setup without a forced slot (`pqcli-init`),
+then run the long-lived detached service (`pqcli`) that loads slot `1` by
+default.
+
+## Languages
+
+The game ships with English (the source language) and Japanese. Pick one with
+the `PQCLI_LANG` environment variable:
+
+```console
+PQCLI_LANG=ja pqcli
+PQCLI_LANG=en pqcli
+```
+
+When `PQCLI_LANG` is unset, the usual gettext environment is consulted
+(`LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG`). If no catalog matches, the game
+falls back to English.
+
+Everything the game shows is translatable, including the game-data tables in
+`pqcli/config.py` — monster, spell, race, class, item and equipment names. Those
+English strings are *identities*, not display text: they are what the code, the
+save files and the msgids all agree on, and the display layer resolves them
+through the catalog at render time. Translating one therefore means adding a
+msgstr, never editing `pqcli/config.py`.
+
+Text is stored as a phrase (`pqcli/text.py`) — a msgid plus its parameters —
+rather than as a finished sentence, so a language change reaches text that was
+generated earlier, and translators can reorder the parts of a sentence in the
+catalog. Text written by versions before phrases existed keeps the language it
+was generated in, since the msgid it came from cannot be recovered.
+
+English grammar (articles, plurals, the adjective stack) lives in
+`pqcli/lingo/en.py`. `pqcli/lingo/__init__.py` picks a backend from the active
+catalog and falls back to English, so adding `pqcli/lingo/<lang>.py` is how a
+language gets its own rules.
+
+### Working on translations
+
+Translation tooling needs the dev dependencies (`uv sync`).
+
+```console
+# 1. Re-extract msgids from the source into the .pot template
+uv run pybabel extract -F babel.cfg -k N_ -k Term -k phrase \
+    -o pqcli/locale/pqcli.pot \
+    --project=pqcli --version=1.1.0 \
+    --copyright-holder="pq-cli contributors" \
+    --msgid-bugs-address="https://github.com/hannibal414/pq-cli/issues" .
+
+# 2. Merge the template into the existing catalogs
+uv run pybabel update -i pqcli/locale/pqcli.pot -d pqcli/locale -D pqcli
+
+# 3. Edit pqcli/locale/<lang>/LC_MESSAGES/pqcli.po, then compile to .mo
+uv run pybabel compile -d pqcli/locale -D pqcli --statistics
+```
+
+To start a new language (`de` shown here):
+
+```console
+uv run pybabel init -i pqcli/locale/pqcli.pot -d pqcli/locale -l de -D pqcli
+```
+
+The compiled `.mo` files are what the game loads at runtime, so re-run step 3
+after editing any `.po`. The `compile-catalogs` pre-commit hook does this for
+you whenever a `.po` changes.
+
+`.mo` files are build output and are not in git: `hatch_build.py` compiles them
+into the wheel and sdist. A translation pull request therefore carries only the
+`.po` you edited — no binary, and nothing to go stale in review.
+
+`-k N_ -k Term -k phrase` is what pulls the game data in: `N_()` marks a string
+in `pqcli/config.py` for extraction without translating it there, `Term()` names
+one of those strings at the point of use, and `phrase()` builds a deferred
+sentence. When adding translatable strings to the source, wrap
+them with `_()` from `pqcli.i18n` and prefer a single `.format()` template over
+concatenation, so translators can reorder the parts:
+
+```python
+# good -- one msgid, placeholders can move
+_("Selling {item}").format(item=indefinite(item.name, item.quantity))
+
+# bad -- word order is baked into the code
+_("Selling ") + indefinite(item.name, item.quantity)
+```
+
+Beware that `_` is the gettext function: never use it as a throwaway variable
+name (`for _ in range(...)`) in a module that imports it.
+
+### Checking the display did not change
+
+There are no tests, so `tools/golden.py` stands in for one: it runs five seeded
+simulations and dumps every string they display. `--check` diffs that against
+`tools/golden_expected.txt` and fails on any difference; `--update` re-records
+it once you have read the diff and want it. The `golden-output` pre-commit hook
+runs the check for you. Translating does not change the English dump, so the
+hook stays quiet during translation work and speaks up when code does.
+
+## Contributing
+
+Translating needs only a `.po` editor — see [CONTRIBUTING.md](CONTRIBUTING.md).
+To work on the code:
+
+```sh
+# Clone the repository:
+git clone https://github.com/hannibal414/pq-cli.git
+cd pq-cli
+
+# Install dependencies into a local venv:
+uv sync
+
+# Install pre-commit hooks:
+uv run pre-commit install
+
+# Compile the catalogs once, so the game can run in a language other than
+# English (the hooks keep them current from here on):
+uv run pybabel compile -d pqcli/locale -D pqcli
+
+# Run commands inside the venv:
+uv run pqcli
+```
+
+This project uses [uv](https://docs.astral.sh/uv/) for packaging.
+Install instructions are available at [uv installation](https://docs.astral.sh/uv/getting-started/installation/).
+
+## Troubleshooting
+
+### `_curses.error: init_pair() returned ERR`
+
+If running on Linux and you get the error `_curses.error: init_pair() returned ERR`,
+try making sure that your `$TERM` variable is set to a value which supports
+256 colors, such as via the following:
+
+    TERM=xterm-256color pqcli
+