PolyloДокументация
Открыть Polylo

Polylo для разработчиков

Polylo хранит все строки продукта и их переводы. Разработчик держит в репозитории только файлы исходного языка, а переводы получает одной командой — или прямо в приложении, без новой сборки.

  1. Репозиторий → Polylo. polylo push загружает файлы базового языка: новые ключи, изменённые тексты. Переводы изменённых строк помечаются устаревшими.
  2. Перевод. Переводчики работают в редакторе Polylo, AI переводит пустое и устаревшее, проверки качества ловят сломанные плейсхолдеры и формы числа.
  3. Polylo → репозиторий. polylo pull в CI или «Создать PR» в GitHub кладут файлы переводов в сборку.
  4. Polylo → приложение. Релиз OTA доставляет исправленные строки на телефоны без выпуска версии в магазине.

Адреса: приложение и API — https://app.polylo.dev, раздача OTA — https://cdn.polylo.dev.

Быстрый старт

  1. Проект. В Polylo: «Проекты → Новый проект» — название, адрес (slug), базовый язык и языки перевода. Если приложение показывает только целые числа (вопросы, шаги, дни), включите «Настройки → Основное → Формы числа → только для целых».

  2. Токен. «Настройки → Токены для CLI и CI» → токен области write. Он показывается один раз: положите его в переменную POLYLO_TOKEN (в CI — секретом).

  3. polylo.yml в корне репозитория:

    project: my-app
    baseLanguage: de
    files:
      - path: composeApp/src/commonMain/composeResources/files/i18n/{lang}.json
        format: flat-json
  4. Первая загрузка — исходник и уже готовые переводы:

    polylo push --translations --dry-run   # посмотреть, что изменится
    polylo push --translations
  5. Дальше — polylo push после изменения строк исходника, polylo pull перед сборкой, polylo status — сколько переведено.

  6. Приложение. Подключите файлы и OTA для своей платформы: Android, iOS, Flutter, React Native, Kotlin Multiplatform, веб, сервер.

Статусы и что попадает в файлы

СтатусЗначитВ файлы и OTA
ПустоПеревода нет.Нет (или текст исходника — настройка «Нет перевода»).
AIПеревёл AI, оценка выше порога.Да.
На проверкуAI не уверен или проверка нашла ошибку.По настройке «Выгружать непроверенные»; с ошибками проверки — никогда в OTA.
ПровереноПодтвердил человек.Да.
УстарелоИсходник изменился после перевода.Нет.

Проверки качества: плейсхолдеры ({0}, {name}, %1$s, {{count}}), формы числа по CLDR, длина, глоссарий, теги, пробелы и пунктуация. Ошибка не даёт подтвердить перевод.

Как работает OTA

У каждой платформы два слоя строк. Файлы — polylo pull перед сборкой кладёт переводы в формате платформы, они вшиваются в приложение. OTA — опубликованный в Polylo релиз приложение скачивает при запуске и кладёт поверх вшитых строк: исправленный текст доходит без новой версии.

  1. Токен области ota («Настройки → Токены»): он вшивается в приложение и открывает только опубликованные переводы этого проекта.
  2. Публикация: «Релизы OTA → Опубликовать» или polylo release. Пакет релиза не меняется, откат — переключение манифеста на прежний релиз.
  3. Какие namespace попадают в пакет — «Настройки → Экспорт и OTA → Namespace в пакетах OTA».

Манифест и пакет

GET https://cdn.polylo.dev/ota/<токен ota>/manifest.json

{
  "project": "my-app",
  "baseLanguage": "de",
  "release": 7,
  "publishedAt": "2026-11-22T10:00:00Z",
  "packages": {
    "de": { "url": "r/7/de.json", "sha256": "9f2c…", "size": 18342 },
    "ru": { "url": "r/7/ru.json", "sha256": "41ab…", "size": 20117 }
  }
}

GET https://cdn.polylo.dev/ota/<токен ota>/r/7/ru.json      // адрес — относительно манифеста

