storelingo 0.0.0-stage → 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+## 0.5.1 — 2026-11-15
+
+- `stores.appstore.appId` is needed only for `pull` and `push`. `translate` and `check` work with `"appstore": {}` before the app exists in App Store Connect, and `init` accepts an empty Apple ID. `pull` / `push` without it stop with a clear `E_CONFIG` before any network call (found while localizing a real app).
+
+## 0.5.0 — 2026-11-15
+
+- First release on npm: `npx storelingo` works without building from source.
+- Releases are published from GitHub Actions with npm trusted publishing and provenance (`docs/releasing.md`).
+- `npm run build` starts from a clean `dist/`, so files of removed modules never end up in the package.
+- The package includes `CHANGELOG.md`.
+- Google Play: concurrent requests share one token refresh, a failed refresh can be retried, and an invalid `expires_in` falls back to one hour (thanks @yonash24, #13).
+
+## 0.4.1 — 2026-11-14
+
+- GitHub Action: the commit step treats config paths literally (`GIT_LITERAL_PATHSPECS`) and commits only storelingo output even if an earlier workflow step staged other files (reported by the Codex review on #11).
+
+## 0.4.0 — 2026-11-14
+
+- GitHub Action (`uses: Alisher23/storelingo@v0.4.0`): runs `translate` and/or `check` in CI. Optional `commit` of the translated files: only storelingo output is committed, only on `push`, `workflow_dispatch` or `schedule` runs on a branch, and never after a failed or cancelled step. Setup guide in `docs/github-action.md`.
+- Retry-After delays from servers are capped at 60 s (thanks @yonash24, #10).
+- App Store: promotional text without an editable version is sent only for languages that already exist on the live version; other languages are shown as skipped.
+- The final "some changes were skipped" note is store-specific.
+
+## 0.3.0 — unreleased
+
+- **Breaking:** `stores.appstore.appId` must be the numeric Apple ID (for example `1234567890`), not the bundle ID.
+- App Store `pull` / `push` (`--store appstore`) through the App Store Connect API with a team API key (`STORELINGO_ASC_ISSUER_ID`, `STORELINGO_ASC_KEY_ID`, `STORELINGO_ASC_PRIVATE_KEY`); setup guide in `docs/app-store-setup.md`.
+- `pull` and `push` without `--store` now run every configured store (Google Play, then the App Store), each with its own diff and confirmation.
+- App Store `push` is not atomic: it applies one language at a time, sends only the changed fields, and on a failure reports "already applied: ...; failed (may be partly applied): ...; not attempted: ..."; re-running only sends what still differs.
+- `pull` and `push` load the credentials of every selected store before touching any of them, so a missing App Store key no longer shows up after Google Play was already pushed.
+- Release notes are not sent for the first version of an app (Apple shows them only for updates); skipped lines name their real reason; several editable versions or app infos prefer `PREPARE_FOR_SUBMISSION` or fail with a clear `E_STORE`; paginated App Store Connect lists are capped and never silently truncated.
+- Fields are routed to the resource that can take them: `name`, `subtitle`, `privacy_url` to the editable app info; `description`, `keywords`, `release_notes`, `marketing_url`, `support_url` to the editable version; `promotional_text` to the editable version or else the live one. Changes with no such resource are shown as skipped and never sent.
+- Requests that create a localization are never retried; a lost response is reported as "status is unknown".
+- New `stores.appstore.platform` option (`IOS` by default).
+- Error codes `E_AUTH_ASC` and `E_NO_EDITABLE_VERSION` are now used.
+- `STORELINGO_ASC_PRIVATE_KEY` is masked in logs and errors.
+
+## 0.2.0 — unreleased
+
+- `pull`: download the current Google Play listings into the fastlane folders. Never commits and never touches the lock file; keeps different local files unless `--force`.
+- `push`: runs `check`, shows the diff with the live Google Play listing and uploads after confirmation (`--dry-run`, `--yes`; outside a terminal it needs one of them). One Play edit per push, committed with `ERROR_IF_IN_REVIEW` so changes already in review are never cancelled.
+- `push` counts as interactive only when both input and output are a terminal: with output redirected or piped (e.g. `storelingo push > log.txt`, `storelingo push | tee log.txt`) it needs `--yes` or `--dry-run`.
+- The `push` diff shows the part of a long value where it actually changes, with character counts.
+- Google Play service account authentication via `STORELINGO_PLAY_SERVICE_ACCOUNT`; setup guide in `docs/google-play-setup.md`.
+- New error codes `E_IN_REVIEW` and `E_STORE`.
+- Hardening: the OpenAI-compatible translator no longer follows redirects.
+- Hardening: `init` refuses symbolic links at `storelingo.config.json` and `.gitignore`.
+- `--store appstore` is rejected until v0.3.
+
+## 0.1.0 — unreleased
+
+- `init`: create `storelingo.config.json` and fastlane folders.
+- `translate`: AI localization with store limits, keyword rules, lock file and manual-edit protection.
+- `check`: offline validation of limits, missing fields and keyword format.
+- Translators: Claude API and any OpenAI-compatible endpoint.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alisher23
+
+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.

package/README.md

@@ -1,3 +1,332 @@
-# Temporary Holding Version
+# storelingo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AI localization for your Google Play and App Store listings. Works with fastlane metadata — no fastlane required.
+
+[![npm](https://img.shields.io/npm/v/storelingo)](https://www.npmjs.com/package/storelingo) [![CI](https://github.com/Alisher23/storelingo/actions/workflows/ci.yml/badge.svg)](https://github.com/Alisher23/storelingo/actions/workflows/ci.yml)
+
+> Status: early. Covered by automated tests on Windows, macOS and Linux, but not yet run against many real store accounts. Start with `pull` and `push --dry-run`, and [open an issue](https://github.com/Alisher23/storelingo/issues) if anything looks off.
+
+[Русская версия](README.ru.md)
+
+## Why
+
+- **Store limits are respected.** Every field has its character limit (counted in Unicode code points). If a translation is too long, storelingo asks the model to shorten it, up to 2 times. Text is never truncated mechanically; if it still does not fit, the file is not written and the run reports an error.
+- **Keywords are localized for search, not translated literally.** App Store keywords are chosen for what people in the target market search for, then normalized (comma-separated, no spaces, no duplicates, no words already in the name or subtitle).
+- **Your manual edits are protected.** If you edit a translated file by hand, storelingo notices and skips it (use `--force` to overwrite).
+- **Incremental.** A lock file records what was translated, so only changed source fields are sent to the model.
+- **Bring your own model.** Claude (default) or any OpenAI-compatible endpoint, including a local Ollama.
+
+## Quick start
+
+```bash
+npx storelingo init
+export ANTHROPIC_API_KEY=sk-ant-...
+npx storelingo translate
+git diff
+npx storelingo check
+```
+
+`init` asks a few questions and creates `storelingo.config.json` plus the fastlane folders. Put your source-language texts into those folders, then run `translate`. Review the result with `git diff`, and commit `storelingo.lock.json` together with the translations.
+
+Requires Node.js >= 22.13. To pin the version for your team, add storelingo to the project with `npm install --save-dev storelingo`. To run it in CI, see the [GitHub Action](https://github.com/Alisher23/storelingo/blob/main/docs/github-action.md).
+
+## Folder layout
+
+storelingo reads and writes the standard fastlane trees (paths can be changed in `paths`):
+
+```
+fastlane/metadata/android/          # Google Play (fastlane supply)
+  en-US/
+    title.txt
+    short_description.txt
+    full_description.txt
+    video.txt                       # not translated
+    changelogs/<versionCode>.txt
+  ru-RU/ ...
+
+fastlane/metadata/                  # App Store (fastlane deliver)
+  en-US/
+    name.txt
+    subtitle.txt
+    description.txt
+    keywords.txt
+    promotional_text.txt
+    release_notes.txt
+    marketing_url.txt               # urls are not translated
+    support_url.txt
+    privacy_url.txt
+  ru/ ...
+```
+
+The `android`, `default`, `review_information` and `trade_representative_contact_information` folders inside `fastlane/metadata` are not treated as App Store locales. Files are written as UTF-8 without BOM with `\n` line endings (line breaks in the model's reply are normalized before writing); the source's trailing newline is preserved.
+
+The metadata paths and `storelingo.lock.json` are resolved against the current directory, so run storelingo from the project root. `paths.play` and `paths.appstore` must stay inside the project: absolute paths and `..` escapes are rejected with a config error (exit code 2). storelingo also refuses to follow symbolic links in the metadata folders and for the lock file (exit code 2), because the config and these files can come from someone else's repository.
+
+For Google Play, the newest changelog (highest version code) of the source locale is the one that gets translated.
+
+## Config reference
+
+`storelingo.config.json` in the project root:
+
+```json
+{
+  "sourceLocale": "en-US",
+  "targetLocales": ["ru", "de", "tr", "ar", "uz"],
+  "stores": {
+    "play": { "packageName": "com.example.app" },
+    "appstore": { "appId": "1234567890" }
+  },
+  "translator": {
+    "provider": "anthropic",
+    "model": "claude-opus-5-5",
+    "effort": "medium",
+    "concurrency": 4
+  },
+  "context": "Prayer times and Quran app for Muslims in Central Asia.",
+  "glossary": {
+    "doNotTranslate": ["Quran Widgets"],
+    "terms": { "ru": { "prayer": "намаз" } }
+  },
+  "paths": {}
+}
+```
+
+| Key | Required | Description |
+|---|---|---|
+| `sourceLocale` | yes | storelingo locale code of your source texts, e.g. `en-US`. |
+| `targetLocales` | yes | Non-empty list of storelingo locale codes to translate into, without duplicates. |
+| `stores.play.packageName` | one store required | Enables Google Play. |
+| `stores.appstore` | one store required | Enables the App Store. `{}` is enough for `translate` and `check`, even before the app exists in App Store Connect. |
+| `stores.appstore.appId` | for `pull` / `push` | The numeric Apple ID of the app (App Store Connect → App Information). |
+| `stores.appstore.platform` | no (default `IOS`) | `IOS`, `MAC_OS`, `TV_OS` or `VISION_OS`: the platform whose version storelingo works with. |
+| `translator.provider` | yes | `anthropic` or `openai-compatible`. |
+| `translator.model` | `anthropic`: no (default `claude-opus-5-5`); `openai-compatible`: yes | Model name. |
+| `translator.effort` | no, `anthropic` only | `low`, `medium` (default), `high`, `xhigh` or `max`. |
+| `translator.baseUrl` | `openai-compatible` only | API base URL. Must be `https://` unless it points to `localhost`, `127.0.0.1` or `[::1]`. |
+| `translator.concurrency` | no (default `4`) | Locales translated in parallel, 1 to 16. |
+| `context` | no | Short description of your app; added to every prompt. |
+| `glossary.doNotTranslate` | no | Terms kept exactly as written (brand names). |
+| `glossary.terms` | no | Preferred translations per target locale: `{ "<locale>": { "<source term>": "<translation>" } }`. |
+| `paths.play` | no | Play metadata root (default `fastlane/metadata/android`). A relative path inside the project. |
+| `paths.appstore` | no | App Store metadata root (default `fastlane/metadata`). A relative path inside the project. |
+
+Unknown keys are rejected, so a typo such as `glossary.doNotTranslte` is reported instead of silently ignored.
+
+### Translators and API keys
+
+Keys come only from environment variables. They are never written to the config, the lock file or the logs.
+
+| Variable | Used for |
+|---|---|
+| `ANTHROPIC_API_KEY` | Claude (`provider: "anthropic"`). |
+| `OPENAI_API_KEY` | OpenAI-compatible, **only** when the `baseUrl` host is `api.openai.com`. |
+| `STORELINGO_TRANSLATOR_API_KEY` | Any other OpenAI-compatible host (OpenRouter, Gemini endpoint, ...). |
+| `STORELINGO_TRANSLATOR_API_HOST` | The host the OpenAI-compatible provider may talk to. Required for every non-local host other than `api.openai.com`, even without a key; the only host that receives `STORELINGO_TRANSLATOR_API_KEY`. |
+| `STORELINGO_PLAY_SERVICE_ACCOUNT` | Google Play `pull` / `push`: the path to the service account JSON key, or the JSON itself. See [Google Play](#google-play). |
+| `STORELINGO_ASC_ISSUER_ID` | App Store `pull` / `push`: the Issuer ID of the App Store Connect team API key. See [App Store](#app-store). |
+| `STORELINGO_ASC_KEY_ID` | App Store `pull` / `push`: the Key ID of that key. |
+| `STORELINGO_ASC_PRIVATE_KEY` | App Store `pull` / `push`: the path to the `.p8` private key, or its contents (literal `\n` sequences are accepted as line breaks). |
+
+Rules for `openai-compatible`:
+
+- `api.openai.com`: uses `OPENAI_API_KEY`; no other variable is needed.
+- Any other non-local host: `STORELINGO_TRANSLATOR_API_HOST` must equal the hostname of `baseUrl`, **even if no key is set**; otherwise storelingo stops with a config error (exit code 2) and sends nothing. `STORELINGO_TRANSLATOR_API_KEY`, if set, is sent only to that host.
+- Local servers (`localhost`, `127.0.0.1`, `[::1]`, e.g. Ollama): no variable is needed. A `STORELINGO_TRANSLATOR_API_KEY` is sent to a local server only if `STORELINGO_TRANSLATOR_API_HOST` names it; if the key is set and the host does not match, storelingo stops with a config error.
+- `baseUrl` must be `https://`; plain `http://` is allowed only for `localhost`, `127.0.0.1` and `[::1]`. Other schemes (`file:`, `data:`, ...) are rejected.
+
+Why: a `storelingo.config.json` can come from someone else's repository. Without these rules, a malicious config could set `baseUrl` to its own server and collect whatever API key is in your environment, or your unreleased listing texts. Requests and keys can only travel to the host you explicitly allowed.
+
+OpenRouter:
+
+```json
+{
+  "translator": {
+    "provider": "openai-compatible",
+    "baseUrl": "https://openrouter.ai/api/v1",
+    "model": "anthropic/claude-sonnet-5-5"
+  }
+}
+```
+
+```bash
+export STORELINGO_TRANSLATOR_API_KEY=sk-or-...
+export STORELINGO_TRANSLATOR_API_HOST=openrouter.ai
+npx storelingo translate
+```
+
+Local Ollama (no key):
+
+```json
+{
+  "translator": {
+    "provider": "openai-compatible",
+    "baseUrl": "http://localhost:11434/v1",
+    "model": "qwen3:32b"
+  }
+}
+```
+
+## Commands
+
+```
+storelingo [--config <path>] [--verbose] [--no-color] <command>
+```
+
+| Command | What it does |
+|---|---|
+| `init [--force]` | Interactive setup: creates `storelingo.config.json` and the fastlane folders. `--force` overwrites an existing config. |
+| `translate [--locale <code...>] [--force]` | Translates changed fields into the target locales. `--locale` limits the run to some of `targetLocales`. `--force` re-translates everything, including files you edited manually. |
+| `check` | Offline validation: character limits, missing required fields, keyword format. Makes no API calls. |
+| `pull [--store <store>] [--force]` | Downloads the current store listings into the fastlane folders. Local files that differ from the store are kept unless you pass `--force`. Never changes the store. |
+| `push [--store <store>] [--dry-run] [--yes]` | Runs `check`, shows the diff with the live listing and uploads after confirmation. `--dry-run` only shows the diff. Outside a terminal it needs `--yes` or `--dry-run`. |
+
+`--store` accepts `play` or `appstore`. Without it, `pull` and `push` run every configured store, Google Play first and then the App Store, each with its own diff and confirmation. With `--store`, the store must be configured (`stores.play` or `stores.appstore`), otherwise the command stops with a config error.
+
+Global flags: `--config <path>` (default `storelingo.config.json`), `--verbose` (debug output), `--no-color`, `--version`, `--help`.
+
+Exit codes:
+
+| Code | Meaning |
+|---|---|
+| `0` | Success. |
+| `1` | `check` found errors, some translations failed, `push` was blocked by `check` errors or by a listing problem, or a runtime error (for example the source locale is not supported by a configured store, a file could not be read or written, Google Play denied access (`E_AUTH_PLAY`), changes are already in review (`E_IN_REVIEW`), App Store Connect denied access (`E_AUTH_ASC`), there is no editable App Store version for any of the changes (`E_NO_EDITABLE_VERSION`) or a store API failed (`E_STORE`)). |
+| `2` | Bad usage or config: invalid flag, `--locale` outside `targetLocales`, missing or invalid config, `paths` outside the project, a symbolic link in the metadata folders or at the lock file, a corrupt lock file, missing API key or a `baseUrl` host not allowed by `STORELINGO_TRANSLATOR_API_HOST`, a missing or invalid `STORELINGO_PLAY_SERVICE_ACCOUNT`, missing or invalid `STORELINGO_ASC_ISSUER_ID`, `STORELINGO_ASC_KEY_ID` or `STORELINGO_ASC_PRIVATE_KEY`, a Google Play or App Store 404 ("app not found or not accessible"), a `--store` value other than `play` or `appstore`, a `--store` for a store that is not configured, or `push` without `--yes` outside a terminal. |
+
+## Google Play
+
+`pull` and `push` use the Google Play Android Publisher API with a service account. Follow the [Google Play setup guide](https://github.com/Alisher23/storelingo/blob/main/docs/google-play-setup.md) once (Google Cloud project, service account key, access in Play Console), then:
+
+```bash
+export STORELINGO_PLAY_SERVICE_ACCOUNT=/path/to/play-service-account.json
+npx storelingo pull
+npx storelingo translate
+npx storelingo check
+npx storelingo push --dry-run
+npx storelingo push
+```
+
+How it behaves:
+
+- `push` validates the config, `--store` and the terminal rule (outside a terminal it needs `--yes` or `--dry-run`) before any network request. It then runs `check` and stops on errors (exit code 1).
+- One Play edit per push: all changed listings are uploaded and committed together. The commit uses `changesInReviewBehavior=ERROR_IF_IN_REVIEW`, so changes that are already in review are never cancelled; if there are any, `push` stops with `E_IN_REVIEW` (exit code 1) and changes nothing.
+- If the final commit request gets no clear answer (a network error, a timeout, or an HTTP 429/5xx response), storelingo reports "commit status is unknown". Check Play Console, or run `push --dry-run` to see whether the listing already matches your files.
+- Google reviews listing changes before they go live.
+- Changelogs (release notes) are not uploaded yet; use `fastlane supply` for them.
+- Languages that exist only in Google Play are never deleted. A new language needs `title`, `short_description` and `full_description`.
+- `pull` never commits anything and never touches `storelingo.lock.json`. Pulled translations have no lock entry, so `translate` treats them as manual edits and skips them; re-translate them with `translate --force` (optionally with `--locale`).
+- The service account key is read only from `STORELINGO_PLAY_SERVICE_ACCOUNT` (a path or the JSON itself). Tokens are requested from Google's fixed token endpoint; the `token_uri` inside the key file is ignored.
+
+## App Store
+
+`pull` and `push` use the App Store Connect API with a team API key. Follow the [App Store setup guide](https://github.com/Alisher23/storelingo/blob/main/docs/app-store-setup.md) once (API key with the App Manager role, Apple ID of the app), then:
+
+```bash
+export STORELINGO_ASC_ISSUER_ID=...
+export STORELINGO_ASC_KEY_ID=...
+export STORELINGO_ASC_PRIVATE_KEY=/path/to/AuthKey_XXXXXXXXXX.p8
+npx storelingo pull --store appstore
+npx storelingo translate
+npx storelingo check
+npx storelingo push --store appstore --dry-run
+npx storelingo push --store appstore
+```
+
+How it behaves:
+
+- **Not atomic.** The API has no transaction. `push` computes the whole diff first and then applies it one language at a time. If a request fails midway, the languages already applied stay applied; the error lists three groups ("already applied: ...; failed (may be partly applied): ...; not attempted: ..."; "none" when a group is empty; the failed language may be partly applied, e.g. app info updated but the version not) and tells you to re-run `storelingo push`. This message appears for every failure of an App Store update, including one on the first language. Only changed fields are sent. Re-running is safe either way: it reads the store again and sends only what still differs.
+- **Fields go to the resource that can take them.** `name`, `subtitle` and `privacy_url` go to the editable app info. `description`, `keywords`, `release_notes`, `marketing_url` and `support_url` go to the editable version. `promotional_text` goes to the editable version, or to the live version if there is no editable one. A version is editable in the states `PREPARE_FOR_SUBMISSION`, `DEVELOPER_REJECTED`, `REJECTED` or `METADATA_REJECTED` (app info: the first three); live means `READY_FOR_DISTRIBUTION`. `pull` reads the editable resources if they exist, otherwise the live ones.
+- **Skipped lines.** A change that has no resource to go to is never sent. It is shown in the diff as `<locale>/<field>: skipped (<reason>)`, where the reason is "no editable version in App Store Connect", "no editable app info in App Store Connect" or "Apple shows release notes only for updates" (release notes are not sent for the first version of an app), and `push` prints a note at the start. If every change is skipped, `push` prints the skipped lines and stops with `E_NO_EDITABLE_VERSION` (exit code 1, also with `--dry-run`): create a new version in App Store Connect and push again. Without a new version only the promotional text can change, and on the live version it takes effect right away; the rest goes live with the version you prepare.
+- **New languages** need `name`, `description` and `keywords` locally and both an editable app info and an editable version.
+- A request that creates a localization is never retried. If it gets no clear answer, storelingo reports `E_STORE` "status is unknown"; run `push --dry-run` to see whether it was created.
+- storelingo never submits anything for review, never deletes languages and never touches prices, builds, screenshots or categories.
+- The key is read only from the `STORELINGO_ASC_*` variables and never appears in logs or error messages. Keep the `.p8` out of git (`init` adds `*.p8` to `.gitignore`).
+
+## GitHub Action
+
+Run storelingo in CI with `uses: Alisher23/storelingo@v0.5.1` (pin a release tag or a commit SHA). It can translate on push and commit the result, or only run the offline `check` on pull requests with no secrets. See the [GitHub Action guide](https://github.com/Alisher23/storelingo/blob/main/docs/github-action.md) for workflows, inputs and security notes.
+
+## How translation works
+
+1. For every store and target locale, storelingo decides per field: skip if the source is empty or missing; translate if the target file is missing or empty (whitespace only); skip if you edited the translated file by hand; skip if the source has not changed since the last run; otherwise translate.
+2. One request per store and locale carries all selected fields, together with your `context`, `doNotTranslate` list, the locale's `terms` and each field's character limit. The prompt asks for localized, idiomatic text and preserves line breaks and bullet lists.
+3. The JSON reply is validated; an invalid reply is retried once.
+4. A field over its limit is sent back for shortening, at most 2 times. If it still exceeds the limit, nothing is written for that field and it is reported as an error.
+5. App Store `keywords` are normalized in code after the reply: trimmed, comma-separated without spaces, deduplicated, words from the name and subtitle removed (the newly translated ones, or the locale's current `name.txt` / `subtitle.txt` when those are not re-translated in this run).
+6. Translations are written to the fastlane folders. `storelingo.lock.json` stores hashes of each source and written output. A target file whose hash no longer matches the lock was edited by you and is skipped, unless you pass `--force`. The lock is written atomically after each field; commit it to git.
+7. The run continues past a single failure. At the end storelingo prints a summary (translated, unchanged, edited manually, unsupported, failed, tokens) and exits with code 1 if anything failed. Fields that succeeded are already saved.
+
+## Locale codes
+
+storelingo uses its own locale codes in `sourceLocale` and `targetLocales` (for example `ru`, `de`, `es-419`, `zh-Hans`) and maps them to each store's code: `ru` is `ru-RU` on Google Play and `ru` on the App Store, `es-419` is `es-MX` on the App Store, `zh-Hans` is `zh-CN` on Google Play. The fastlane folders use the store codes.
+
+Some languages exist on only one store. For example `ky` (Kyrgyz), `kk` (Kazakh) and `uz` (Uzbek) are Google Play only. If a store does not support a target locale, that locale is skipped for that store with a warning and counted as "unsupported" in the summary; the other store is still translated. The source locale must be supported by every configured store.
+
+## Cost
+
+The default model is `claude-opus-5-5` with `effort: "medium"`. For cheaper runs set `"model": "claude-sonnet-5-5"` or `"claude-haiku-5-5"` in the `translator` block. Only changed fields are sent, so repeat runs are small. Input and output token totals are printed after each run, so you can estimate the cost with your provider's price list.
+
+## Supported languages
+
+Generated from `src/locales/table.ts`. "—" means the store does not support that language.
+
+| Code | Language | Google Play | App Store |
+|---|---|---|---|
+| `ar` | Arabic | `ar` | `ar-SA` |
+| `az` | Azerbaijani | `az-AZ` | — |
+| `ca` | Catalan | `ca` | `ca` |
+| `cs` | Czech | `cs-CZ` | `cs` |
+| `da` | Danish | `da-DK` | `da` |
+| `de` | German | `de-DE` | `de-DE` |
+| `el` | Greek | `el-GR` | `el` |
+| `en-AU` | English (Australia) | `en-AU` | `en-AU` |
+| `en-CA` | English (Canada) | `en-CA` | `en-CA` |
+| `en-GB` | English (United Kingdom) | `en-GB` | `en-GB` |
+| `en-US` | English (United States) | `en-US` | `en-US` |
+| `es-ES` | Spanish (Spain) | `es-ES` | `es-ES` |
+| `es-419` | Spanish (Latin America) | `es-419` | `es-MX` |
+| `fa` | Persian | `fa` | — |
+| `fi` | Finnish | `fi-FI` | `fi` |
+| `fr-CA` | French (Canada) | `fr-CA` | `fr-CA` |
+| `fr-FR` | French (France) | `fr-FR` | `fr-FR` |
+| `he` | Hebrew | `iw-IL` | `he` |
+| `hi` | Hindi | `hi-IN` | `hi` |
+| `hr` | Croatian | `hr` | `hr` |
+| `hu` | Hungarian | `hu-HU` | `hu` |
+| `id` | Indonesian | `id` | `id` |
+| `it` | Italian | `it-IT` | `it` |
+| `ja` | Japanese | `ja-JP` | `ja` |
+| `kk` | Kazakh | `kk` | — |
+| `ko` | Korean | `ko-KR` | `ko` |
+| `ky` | Kyrgyz | `ky-KG` | — |
+| `ms` | Malay | `ms` | `ms` |
+| `nl` | Dutch | `nl-NL` | `nl-NL` |
+| `no` | Norwegian | `no-NO` | `no` |
+| `pl` | Polish | `pl-PL` | `pl` |
+| `pt-BR` | Portuguese (Brazil) | `pt-BR` | `pt-BR` |
+| `pt-PT` | Portuguese (Portugal) | `pt-PT` | `pt-PT` |
+| `ro` | Romanian | `ro` | `ro` |
+| `ru` | Russian | `ru-RU` | `ru` |
+| `sk` | Slovak | `sk` | `sk` |
+| `sv` | Swedish | `sv-SE` | `sv` |
+| `th` | Thai | `th` | `th` |
+| `tr` | Turkish | `tr-TR` | `tr` |
+| `uk` | Ukrainian | `uk` | `uk` |
+| `uz` | Uzbek | `uz` | — |
+| `vi` | Vietnamese | `vi` | `vi` |
+| `zh-Hans` | Chinese (Simplified) | `zh-CN` | `zh-Hans` |
+| `zh-Hant` | Chinese (Traditional) | `zh-TW` | `zh-Hant` |
+
+## Roadmap
+
+- v0.2 (done): Google Play `pull` / `push`
+- v0.3 (done): App Store `pull` / `push`
+- v0.4 (done): GitHub Action
+- Later: screenshots, RuStore, Huawei AppGallery
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/Alisher23/storelingo/blob/main/CONTRIBUTING.md). To add a language or fix a character limit you usually only need to edit one data file. Repository: https://github.com/Alisher23/storelingo
+
+## License
+
+MIT