Polylo для разработчиков
Polylo хранит все строки продукта и их переводы. Разработчик держит в репозитории только файлы исходного языка, а переводы получает одной командой — или прямо в приложении, без новой сборки.
- Репозиторий → Polylo.
polylo pushзагружает файлы базового языка: новые ключи, изменённые тексты. Переводы изменённых строк помечаются устаревшими. - Перевод. Переводчики работают в редакторе Polylo, AI переводит пустое и устаревшее, проверки качества ловят сломанные плейсхолдеры и формы числа.
- Polylo → репозиторий.
polylo pullв CI или «Создать PR» в GitHub кладут файлы переводов в сборку. - Polylo → приложение. Релиз OTA доставляет исправленные строки на телефоны без выпуска версии в магазине.
Адреса: приложение и API — https://app.polylo.dev, раздача OTA — https://cdn.polylo.dev.
Быстрый старт
Проект. В Polylo: «Проекты → Новый проект» — название, адрес (slug), базовый язык и языки перевода. Если приложение показывает только целые числа (вопросы, шаги, дни), включите «Настройки → Основное → Формы числа → только для целых».
Токен. «Настройки → Токены для CLI и CI» → токен области
write. Он показывается один раз: положите его в переменнуюPOLYLO_TOKEN(в CI — секретом).polylo.yml в корне репозитория:
project: my-app baseLanguage: de files: - path: composeApp/src/commonMain/composeResources/files/i18n/{lang}.json format: flat-jsonПервая загрузка — исходник и уже готовые переводы:
polylo push --translations --dry-run # посмотреть, что изменится polylo push --translationsДальше —
polylo pushпосле изменения строк исходника,polylo pullперед сборкой,polylo status— сколько переведено.Приложение. Подключите файлы и OTA для своей платформы: Android, iOS, Flutter, React Native, Kotlin Multiplatform, веб, сервер.
Статусы и что попадает в файлы
| Статус | Значит | В файлы и OTA |
|---|---|---|
| Пусто | Перевода нет. | Нет (или текст исходника — настройка «Нет перевода»). |
| AI | Перевёл AI, оценка выше порога. | Да. |
| На проверку | AI не уверен или проверка нашла ошибку. | По настройке «Выгружать непроверенные»; с ошибками проверки — никогда в OTA. |
| Проверено | Подтвердил человек. | Да. |
| Устарело | Исходник изменился после перевода. | Нет. |
Проверки качества: плейсхолдеры ({0}, {name}, %1$s, {{count}}),
формы числа по CLDR, длина, глоссарий, теги, пробелы и пунктуация. Ошибка не даёт подтвердить перевод.
Как работает OTA
У каждой платформы два слоя строк. Файлы — polylo pull перед сборкой кладёт
переводы в формате платформы, они вшиваются в приложение. OTA — опубликованный в Polylo релиз
приложение скачивает при запуске и кладёт поверх вшитых строк: исправленный текст доходит без новой версии.
- Токен области
ota(«Настройки → Токены»): он вшивается в приложение и открывает только опубликованные переводы этого проекта. - Публикация: «Релизы OTA → Опубликовать» или
polylo release. Пакет релиза не меняется, откат — переключение манифеста на прежний релиз. - Какие 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-json | i18next, вложенные ключи и суффиксы форм числа. |
android-xml | strings.xml с plurals. |
xcstrings | String Catalog Xcode, все языки в одном файле. |
apple-strings, apple-stringsdict | Localizable.strings и формы числа .stringsdict. |
arb | Flutter (ICU-сообщения). |
xliff-1.2, xliff-2.0 | Обмен с бюро переводов. |
gettext-po | gettext .po / .pot (PHP, Python/Django, WordPress). Ключ — msgid (с контекстом — msgctxt::msgid), формы числа — по Plural-Forms языка, #, fuzzy — «на проверку». POT (все msgstr пустые) читается как исходник. |
rails-yaml | Ruby 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 Playmetadata/android/<локаль>/ | title.txt (30), short_description.txt (80), full_description.txt (4000), changelogs/default.txt (500) |
App Storemetadata/<локаль>/ | 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_job | AI-перевод пустого и устаревшего (или указанных ключей) и его ход. |
polylo_pull | Выгрузка файлов по polylo.yml, как polylo pull. |
GitHub
- Профиль → GitHub → Подключить GitHub. Polylo покажет код — введите его на github.com/login/device и подтвердите доступ. Каждый подключает свой аккаунт.
- Проект → Настройки → GitHub. Выберите репозиторий из своих (с правом записи) и ветку. PR открываются от имени того, кто выбрал репозиторий.
- Создать 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 | Релизы OTA | read / write |
POST /github/pull-request | PR с переводами в репозиторий проекта | 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 не пускается. |
Токены выпускает владелец проекта, хранятся они только в виде хеша — потерянный токен не восстановить, выпустите новый и отзовите старый. Роли в проекте: владелец (всё), разработчик (ключи, загрузка, релизы), переводчик (свои языки), наблюдатель (чтение). Каждое изменение пишется в аудит.