{ "settings.title": "Настройки", "questions.count.one": "{count} вопрос", "questions.count.other": "{count} вопросов" }
  • Пакет — плоский JSON «ключ → строка». Формы числа — отдельными ключами ключ.one, ключ.few, ключ.other… по правилам CLDR языка.
  • Проверяйте sha256 пакета по манифесту и сохраняйте пакет только при совпадении. Адрес пакета принимайте только вида r/<номер>/<язык>.json, размер — до 5 МБ.
  • Нет сети или ошибка — оставайтесь на вшитых строках и последнем сохранённом пакете.
  • Манифест кэшируется в CDN не дольше минуты (запрашивайте его без кэша браузера: fetch(…, { cache: 'no-store' })), пакеты — навсегда (они не меняются). Ответы разрешены для любого сайта (CORS).

Для Kotlin Multiplatform и Android всё это делает SDK; для остальных платформ ниже — готовый код на 30–40 строк.

Android

Файлы — strings.xml. Исходник лежит в values/ без кода языка, поэтому его путь задаётся полем source; коды с регионом Android пишет как pt-rBR — это поле languages:

files:
  - path: app/src/main/res/values-{lang}/strings.xml
    source: app/src/main/res/values/strings.xml
    format: android-xml
    languages:
      pt-BR: pt-rBR
      zh-Hans: b+zh+Hans

OTA — тот же SDK (на Android берётся его JVM-вариант) и HTTP-клиент Ktor, например io.ktor:ktor-client-okhttp. Ресурсы Android во время работы не подменить, поэтому строки, которые нужно обновлять без сборки, читайте через обёртку: ключ в Polylo — это имя ресурса.

class App : Application() {
    val ota by lazy {
        PolyloOta(BuildConfig.POLYLO_OTA_URL, HttpClient(OkHttp), FileOtaStore(filesDir.path + "/polylo-ota"))
    }
}

object Strings {
    @Volatile var ota: Map<String, String> = emptyMap()

    fun get(context: Context, @StringRes id: Int): String =
        ota[context.resources.getResourceEntryName(id)] ?: context.getString(id)
}

// Activity.onCreate
lifecycleScope.launch {
    val lang = resources.configuration.locales[0].toLanguageTag()
    val ota = (application as App).ota
    Strings.ota = ota.stored(lang)?.strings.orEmpty()
    (ota.refresh(lang) as? OtaResult.Updated)?.let { Strings.ota = it.strings.strings }
}

titleView.text = Strings.get(this, R.string.settings_title)

iOS (Swift)

Файлы — String Catalog (один файл на все языки) или .strings по папкам .lproj:

files:
  - path: MyApp/Localizable.xcstrings
    format: xcstrings
  # или:
  # - path: MyApp/{lang}.lproj/Localizable.strings
  #   format: apple-strings

OTA — без зависимостей, на URLSession и CryptoKit:

import CryptoKit
import Foundation

final class PolyloOta {
    private struct Manifest: Decodable { let packages: [String: Entry] }
    private struct Entry: Decodable { let url: String; let sha256: String; let size: Int }

    private let manifestURL: URL
    private let dir = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
        .appendingPathComponent("polylo-ota")
    private(set) var strings: [String: String] = [:]

    init(manifestURL: URL) { self.manifestURL = manifestURL }

    /// При запуске: сохранённый пакет, без сети.
    func loadStored(_ lang: String) {
        guard let data = try? Data(contentsOf: dir.appendingPathComponent("\(lang).json")) else { return }
        strings = (try? JSONDecoder().decode([String: String].self, from: data)) ?? [:]
    }

