storelingo 0.0.0-stage → 0.5.0

package/README.ru.md

@@ -0,0 +1,331 @@
+# storelingo
+
+ИИ-локализация карточек Google Play и App Store. Работает с метаданными fastlane — сам fastlane не нужен.
+
+[![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)
+
+> Статус: ранняя версия. Покрыт автотестами на Windows, macOS и Linux, но ещё мало проверялся на реальных аккаунтах магазинов. Начните с `pull` и `push --dry-run`, а если что-то не так — [откройте issue](https://github.com/Alisher23/storelingo/issues).
+
+[English version](README.md)
+
+## Зачем
+
+- **Лимиты магазинов соблюдаются.** У каждого поля есть лимит символов (считаются кодовые точки Unicode). Если перевод длиннее, storelingo просит модель сократить его, до 2 раз. Текст никогда не обрезается механически; если он всё равно не помещается, файл не пишется, а в отчёте будет ошибка.
+- **Ключевые слова локализуются под поиск, а не переводятся дословно.** Ключевые слова App Store подбираются так, как ищут люди на целевом рынке, затем нормализуются (через запятую, без пробелов, без дублей, без слов из названия и подзаголовка).
+- **Ручные правки защищены.** Если вы отредактировали переведённый файл руками, storelingo это заметит и пропустит его (перезаписать можно через `--force`).
+- **Инкрементально.** Lock-файл помнит, что уже переведено, поэтому в модель уходят только изменившиеся поля.
+- **Своя модель.** Claude (по умолчанию) или любой OpenAI-совместимый endpoint, включая локальный Ollama.
+
+## Быстрый старт
+
+```bash
+npx storelingo init
+export ANTHROPIC_API_KEY=sk-ant-...
+npx storelingo translate
+git diff
+npx storelingo check
+```
+
+`init` задаёт несколько вопросов и создаёт `storelingo.config.json` и папки fastlane. Положите исходные тексты в эти папки и запустите `translate`. Проверьте результат через `git diff` и закоммитьте `storelingo.lock.json` вместе с переводами.
+
+Требуется Node.js >= 22.13. Чтобы зафиксировать версию для команды, добавьте storelingo в проект: `npm install --save-dev storelingo`. Для запуска в CI есть [GitHub Action](https://github.com/Alisher23/storelingo/blob/main/docs/github-action.ru.md).
+
+## Структура папок
+
+storelingo читает и пишет стандартные деревья fastlane (пути меняются через `paths`):
+
+```
+fastlane/metadata/android/          # Google Play (fastlane supply)
+  en-US/
+    title.txt
+    short_description.txt
+    full_description.txt
+    video.txt                       # не переводится
+    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               # ссылки не переводятся
+    support_url.txt
+    privacy_url.txt
+  ru/ ...
+```
+
+Папки `android`, `default`, `review_information` и `trade_representative_contact_information` внутри `fastlane/metadata` не считаются локалями App Store. Файлы пишутся в UTF-8 без BOM с переводами строк `\n` (переводы строк в ответе модели нормализуются до записи); завершающий перевод строки берётся из исходника.
+
+Пути к метаданным и `storelingo.lock.json` считаются от текущей папки, поэтому запускайте storelingo из корня проекта. `paths.play` и `paths.appstore` обязаны оставаться внутри проекта: абсолютные пути и выход через `..` отклоняются с ошибкой конфигурации (код выхода 2). storelingo также не следует по символическим ссылкам в папках метаданных и для lock-файла (код выхода 2), потому что конфиг и эти файлы могут прийти из чужого репозитория.
+
+Для Google Play переводится самый свежий changelog (с наибольшим номером версии) исходной локали.
+
+## Конфигурация
+
+`storelingo.config.json` в корне проекта:
+
+```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": {}
+}
+```
+
+| Ключ | Обязателен | Описание |
+|---|---|---|
+| `sourceLocale` | да | Код локали storelingo для исходных текстов, например `en-US`. |
+| `targetLocales` | да | Непустой список кодов локалей storelingo, на которые переводить, без повторов. |
+| `stores.play.packageName` | нужен хотя бы один магазин | Включает Google Play. |
+| `stores.appstore.appId` | нужен хотя бы один магазин | Включает App Store. Числовой Apple ID приложения. |
+| `stores.appstore.platform` | нет (по умолчанию `IOS`) | `IOS`, `MAC_OS`, `TV_OS` или `VISION_OS`: платформа, с версией которой работает storelingo. |
+| `translator.provider` | да | `anthropic` или `openai-compatible`. |
+| `translator.model` | `anthropic`: нет (по умолчанию `claude-opus-5-5`); `openai-compatible`: да | Название модели. |
+| `translator.effort` | нет, только `anthropic` | `low`, `medium` (по умолчанию), `high`, `xhigh` или `max`. |
+| `translator.baseUrl` | только `openai-compatible` | Базовый URL API. Должен быть `https://`, кроме `localhost`, `127.0.0.1` и `[::1]`. |
+| `translator.concurrency` | нет (по умолчанию `4`) | Сколько локалей переводить параллельно, от 1 до 16. |
+| `context` | нет | Короткое описание приложения; добавляется в каждый запрос. |
+| `glossary.doNotTranslate` | нет | Термины, которые остаются без изменений (названия брендов). |
+| `glossary.terms` | нет | Предпочитаемые переводы по целевым локалям: `{ "<локаль>": { "<исходный термин>": "<перевод>" } }`. |
+| `paths.play` | нет | Корень метаданных Play (по умолчанию `fastlane/metadata/android`). Относительный путь внутри проекта. |
+| `paths.appstore` | нет | Корень метаданных App Store (по умолчанию `fastlane/metadata`). Относительный путь внутри проекта. |
+
+Неизвестные ключи отклоняются, поэтому опечатка вроде `glossary.doNotTranslte` будет показана как ошибка, а не молча проигнорирована.
+
+### Переводчики и API-ключи
+
+Ключи берутся только из переменных окружения. Они никогда не попадают в конфиг, lock-файл и логи.
+
+| Переменная | Для чего |
+|---|---|
+| `ANTHROPIC_API_KEY` | Claude (`provider: "anthropic"`). |
+| `OPENAI_API_KEY` | OpenAI-совместимый провайдер, **только** если хост в `baseUrl` — `api.openai.com`. |
+| `STORELINGO_TRANSLATOR_API_KEY` | Любой другой OpenAI-совместимый хост (OpenRouter, endpoint Gemini и т.д.). |
+| `STORELINGO_TRANSLATOR_API_HOST` | Хост, к которому разрешено обращаться OpenAI-совместимому провайдеру. Обязателен для любого нелокального хоста, кроме `api.openai.com`, даже без ключа; единственный хост, который получает `STORELINGO_TRANSLATOR_API_KEY`. |
+| `STORELINGO_PLAY_SERVICE_ACCOUNT` | `pull` / `push` для Google Play: путь к JSON-ключу сервисного аккаунта или сам JSON. См. [Google Play](#google-play). |
+| `STORELINGO_ASC_ISSUER_ID` | `pull` / `push` для App Store: Issuer ID командного API-ключа App Store Connect. См. [App Store](#app-store). |
+| `STORELINGO_ASC_KEY_ID` | `pull` / `push` для App Store: Key ID этого ключа. |
+| `STORELINGO_ASC_PRIVATE_KEY` | `pull` / `push` для App Store: путь к закрытому ключу `.p8` или его содержимое (последовательности `\n` буквально принимаются как переводы строк). |
+
+Правила для `openai-compatible`:
+
+- `api.openai.com`: используется `OPENAI_API_KEY`; другие переменные не нужны.
+- Любой другой нелокальный хост: `STORELINGO_TRANSLATOR_API_HOST` обязан совпадать с именем хоста из `baseUrl`, **даже если ключ не задан**; иначе storelingo остановится с ошибкой конфигурации (код выхода 2) и ничего не отправит. `STORELINGO_TRANSLATOR_API_KEY`, если задан, отправляется только на этот хост.
+- Локальные серверы (`localhost`, `127.0.0.1`, `[::1]`, например Ollama): переменные не нужны. `STORELINGO_TRANSLATOR_API_KEY` отправляется на локальный сервер, только если `STORELINGO_TRANSLATOR_API_HOST` указывает на него; если ключ задан, а хост не совпадает, storelingo остановится с ошибкой конфигурации.
+- `baseUrl` обязан быть `https://`; обычный `http://` разрешён только для `localhost`, `127.0.0.1` и `[::1]`. Другие схемы (`file:`, `data:` и т.п.) отклоняются.
+
+Зачем это нужно: `storelingo.config.json` может прийти из чужого репозитория. Без таких правил вредоносный конфиг мог бы указать `baseUrl` на свой сервер и собрать любой API-ключ из вашего окружения или ещё не опубликованные тексты листинга. Запросы и ключи уходят только на тот хост, который вы явно разрешили.
+
+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
+```
+
+Локальный Ollama (без ключа):
+
+```json
+{
+  "translator": {
+    "provider": "openai-compatible",
+    "baseUrl": "http://localhost:11434/v1",
+    "model": "qwen3:32b"
+  }
+}
+```
+
+## Команды
+
+```
+storelingo [--config <path>] [--verbose] [--no-color] <command>
+```
+
+| Команда | Что делает |
+|---|---|
+| `init [--force]` | Интерактивная настройка: создаёт `storelingo.config.json` и папки fastlane. `--force` перезаписывает существующий конфиг. |
+| `translate [--locale <code...>] [--force]` | Переводит изменившиеся поля на целевые локали. `--locale` ограничивает запуск частью `targetLocales`. `--force` переводит всё заново, включая файлы, которые вы правили руками. |
+| `check` | Офлайн-проверка: лимиты символов, отсутствующие обязательные поля, формат ключевых слов. API не вызывает. |
+| `pull [--store <store>] [--force]` | Скачивает текущие тексты из магазина в папки fastlane. Локальные файлы, отличающиеся от магазина, остаются нетронутыми, если не указан `--force`. Магазин не меняет. |
+| `push [--store <store>] [--dry-run] [--yes]` | Запускает `check`, показывает diff с живой карточкой и после подтверждения загружает. `--dry-run` только показывает diff. Вне терминала нужен `--yes` или `--dry-run`. |
+
+`--store` принимает `play` или `appstore`. Без него `pull` и `push` обрабатывают все настроенные магазины: сначала Google Play, затем App Store, у каждого свой diff и своё подтверждение. С `--store` магазин должен быть настроен (`stores.play` или `stores.appstore`), иначе команда останавливается с ошибкой конфигурации.
+
+Глобальные флаги: `--config <path>` (по умолчанию `storelingo.config.json`), `--verbose` (отладочный вывод), `--no-color`, `--version`, `--help`.
+
+Коды выхода:
+
+| Код | Значение |
+|---|---|
+| `0` | Успех. |
+| `1` | `check` нашёл ошибки, часть переводов не удалась, `push` заблокирован ошибками `check` или проблемой карточки, либо произошла ошибка во время работы (например, исходная локаль не поддерживается одним из магазинов, файл не удалось прочитать или записать, Google Play отказал в доступе (`E_AUTH_PLAY`), изменения уже на проверке (`E_IN_REVIEW`), App Store Connect отказал в доступе (`E_AUTH_ASC`), для изменений нет редактируемой версии App Store (`E_NO_EDITABLE_VERSION`) или API магазина вернул ошибку (`E_STORE`)). |
+| `2` | Неверное использование или конфиг: неверный флаг, `--locale` вне `targetLocales`, нет или некорректный конфиг, `paths` за пределами проекта, символическая ссылка в папках метаданных или на месте lock-файла, повреждённый lock-файл, нет API-ключа или хост `baseUrl` не разрешён через `STORELINGO_TRANSLATOR_API_HOST`, нет или некорректен `STORELINGO_PLAY_SERVICE_ACCOUNT`, нет или некорректны `STORELINGO_ASC_ISSUER_ID`, `STORELINGO_ASC_KEY_ID` или `STORELINGO_ASC_PRIVATE_KEY`, ответ 404 Google Play или App Store («app not found or not accessible»), значение `--store`, отличное от `play` и `appstore`, `--store` для ненастроенного магазина, либо `push` без `--yes` вне терминала. |
+
+## Google Play
+
+`pull` и `push` работают через Google Play Android Publisher API от имени сервисного аккаунта. Один раз выполните [руководство по настройке Google Play](https://github.com/Alisher23/storelingo/blob/main/docs/google-play-setup.ru.md) (проект Google Cloud, ключ сервисного аккаунта, доступ в Play Console), затем:
+
+```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
+```
+
+Как это работает:
+
+- `push` проверяет конфиг, `--store` и правило про терминал (вне терминала нужен `--yes` или `--dry-run`) до любых сетевых запросов. Затем запускает `check` и останавливается при ошибках (код выхода 1).
+- Одна правка (edit) Play на один `push`: все изменённые карточки загружаются и фиксируются вместе. Фиксация идёт с `changesInReviewBehavior=ERROR_IF_IN_REVIEW`, поэтому изменения, уже находящиеся на проверке, никогда не отменяются; если они есть, `push` останавливается с `E_IN_REVIEW` (код выхода 1) и ничего не меняет.
+- Если последний запрос фиксации не получил внятного ответа (сетевая ошибка, тайм-аут или ответ HTTP 429/5xx), storelingo сообщает «commit status is unknown». Проверьте Play Console или запустите `push --dry-run`, чтобы увидеть, совпадает ли карточка с вашими файлами.
+- Google проверяет изменения карточки перед публикацией.
+- Список изменений (release notes) пока не загружается; используйте для него `fastlane supply`.
+- Языки, которые есть только в Google Play, никогда не удаляются. Для нового языка нужны `title`, `short_description` и `full_description`.
+- `pull` ничего не фиксирует в магазине и не трогает `storelingo.lock.json`. У скачанных переводов нет записи в lock-файле, поэтому `translate` считает их ручными правками и пропускает; переведите их заново через `translate --force` (можно с `--locale`).
+- Ключ сервисного аккаунта читается только из `STORELINGO_PLAY_SERVICE_ACCOUNT` (путь или сам JSON). Токены запрашиваются на фиксированном адресе Google; `token_uri` из файла ключа игнорируется.
+
+## App Store
+
+`pull` и `push` работают через API App Store Connect с командным API-ключом. Один раз выполните [руководство по настройке App Store](https://github.com/Alisher23/storelingo/blob/main/docs/app-store-setup.ru.md) (API-ключ с ролью App Manager, Apple ID приложения), затем:
+
+```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
+```
+
+Как это работает:
+
+- **Не атомарно.** У API нет транзакций. `push` сначала считает весь diff, затем применяет его по одному языку. Если запрос падает посреди работы, уже применённые языки остаются применёнными; ошибка перечисляет три группы («already applied: ...; failed (may be partly applied): ...; not attempted: ...»; «none», если группа пуста; язык со сбоем может быть применён частично, например app info обновлён, а версия нет) и предлагает повторить `storelingo push`. Это сообщение появляется при любом сбое обновления App Store, в том числе на первом языке. Отправляются только изменённые поля. Повторный запуск безопасен в любом случае: он заново читает магазин и отправляет только то, что ещё отличается.
+- **Поля идут в тот ресурс, который может их принять.** `name`, `subtitle` и `privacy_url` идут в редактируемый app info. `description`, `keywords`, `release_notes`, `marketing_url` и `support_url` идут в редактируемую версию. `promotional_text` идёт в редактируемую версию, а если её нет, в живую. Версия редактируема в состояниях `PREPARE_FOR_SUBMISSION`, `DEVELOPER_REJECTED`, `REJECTED` или `METADATA_REJECTED` (app info: первые три); живая означает `READY_FOR_DISTRIBUTION`. `pull` читает редактируемые ресурсы, если они есть, иначе живые.
+- **Пропущенные строки.** Изменение, которому некуда попасть, не отправляется никогда. В diff оно показано как `<locale>/<field>: skipped (<причина>)`, где причина: «no editable version in App Store Connect», «no editable app info in App Store Connect» или «Apple shows release notes only for updates» (для первой версии приложения release notes не отправляются), а в начале `push` печатает примечание. Если пропущены все изменения, `push` печатает пропущенные строки и останавливается с `E_NO_EDITABLE_VERSION` (код выхода 1, в том числе с `--dry-run`): создайте новую версию в App Store Connect и повторите. Без новой версии можно изменить только промо-текст, и на живой версии он вступает в силу сразу; остальное выходит вместе с версией, которую вы готовите.
+- **Новым языкам** локально нужны `name`, `description` и `keywords`, а также и редактируемый app info, и редактируемая версия.
+- Запрос, создающий локализацию, никогда не повторяется. Если он не получил внятного ответа, storelingo сообщает `E_STORE` «status is unknown»; запустите `push --dry-run`, чтобы увидеть, создана ли она.
+- storelingo никогда не отправляет ничего на ревью, не удаляет языки и не трогает цены, билды, скриншоты и категории.
+- Ключ читается только из переменных `STORELINGO_ASC_*` и никогда не попадает в логи и сообщения об ошибках. Не добавляйте `.p8` в git (`init` дописывает `*.p8` в `.gitignore`).
+
+## GitHub Action
+
+Запускайте storelingo в CI через `uses: Alisher23/storelingo@v0.4.1` (закрепляйте релизный тег или SHA коммита). Он может переводить при push и коммитить результат либо только запускать офлайн-проверку `check` в pull request'ах без секретов. Workflow, параметры и заметки по безопасности смотрите в [руководстве по GitHub Action](https://github.com/Alisher23/storelingo/blob/main/docs/github-action.ru.md).
+
+## Как работает перевод
+
+1. Для каждого магазина и целевой локали storelingo решает по каждому полю: пропустить, если исходник пуст или отсутствует; перевести, если целевой файл отсутствует или пуст (только пробелы); пропустить, если вы правили переведённый файл руками; пропустить, если исходник не изменился с прошлого запуска; иначе перевести.
+2. Один запрос на магазин и локаль несёт все выбранные поля вместе с `context`, списком `doNotTranslate`, `terms` этой локали и лимитом каждого поля. В запросе просят естественный, идиоматичный текст и сохранение переносов строк и маркированных списков.
+3. JSON-ответ проверяется; невалидный ответ повторяется один раз.
+4. Поле длиннее лимита отправляется на сокращение, максимум 2 раза. Если оно всё ещё не помещается, для этого поля ничего не пишется, а в отчёте будет ошибка.
+5. `keywords` App Store нормализуются кодом после ответа: trim, через запятую без пробелов, без дублей, без слов из названия и подзаголовка (только что переведённых или текущих `name.txt` / `subtitle.txt` локали, если они в этом запуске не переводятся).
+6. Переводы записываются в папки fastlane. `storelingo.lock.json` хранит хэши исходника и записанного результата. Целевой файл, чей хэш не совпал с lock-файлом, считается отредактированным вами и пропускается, если не указан `--force`. Lock пишется атомарно после каждого поля; коммитьте его в git.
+7. Запуск продолжается после отдельных сбоев. В конце storelingo печатает сводку (переведено, без изменений, правлено вручную, не поддерживается, ошибки, токены) и завершается с кодом 1, если что-то не удалось. Успешные поля уже сохранены.
+
+## Коды локалей
+
+В `sourceLocale` и `targetLocales` storelingo использует собственные коды локалей (например `ru`, `de`, `es-419`, `zh-Hans`) и сам сопоставляет их с кодами каждого магазина: `ru` — это `ru-RU` в Google Play и `ru` в App Store, `es-419` — `es-MX` в App Store, `zh-Hans` — `zh-CN` в Google Play. Папки fastlane используют коды магазинов.
+
+Некоторые языки есть только в одном магазине. Например, `ky` (киргизский), `kk` (казахский) и `uz` (узбекский) есть только в Google Play. Если магазин не поддерживает целевую локаль, она пропускается для этого магазина с предупреждением и учитывается как «не поддерживается» в сводке; второй магазин переводится как обычно. Исходная локаль должна поддерживаться каждым настроенным магазином.
+
+## Стоимость
+
+Модель по умолчанию — `claude-opus-5-5` с `effort: "medium"`. Для более дешёвых запусков укажите в блоке `translator` `"model": "claude-sonnet-5-5"` или `"claude-haiku-5-5"`. Отправляются только изменившиеся поля, поэтому повторные запуски небольшие. После каждого запуска печатаются суммы входных и выходных токенов, по ним можно прикинуть стоимость по прайсу вашего провайдера.
+
+## Поддерживаемые языки
+
+Сгенерировано из `src/locales/table.ts`. «—» значит, что магазин этот язык не поддерживает.
+
+| Код | Язык (English) | 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` |
+
+## Планы
+
+- v0.2 (готово): Google Play `pull` / `push`
+- v0.3 (готово): App Store `pull` / `push`
+- v0.4 (готово): GitHub Action
+- Позже: скриншоты, RuStore, Huawei AppGallery
+
+## Участие в проекте
+
+См. [CONTRIBUTING.md](https://github.com/Alisher23/storelingo/blob/main/CONTRIBUTING.md). Чтобы добавить язык или поправить лимит символов, обычно достаточно изменить один файл с данными. Репозиторий: https://github.com/Alisher23/storelingo
+
+## Лицензия
+
+MIT

package/dist/bin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { main } from "./cli/main.js";
+main(process.argv).then((code) => {
+    process.exitCode = code;
+});

package/dist/cli/main.js

@@ -0,0 +1,258 @@
+import { confirm as promptConfirm } from "@inquirer/prompts";
+import { Command, CommanderError } from "commander";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { STORE_NAMES, configuredStores, runCheck } from "../commands/check.js";
+import { promptInitAnswers, writeInitFiles } from "../commands/init.js";
+import { runPull } from "../commands/pull.js";
+import { runPush } from "../commands/push.js";
+import { runTranslate } from "../commands/translate.js";
+import { CONFIG_FILE, loadConfig } from "../config/load.js";
+import { ExitCode, StorelingoError, exitCodeFor } from "../errors.js";
+import { createLogger } from "../log.js";
+import { createTranslator } from "../translate/engine.js";
+import { createTokenProvider, loadServiceAccount } from "../stores/google-play/auth.js";
+import { createPlayApi } from "../stores/google-play/client.js";
+import { createPlayStore } from "../stores/google-play/store.js";
+import { createAscTokenProvider, loadAscKey } from "../stores/app-store/auth.js";
+import { createAscApi } from "../stores/app-store/client.js";
+import { createAppStoreStore } from "../stores/app-store/store.js";
+import { createLlmClient } from "../translate/providers/index.js";
+const defaultDeps = () => ({
+    cwd: process.cwd(),
+    env: process.env,
+    out: (l) => process.stdout.write(`${l}\n`),
+    err: (l) => process.stderr.write(`${l}\n`),
+});
+const defaultTranslator = (config, env) => createTranslator(createLlmClient(config.translator, env));
+const pkg = createRequire(import.meta.url)("../../package.json");
+const defaultMakeStore = async (store, config, env) => {
+    if (store === "appstore") {
+        if (!config.stores.appstore)
+            throw new StorelingoError("E_CONFIG", "stores.appstore is not configured");
+        const key = await loadAscKey(env);
+        const tokens = createAscTokenProvider({ key });
+        const api = createAscApi({ getToken: () => tokens.getToken() });
+        return createAppStoreStore(api, { appId: config.stores.appstore.appId, platform: config.stores.appstore.platform });
+    }
+    if (!config.stores.play)
+        throw new StorelingoError("E_CONFIG", "stores.play is not configured");
+    const account = await loadServiceAccount(env);
+    const tokens = createTokenProvider({ account });
+    const api = createPlayApi({ packageName: config.stores.play.packageName, getToken: () => tokens.getToken() });
+    return createPlayStore(api);
+};
+/** Validated before any network call; without --store every configured store runs (play, then appstore). */
+function selectStores(option, config) {
+    if (option === undefined)
+        return configuredStores(config);
+    if (option !== "play" && option !== "appstore") {
+        throw new StorelingoError("E_USAGE", `--store must be play or appstore, got ${JSON.stringify(option)}`);
+    }
+    if (!config.stores[option]) {
+        throw new StorelingoError("E_CONFIG", `stores.${option} is not configured`, option === "play"
+            ? "Add stores.play.packageName to storelingo.config.json."
+            : "Add stores.appstore.appId to storelingo.config.json.");
+    }
+    return [option];
+}
+export async function main(argv, deps = defaultDeps()) {
+    let exitCode = ExitCode.OK;
+    const program = new Command();
+    const secrets = [
+        deps.env.ANTHROPIC_API_KEY,
+        deps.env.OPENAI_API_KEY,
+        deps.env.STORELINGO_TRANSLATOR_API_KEY,
+        deps.env.STORELINGO_PLAY_SERVICE_ACCOUNT,
+        deps.env.STORELINGO_ASC_PRIVATE_KEY,
+    ];
+    const logger = () => createLogger({
+        verbose: program.opts().verbose ?? false,
+        secrets,
+        out: deps.out,
+        err: deps.err,
+    });
+    // Raw (unprefixed) stderr line with secrets masked: the logger masks info() and sends it to `out`.
+    const maskedErr = createLogger({ verbose: false, secrets, out: deps.err, err: deps.err }).info;
+    const configPath = () => resolve(deps.cwd, program.opts().config ?? CONFIG_FILE);
+    program
+        .name("storelingo")
+        .description("AI localization for Google Play and App Store listings (fastlane metadata).")
+        .version(pkg.version)
+        .option("--config <path>", `path to the config file (default: ${CONFIG_FILE})`)
+        .option("--verbose", "print debug output")
+        .option("--no-color", "disable colors")
+        .exitOverride()
+        .configureOutput({
+        writeOut: (s) => deps.out(s.trimEnd()),
+        writeErr: (s) => deps.err(s.trimEnd()),
+    });
+    /** Loads credentials for every selected store (no network) so a missing key fails before any store is touched. */
+    const buildClients = async (stores, config) => {
+        const clients = [];
+        for (const store of stores)
+            clients.push([store, await (deps.makeStore ?? defaultMakeStore)(store, config, deps.env)]);
+        return clients;
+    };
+    program
+        .command("init")
+        .description("create storelingo.config.json and fastlane folders")
+        .option("--force", "overwrite an existing config")
+        .action(async (opts) => {
+        const log = logger();
+        const answers = await (deps.promptInit ?? promptInitAnswers)();
+        const created = await writeInitFiles(deps.cwd, answers, { force: opts.force });
+        for (const change of created)
+            log.info(`${change.action} ${change.path}`);
+        log.info("Set ANTHROPIC_API_KEY (Claude), or for OpenAI-compatible: OPENAI_API_KEY for api.openai.com, " +
+            "otherwise STORELINGO_TRANSLATOR_API_KEY + STORELINGO_TRANSLATOR_API_HOST.");
+        log.info("Next: put your source texts into the folders above, then run `npx storelingo translate`.");
+    });
+    program
+        .command("check")
+        .description("validate limits, missing fields and keyword format (offline)")
+        .action(async () => {
+        const log = logger();
+        const config = await loadConfig(configPath());
+        const issues = await runCheck(config, deps.cwd);
+        for (const i of issues) {
+            const where = `${i.store}/${i.locale}${i.field ? `/${i.field}` : ""}`;
+            deps.err(`${i.level} ${where}: ${i.message}`);
+        }
+        const errors = issues.filter((i) => i.level === "error").length;
+        const warnings = issues.length - errors;
+        log.info(`check: ${errors} error(s), ${warnings} warning(s)`);
+        if (errors > 0)
+            exitCode = ExitCode.FAILED;
+    });
+    program
+        .command("translate")
+        .description("translate changed fields into the target locales")
+        .option("--locale <code...>", "only these target locales")
+        .option("--force", "re-translate everything, including manual edits")
+        .action(async (opts) => {
+        const log = logger();
+        const config = await loadConfig(configPath());
+        const translator = (deps.makeTranslator ?? defaultTranslator)(config, deps.env);
+        const report = await runTranslate({
+            config,
+            cwd: deps.cwd,
+            translator,
+            log,
+            locales: opts.locale,
+            force: opts.force,
+        });
+        for (const f of report.failed) {
+            log.error(`${f.store}/${f.locale}${f.field ? `/${f.field}` : ""}: ${f.message}`);
+        }
+        log.info(`Translated ${report.translated} fields; unchanged ${report.unchanged}; ` +
+            `edited manually ${report.manual}; unsupported locales ${report.unsupported}; failed ${report.failed.length}. ` +
+            `Tokens: ${report.usage.inputTokens} in / ${report.usage.outputTokens} out.`);
+        if (report.failed.length > 0)
+            exitCode = ExitCode.FAILED;
+    });
+    program
+        .command("pull")
+        .description("download the current store listings into the fastlane folders")
+        .option("--store <store>", "store to pull from / push to (play or appstore; default: all configured)")
+        .option("--force", "overwrite local files that differ from the store")
+        .action(async (opts) => {
+        const log = logger();
+        const config = await loadConfig(configPath());
+        const stores = selectStores(opts.store, config);
+        const clients = await buildClients(stores, config);
+        for (const [store, client] of clients) {
+            const report = await runPull({ config, cwd: deps.cwd, client, log, force: opts.force });
+            log.info(`Pulled from ${STORE_NAMES[store]}: wrote ${report.written}, unchanged ${report.unchanged}, ` +
+                `kept ${report.skipped.length} different local file(s) (use --force to overwrite).`);
+            for (const path of report.skipped)
+                log.info(`  kept ${path}`);
+        }
+    });
+    program
+        .command("push")
+        .description("show the diff with the live listing and upload after confirmation")
+        .option("--store <store>", "store to pull from / push to (play or appstore; default: all configured)")
+        .option("--dry-run", "only show the diff")
+        .option("--yes", "do not ask for confirmation (required outside a terminal)")
+        .action(async (opts) => {
+        const log = logger();
+        const config = await loadConfig(configPath());
+        const stores = selectStores(opts.store, config);
+        const isTTY = deps.isTTY ?? (process.stdin.isTTY === true && process.stdout.isTTY === true);
+        if (!opts.yes && !deps.confirm && !isTTY && !opts.dryRun) {
+            throw new StorelingoError("E_USAGE", "push needs --yes when not running in an interactive terminal (or use --dry-run)");
+        }
+        const askFor = (message) => {
+            if (opts.yes)
+                return async () => true;
+            if (deps.confirm) {
+                const confirmFn = deps.confirm;
+                return async () => confirmFn(message);
+            }
+            if (isTTY)
+                return async () => promptConfirm({ message, default: false });
+            return async () => false; // --dry-run outside a terminal
+        };
+        const clients = await buildClients(stores, config);
+        for (const [store, client] of clients) {
+            const name = STORE_NAMES[store];
+            const report = await runPush({
+                config,
+                cwd: deps.cwd,
+                client,
+                log,
+                dryRun: opts.dryRun,
+                confirm: askFor(`Upload these changes to ${name}?`),
+            });
+            switch (report.status) {
+                case "pushed": {
+                    const locales = report.locales.join(", ");
+                    log.info(store === "play"
+                        ? `Pushed ${report.locales.length} listing(s) to ${name}: ${locales}. Google reviews listing changes before they go live.`
+                        : `Updated ${report.locales.length} App Store localization(s): ${locales}. ` +
+                            "Changes to an editable version go live with that version; " +
+                            "promotional text on the live version changes right away.");
+                    if (report.skipped.length > 0) {
+                        log.info(store === "appstore"
+                            ? "Some changes were skipped: create a new version in App Store Connect to push them."
+                            : `Some changes were skipped: these fields can't be changed in ${name}.`);
+                    }
+                    break;
+                }
+                case "dry-run":
+                    log.info("Dry run: nothing was changed.");
+                    break;
+                case "cancelled":
+                    log.info("Cancelled: nothing was changed.");
+                    break;
+                case "blocked":
+                    for (const p of report.problems)
+                        log.error(p);
+                    log.error("Push blocked: fix the problems above (nothing was changed).");
+                    exitCode = ExitCode.FAILED;
+                    break;
+                case "nothing":
+                    break;
+            }
+        }
+    });
+    try {
+        await program.parseAsync(argv);
+        return exitCode;
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            return err.exitCode === 0 ? ExitCode.OK : ExitCode.USAGE;
+        }
+        if (err instanceof StorelingoError) {
+            maskedErr(`error [${err.code}]: ${err.message}`);
+            if (err.hint)
+                maskedErr(`hint: ${err.hint}`);
+        }
+        else {
+            maskedErr(`error: ${err.message}`);
+        }
+        return exitCodeFor(err);
+    }
+}