    /// В фоне: новый пакет, только если sha256 совпал с манифестом.
    func refresh(_ lang: String) async {
        guard let m = try? await URLSession.shared.data(from: manifestURL).0,
              let entry = (try? JSONDecoder().decode(Manifest.self, from: m))?.packages[lang],
              entry.url.range(of: #"^r/\d+/[A-Za-z0-9-]+\.json$"#, options: .regularExpression) != nil,
              entry.size <= 5_000_000,
              let data = try? await URLSession.shared.data(from: manifestURL.deletingLastPathComponent().appendingPathComponent(entry.url)).0,
              SHA256.hash(data: data).map({ String(format: "%02x", $0) }).joined() == entry.sha256.lowercased(),
              let fresh = try? JSONDecoder().decode([String: String].self, from: data) else { return }
        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
        try? data.write(to: dir.appendingPathComponent("\(lang).json"), options: .atomic)
        strings = fresh
    }
}

let ota = PolyloOta(manifestURL: URL(string: "https://cdn.polylo.dev/ota/plo_o_…/manifest.json")!)

/// Строка: OTA, если есть, иначе вшитая.
func L(_ key: String) -> String { ota.strings[key] ?? NSLocalizedString(key, comment: "") }

Flutter

Файлы — ARB для flutter gen-l10n. Flutter пишет регион через подчёркивание — app_pt_BR.arb:

files:
  - path: lib/l10n/app_{lang}.arb
    format: arb
    languages:
      pt-BR: pt_BR

Геттеры, которые создаёт gen-l10n, во время работы не подменить — строки, которые нужно обновлять через OTA, берите через tr(). Пакеты http, crypto, path_provider:

import 'dart:convert';
import 'dart:io';
import 'package:crypto/crypto.dart';
import 'package:http/http.dart' as http;
import 'package:path_provider/path_provider.dart';

class PolyloOta {
  PolyloOta(this.manifestUrl);
  final Uri manifestUrl;
  Map<String, String> strings = {};

  Future<File> _file(String lang) async =>
      File('${(await getApplicationSupportDirectory()).path}/polylo-ota/$lang.json');

  /// При запуске: сохранённый пакет, без сети.
  Future<void> loadStored(String lang) async {
    final f = await _file(lang);
    if (await f.exists()) strings = Map<String, String>.from(jsonDecode(await f.readAsString()));
  }

  /// В фоне: новый пакет, только если sha256 совпал с манифестом.
  Future<bool> refresh(String lang) async {
    try {
      final m = await http.get(manifestUrl);
      if (m.statusCode != 200) return false;
      final entry = (jsonDecode(m.body)['packages'] as Map)[lang];
      if (entry == null || !RegExp(r'^r/\d+/[A-Za-z0-9-]+\.json$').hasMatch(entry['url']) || entry['size'] > 5000000) return false;
      final res = await http.get(manifestUrl.resolve(entry['url']));
      if (res.statusCode != 200 || sha256.convert(res.bodyBytes).toString() != entry['sha256']) return false;
      final f = await _file(lang);
      await f.parent.create(recursive: true);
      await f.writeAsBytes(res.bodyBytes, flush: true);
      strings = Map<String, String>.from(jsonDecode(utf8.decode(res.bodyBytes)));
      return true;
    } catch (_) {
      return false;
    }
  }
}

final ota = PolyloOta(Uri.parse('https://cdn.polylo.dev/ota/plo_o_…/manifest.json'));

String tr(String key, String bundled) => ota.strings[key] ?? bundled;
// Text(tr('settings_title', AppLocalizations.of(context)!.settings_title))

React Native

Файлы — JSON для i18next (i18next + react-i18next):

files:
  - path: src/locales/{lang}/{namespace}.json
    format: i18next-json

OTA — fetch, хранение в @react-native-async-storage/async-storage, sha256 — js-sha256. Пакет плоский, i18next ждёт вложенные ключи и формы числа через _ — функция toI18next из раздела Веб переводит одно в другое.

import AsyncStorage from '@react-native-async-storage/async-storage';
import { sha256 } from 'js-sha256';
import i18n from 'i18next';

const MANIFEST = 'https://cdn.polylo.dev/ota/plo_o_…/manifest.json';
const NS = 'translation';   // namespace i18next, куда кладутся строки OTA

export async function loadStoredOta(lang) {
  const saved = await AsyncStorage.getItem(`polylo-ota:${lang}`);
  if (saved) i18n.addResourceBundle(lang, NS, toI18next(JSON.parse(saved)), true, true);
}

export async function refreshOta(lang) {
  try {
    const manifest = await (await fetch(MANIFEST, { cache: 'no-store' })).json();
    const entry = manifest.packages?.[lang];
    if (!entry || !/^r\/\d+\/[A-Za-z0-9-]+\.json$/.test(entry.url) || entry.size > 5_000_000) return;
    const res = await fetch(new URL(entry.url, MANIFEST).toString());
    const text = await res.text();
    if (!res.ok || sha256(text) !== entry.sha256) return;   // js-sha256 считает по UTF-8 — как сервер
    await AsyncStorage.setItem(`polylo-ota:${lang}`, text);
    i18n.addResourceBundle(lang, NS, toI18next(JSON.parse(text)), true, true);
  } catch (e) {
    // нет сети — остаёмся на вшитых строках
  }
}

Kotlin Multiplatform

Файлы — формат flat-json, строки читаются из composeResources:

files:
  - path: composeApp/src/commonMain/composeResources/files/i18n/{lang}.json
    format: flat-json

OTA — SDK Polylo: Android, iosArm64, iosSimulatorArm64, jvm. HTTP-клиент (Ktor) передаёт приложение — своего движка SDK не тянет.

// build.gradle.kts
commonMain.dependencies {
    implementation("com.mvlikhachev.polylo:sdk:0.1.0")
}

SDK скачивается из публичного Maven-репозитория Polylo — https://cdn.polylo.dev/maven, без токена. Работает он только с токеном области ota, выпущенным в Polylo для вашего проекта: без него сервер отвечает 401, а приложение остаётся на вшитых строках.

// commonMain
val ota = PolyloOta(
    manifestUrl = BuildConfig.POLYLO_OTA_URL,   // пусто — OTA выключен
    http = createHttpClient(),
    store = FileOtaStore(otaDirectory),          // Android: filesDir.path + "/polylo-ota"; iOS: defaultOtaDirectory()
    log = { println("MyApp OTA: $it") },
)

// При запуске — без сети, сразу: OTA-строки поверх вшитых.
val strings = bundled + ota.stored(language)?.strings.orEmpty()

// В фоне:
when (val r = ota.refresh(language)) {
    is OtaResult.Updated -> apply(bundled + r.strings.strings)
    else -> Unit   // UpToDate, NoRelease, NoPackage, Failed — остаёмся на том, что есть
}

Веб

Файлы — те же JSON для i18next (или flat-json, если у вас своя функция перевода):

files:
  - path: src/locales/{lang}/{namespace}.json
    format: i18next-json

OTA — fetch и crypto.subtle прямо из браузера; CDN Polylo разрешает запросы с любого сайта. Токен ota в коде сайта виден всем — он открывает только опубликованные переводы.

const MANIFEST = 'https://cdn.polylo.dev/ota/plo_o_…/manifest.json';
const PLURAL = /^(.*)\.(zero|one|two|few|many|other)$/;

/** Плоский пакет Polylo → ресурсы i18next: вложенные ключи, формы числа — key_one. */
export function toI18next(flat) {
  const out = {};
  for (const [key, value] of Object.entries(flat)) {
    const plural = key.match(PLURAL);
    const path = plural && `${plural[1]}.other` in flat
      ? [...plural[1].split('.').slice(0, -1), `${plural[1].split('.').pop()}_${plural[2]}`]
      : key.split('.');
    let node = out;
    for (const part of path.slice(0, -1)) node = node[part] = typeof node[part] === 'object' ? node[part] : {};
    node[path[path.length - 1]] = value;
  }
  return out;
}

async function sha256hex(buf) {
  const hash = new Uint8Array(await crypto.subtle.digest('SHA-256', buf));
  return [...hash].map((b) => b.toString(16).padStart(2, '0')).join('');
}

export async function refreshOta(i18n, lang) {
  try {
    const saved = localStorage.getItem(`polylo-ota:${lang}`);
    if (saved) i18n.addResourceBundle(lang, 'translation', toI18next(JSON.parse(saved)), true, true);
    const manifest = await (await fetch(MANIFEST, { cache: 'no-store' })).json();
    const entry = manifest.packages?.[lang];
    if (!entry || !/^r\/\d+\/[A-Za-z0-9-]+\.json$/.test(entry.url) || entry.size > 5_000_000) return;
    const res = await fetch(new URL(entry.url, MANIFEST));
    const buf = await res.arrayBuffer();
    if (!res.ok || (await sha256hex(buf)) !== entry.sha256) return;
    const text = new TextDecoder().decode(buf);
    localStorage.setItem(`polylo-ota:${lang}`, text);
    i18n.addResourceBundle(lang, 'translation', toI18next(JSON.parse(text)), true, true);
  } catch (e) {
    // нет сети — остаёмся на вшитых строках
  }
}

Сервер

Обычно серверу хватает файлов: polylo pull на этапе сборки кладёт переводы в ресурсы (письма, push-уведомления, тексты ошибок API), формат — любой подходящий, чаще flat-json.

Если строки нужно обновлять без выкладки — читайте OTA во время работы. На JVM (Ktor, Spring) подходит SDK как есть: FileOtaStore в каталоге данных сервиса и refresh по таймеру. Для Node.js:

import { createHash } from 'node:crypto';

const MANIFEST = process.env.POLYLO_OTA_URL;   // https://cdn.polylo.dev/ota/plo_o_…/manifest.json
const strings = new Map();                       // язык → { ключ: строка }

async function refresh(lang) {
  try {
    const manifest = await (await fetch(MANIFEST, { cache: 'no-store' })).json();
    const entry = manifest.packages?.[lang];
    if (!entry || !/^r\/\d+\/[A-Za-z0-9-]+\.json$/.test(entry.url) || entry.size > 5_000_000) return;
    const res = await fetch(new URL(entry.url, MANIFEST));
    const buf = Buffer.from(await res.arrayBuffer());
    if (!res.ok || createHash('sha256').update(buf).digest('hex') !== entry.sha256) return;
    strings.set(lang, JSON.parse(buf.toString('utf8')));
  } catch (e) {
    console.warn('Polylo OTA:', e.message);   // остаёмся на прежних строках
  }
}

setInterval(() => ['de', 'ru'].forEach(refresh), 5 * 60 * 1000);

export const t = (lang, key, fallback) => strings.get(lang)?.[key] ?? fallback;

Утилита polylo

Консольная программа на Kotlin: нужна только Java 21, Node не нужен.

Скачать polylo (zip) Распакуйте и добавьте polylo/bin в PATH.

Переменные окружения

ПеременнаяЧто это
POLYLO_TOKENТокен проекта. Только здесь — в polylo.yml токен не принимается.
POLYLO_URLАдрес сервера, по умолчанию https://app.polylo.dev. Только https://; http:// — лишь для localhost.

Команды

polylo push                     # загрузить исходники (файлы базового языка)
polylo push --dry-run           # что изменится, ничего не записывая
polylo push --translations      # и готовые переводы
polylo push --translations --review         # переводы — «на проверку» (в релиз не идут)
polylo push --translations --mark-reviewed  # переводы проверены людьми — «проверено»
polylo push --archive-missing   # убрать в архив ключи, которых больше нет в файлах
polylo pull                     # скачать переводы всех активных языков
polylo pull --lang ru,uk --status reviewed
polylo status --fail-under 100  # код 1, если какой-то язык готов меньше чем на 100%
polylo translate --dry-run      # оценка AI-перевода: строк, слов, стоимость
polylo translate --lang ru,uk   # AI-перевод пустых и устаревших, ждёт окончания
polylo release                  # опубликовать OTA-релиз
polylo store pull               # описания для Google Play и App Store в fastlane/metadata
polylo store push               # описания из fastlane/metadata в Polylo
polylo mcp                      # MCP-сервер для AI-ассистента (см. ниже)

Статус загруженных переводов: обычный push --translations ставит «проверено» новым и изменённым строкам, но не трогает строки с прежним текстом — чтобы цикл pull → push не подтверждал AI-переводы молча. --review загружает «на проверку» (они не попадают в релиз OTA и бандл, пока их не подтвердят), --mark-reviewed ставит «проверено» и строкам с неизменным текстом. polylo release предупреждает о пустых пакетах языка. Запросы при 502/503/504 и обрыве связи утилита повторяет сама.

Коды выхода: 0 — успех, 1 — ошибка или порог не пройден, 2 — неверные аргументы или конфиг. pull пишет только внутрь репозитория и не идёт через символические ссылки; файл исходника не создаётся, если его нет.

polylo.yml и форматы

project: my-app
baseLanguage: de
files:
  # Строки интерфейса: один файл на язык.
  - path: app/i18n/{lang}.json
    format: flat-json
  # Несколько файлов на язык: namespace берётся из имени файла исходника.
  - path: web/locales/{lang}/{namespace}.json
    format: i18next-json
  # Контентный JSON: переводятся только перечисленные поля.
  - path: content/questions.json
    format: content-json
    namespace: questions
    items: questions
    translate: [text, answers.*, explanation]
    groupBy: id
  • {lang} — код языка (de, pt-BR), {namespace} — файл или раздел.
  • Путь без {lang} у xcstrings — один файл на все языки; у остальных форматов это файл исходника.
  • Пути — от папки, где лежит polylo.yml; выйти за пределы репозитория нельзя.
  • source — путь файла базового языка, если он лежит не по шаблону (Android: values/strings.xml).
  • languages — как код языка Polylo пишется в пути: pt-BR: pt-rBR (Android), pt-BR: pt_BR (Flutter).
formatФайлы
flat-jsonПлоский JSON «ключ → строка», формы числа — key.one, key.other… Приложения на Kotlin Multiplatform.
i18next-jsoni18next, вложенные ключи и суффиксы форм числа.
android-xmlstrings.xml с plurals.
xcstringsString Catalog Xcode, все языки в одном файле.
apple-strings, apple-stringsdictLocalizable.strings и формы числа .stringsdict.
arbFlutter (ICU-сообщения).
xliff-1.2, xliff-2.0Обмен с бюро переводов.
gettext-pogettext .po / .pot (PHP, Python/Django, WordPress). Ключ — msgid (с контекстом — msgctxt::msgid), формы числа — по Plural-Forms языка, #, fuzzy — «на проверку». POT (все msgstr пустые) читается как исходник.
rails-yamlRuby on Rails config/locales/<lang>.yml: корень — код языка, ключи — путь через точку, формы числа — вложенные one/few/other, плейсхолдеры %{name}. Списки (date.day_names) не переводятся.
xlsx, csvТаблица для переводчика без доступа в Polylo — колонки Key, Form, Source, Translation, Status, Context (заголовки по-английски, переводчик может быть любым). Переводчик заполняет колонку Translation, заполненная таблица загружается обратно. CSV — UTF-8 с BOM, читается и с разделителем «;» (Excel в немецкой и русской локали); ячейки, похожие на формулу, защищены апострофом.
content-jsonСвой JSON с контентом: items — путь к массиву объектов, translate — какие поля, groupBy — поле с id ($key — id в ключе словаря).

Каждый формат выгружается обратно байт в байт — порядок ключей и оформление файла сохраняются, лишних изменений в diff нет.

CI

Типичная схема: при изменении исходника — push, перед сборкой — pull, релизная сборка не проходит, пока переводы не готовы. Пример для GitHub Actions:

name: translations
on:
  push:
    branches: [main]
jobs:
  polylo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with: { distribution: temurin, java-version: 21 }
      - run: |
          curl -fsSL https://app.polylo.dev/docs/download/polylo-cli.zip -o polylo.zip
          unzip -q polylo.zip && echo "$PWD/polylo/bin" >> "$GITHUB_PATH"
      - run: polylo push
        env: { POLYLO_TOKEN: "${{ secrets.POLYLO_TOKEN }}" }
      - run: polylo pull && polylo status --fail-under 100
        env: { POLYLO_TOKEN: "${{ secrets.POLYLO_TOKEN }}" }

Если не хочется коммитить из CI, используйте PR из Polylo — он открывается одной кнопкой или запросом POST /api/v1/github/pull-request.

Описания для магазинов

Название, описание, ключевые слова и «что нового» для Google Play и App Store живут в проекте на вкладке «Магазины» — ключами namespace store с лимитами длины магазинов, поэтому переводятся так же, как строки интерфейса: вручную, AI, с проверкой длины. Обмен с репозиторием — папкой fastlane metadata, которую читают fastlane supply (Google Play) и fastlane deliver (App Store).

polylo store push --dry-run   # что изменится в Polylo из fastlane/metadata
polylo store push             # загрузить
polylo store pull             # переводы в fastlane/metadata (--dir — другая папка)
МагазинФайлы (лимит знаков)
Google Play
metadata/android/<локаль>/
title.txt (30), short_description.txt (80), full_description.txt (4000), changelogs/default.txt (500)
App Store
metadata/<локаль>/
name.txt (30), subtitle.txt (30), promotional_text.txt (170), description.txt (4000), keywords.txt (100), release_notes.txt (4000)

Языки проекта сопоставляются с локалями магазинов сами (de → de-DE, у App Store ru → ru, zh-Hans → zh-Hans). Текст длиннее лимита магазина в выгрузку не попадает.

Тарифы и лимиты

Проект принадлежит команде, у команды — тариф: число проектов, языков в проекте, участников, ключей, слов AI-перевода в месяц и набор возможностей (GitHub, webhooks, задачи, магазины и другие). Текущий расход — «Тариф и расход» в приложении. Действие, которое не помещается в тариф, получает ответ 402 Payment Required:

{ "error": "plan_limit_reached", "message": "Лимит тарифа Free: ключей — не больше 500. …" }
{ "error": "plan_feature_unavailable", "message": "Webhooks — нет в тарифе Free. …" }

В CI это видно как ошибка шага polylo push или polylo translate с тем же текстом. Загрузка файла с превышением лимита ключей в режиме --dry-run не падает, а предупреждает. Отменённая подписка или закончившийся пробный период — действуют лимиты бесплатного тарифа; проекты и переводы при этом остаются.

MCP для AI-ассистента

AI-ассистент в редакторе кода (Claude Code, Cursor и другие клиенты MCP) может сам работать со строками: найти похожий ключ, прежде чем писать новую строку, завести ключ с текстом и описанием, перевести и выгрузить файлы в репозиторий. Сервер MCP — команда polylo mcp той же утилиты, с тем же токеном проекта.

// .mcp.json в корне репозитория (Claude Code; у Cursor — .cursor/mcp.json)
{
  "mcpServers": {
    "polylo": {
      "command": "polylo",
      "args": ["mcp"],
      "env": { "POLYLO_TOKEN": "${POLYLO_TOKEN}" }
    }
  }
}

Токен в файл не пишите — он подставляется из переменной окружения. Для заведения строк и перевода нужен токен write; с read ассистент сможет только искать.

ИнструментЧто делает
polylo_projectБазовый язык, языки и их готовность.
polylo_search_keysКлючи по имени или тексту на любом языке — с переводами и статусами.
polylo_create_keyНовая строка: имя, текст на базовом языке (или формы числа), описание для переводчиков, namespace, длина.
polylo_set_translationПеревод ключа на язык; version защищает от перезаписи чужой правки.
polylo_translate, polylo_jobAI-перевод пустого и устаревшего (или указанных ключей) и его ход.
polylo_pullВыгрузка файлов по polylo.yml, как polylo pull.

GitHub

  1. Профиль → GitHub → Подключить GitHub. Polylo покажет код — введите его на github.com/login/device и подтвердите доступ. Каждый подключает свой аккаунт.
  2. Проект → Настройки → GitHub. Выберите репозиторий из своих (с правом записи) и ветку. PR открываются от имени того, кто выбрал репозиторий.
  3. Создать PR. Polylo читает polylo.yml из ветки, выгружает файлы по тем же правилам, что polylo pull, и открывает PR одним коммитом только с изменёнными файлами. Из CI — POST /api/v1/github/pull-request с токеном write.

Webhooks

«Настройки → Webhooks» (владелец проекта): адрес https:// и события. Polylo отправляет POST с JSON, до трёх попыток (сразу, через 10 секунд, через минуту). Адреса внутренних сетей не принимаются.

{
  "event": "release.published",
  "project": { "id": "…", "slug": "my-app" },
  "target": { "type": "release", "id": "7" },
  "details": "languages=de,ru,uk",
  "actor": "token",
  "timestamp": "2026-11-22T10:00:00Z"
}

События: key.created, key.updated, key.archived, key.restored, translation.updated, translation.reviewed, translation.unreviewed, file.imported, release.published, release.activated, task.created, task.language_completed, task.closed, comment.added, ai_job.started, ai_job.finished (в details — статус, сколько переведено и стоимость).

Проверка подписи

Каждый запрос подписан: заголовок X-Polylo-Signature: sha256=<hex> — HMAC-SHA256 тела запроса секретом webhook (показывается один раз при создании). Сравнивайте за постоянное время:

fun verify(body: ByteArray, header: String, secret: String): Boolean {
    val mac = javax.crypto.Mac.getInstance("HmacSHA256")
    mac.init(javax.crypto.spec.SecretKeySpec(secret.toByteArray(), "HmacSHA256"))
    val expected = "sha256=" + mac.doFinal(body).joinToString("") { "%02x".format(it) }
    return java.security.MessageDigest.isEqual(expected.toByteArray(), header.toByteArray())
}

API

Всё, что делает CLI, доступно по HTTP: https://app.polylo.dev/api/v1, заголовок Authorization: Bearer <токен проекта>. Проект определяется токеном. Лимит — 600 запросов в минуту на токен. Ошибки — {"error": "код", "message": "текст"}.

ЗапросЧто делаетТокен
GET /projectПроект, языки, готовностьread
POST /files/importЗагрузить файл (format, lang, namespace, dryRun)write
GET /files/exportСкачать файл переводовread
GET /keys, POST /keysКлючи: список с фильтрами, созданиеread / write
PATCH /keys/{id}, PUT /keys/{id}/translations/{lang}Изменить ключ, переводwrite
GET /glossary, PUT /glossaryГлоссарий проектаread / write
POST /ai-jobs, GET /ai-jobs/{id}AI-перевод: оценка (dryRun), запуск, ходwrite / read
GET /releases, POST /releasesРелизы OTAread / write
POST /github/pull-requestPR с переводами в репозиторий проектаwrite
GET /store/export, POST /store/importОписания для Google Play и App Store — папкой fastlane metadata (zip)read / write

Полное описание — openapi.yaml (OpenAPI 3).

Токены и роли

ТокенДля чего
readЧтение: pull, status, выгрузка.
writeВсё, что CLI и CI: push, AI-перевод, релизы, PR.
otaТолько раздача опубликованных пакетов OTA — вшивается в приложение. В API не пускается.

Токены выпускает владелец проекта, хранятся они только в виде хеша — потерянный токен не восстановить, выпустите новый и отзовите старый. Роли в проекте: владелец (всё), разработчик (ключи, загрузка, релизы), переводчик (свои языки), наблюдатель (чтение). Каждое изменение пишется в аудит.