Переводите JSON-файлы локализации, не трогая ключи.
Ключи остаются ключами. Вложенность сохраняется. Переводятся только строковые значения — и только они. Все остальные типы свойств возвращаются без изменений.
Стандартные инструменты перевода не понимают JSON.
Общие API перевода воспринимают ваш JSON как сплошной текст. Они переводят имена ключей вместе со значениями. Они уплощают вложенные объекты. Они объединяют строки, которых не должны. В результате возвращается структурно повреждённый JSON, который требует ручной правки перед использованием. Если вы поддерживаете файлы локализации для рабочего приложения, вы знаете, что использование стандартного API перевода создаёт больше работы, чем экономит.
Проблема глубже, чем просто имена ключей. Стандартные API перевода также портят переменные интерполяции. Строка вроде "Hello {name}, you have {count} messages" возвращается с переведёнными именами переменных — "Hola {nombre}, tienes {cuenta} mensajes" — что ломает любое окружение, ожидающее оригинальные имена переменных. За этим следуют часы отладки.
Для команд, поддерживающих файлы локализации на нескольких языках для рабочего приложения, это не теоретическая проблема. Это уже случалось. Вопрос в том, сколько времени занимает ручной ремонт каждый раз.
PolyLingo обрабатывает ваш JSON перед переводом.
PolyLingo понимает структуру JSON. Он рекурсивно обходит объект, находит строковые значения с переводимым текстом и отправляет на перевод только их. Имена ключей не изменяются. Числа, булевы значения, null и нестроковые типы проходят без изменений. На выходе получается валидный JSON с идентичной структурой — только со строковыми значениями на другом языке.
Переменные интерполяции — {name}, {{count}}, %s и похожие шаблоны — распознаются и сохраняются в процессе перевода. Они заменяются плейсхолдерами перед переводом и восстанавливаются в исходном виде в выходных данных. Модель перевода никогда не видит их как переводимый текст.
Массивы обрабатываются корректно: каждый строковый элемент переводится, а числовые индексы и структура массива остаются без изменений. Смешанные массивы со строками и нестроками (числами, объектами) обрабатываются правильно, нестроковые типы проходят без изменений.
{
"nav_home": "Home",
"nav_pricing": "Pricing",
"hero_title": "Grow your audience globally",
"hero_cta": "Get started for free",
"footer_rights": "All rights reserved."
}{
"nav_home": "Accueil",
"nav_pricing": "Tarifs",
"hero_title": "Développez votre audience mondiale",
"hero_cta": "Commencer gratuitement",
"footer_rights": "Tous droits réservés."
}{
"nav": {
"home": "Home",
"pricing": "Pricing",
"blog": "Blog"
},
"hero": {
"title": "Grow your audience globally",
"subtitle": "Translate in seconds.",
"cta": "Get started for free"
},
"errors": {
"notFound": "Page not found",
"serverError": "Something went wrong"
}
}{
"nav": {
"home": "Inicio",
"pricing": "Precios",
"blog": "Blog"
},
"hero": {
"title": "Expande tu audiencia globalmente",
"subtitle": "Traduce en segundos.",
"cta": "Comienza gratis"
},
"errors": {
"notFound": "Página no encontrada",
"serverError": "Algo salió mal"
}
}curl -X POST https://api.usepolylingo.com/v1/translate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "{\"nav_home\": \"Home\", \"hero_title\": \"Get started\"}",
"format": "json",
"targets": ["es", "fr", "de", "ja", "zh"],
"model": "standard"
}'
# Response:
# {
# "translations": {
# "es": "{\"nav_home\": \"Inicio\", \"hero_title\": \"Empezar\"}",
# "fr": "{\"nav_home\": \"Accueil\", \"hero_title\": \"Commencer\"}",
# ...
# }
# }Что PolyLingo гарантирует для каждого перевода JSON
- ✓Имена ключей не изменяются
- ✓Вложенные объекты и массивы обрабатываются рекурсивно
- ✓Числа, булевы значения, null проходят без изменений
- ✓Все 36 языков в одном запросе
- ✓Автоматическое определение JSON — не нужен флаг формата
- ✓Работает с плоскими и глубоко вложенными файлами локализации
- ✓Переменные интерполяции ({name}, {{count}}, %s) сохраняются точно
- ✓Выход — валидный JSON, парсится без изменений
Три шага к переведённым файлам локализации
Вставьте JSON или вызовите API
Используйте безкодовый переводчик для одноразового перевода: вставьте JSON, выберите языки, скачайте переведённые файлы. Для автоматизации вызовите POST /v1/translate с вашим JSON и кодами целевых языков.
Получите все языки в одном ответе
API возвращает JSON-объект с одной записью на каждый целевой язык, содержащий полностью переведённый файл локализации с идентичной структурой. Без вызовов на каждый язык. Без циклов. Один запрос — все результаты.
Поместите файлы в директорию сообщений
Запишите каждый переведённый файл в messages/es.json, messages/fr.json, messages/de.json — или куда ожидает ваша i18n-библиотека. Структура идентична исходному файлу, дополнительная обработка не нужна.
Где перевод JSON особенно важен
i18n приложений с next-intl или i18next
Переводите ваши файлы messages/*.json или locales/*.json напрямую. Ключи сохраняются, вложенность сохраняется, переменные интерполяции проходят без изменений. Поместите файлы в директорию сообщений и разверните.
Экспорт контента из CMS
Платформы headless CMS часто экспортируют структурированный контент в JSON. PolyLingo переводит строковые значения, сохраняя имена полей, вложенные типы контента и нестроковые значения, такие как даты, булевы значения и идентификаторы.
Ответы API и конфигурационные файлы
Любая структура JSON с переводимыми строковыми значениями — описания продуктов, шаблоны уведомлений, текст в приложении, подаваемый через API — может быть переведена без изменения структуры, от которой зависит ваше приложение.
Часто задаваемые вопросы о переводе JSON
Сохраняются ли переменные интерполяции, такие как {name} или {{count}}?
Да. PolyLingo распознаёт распространённые шаблоны интерполяции, включая {variable}, {{variable}}, %(variable)s и %s перед переводом. Они заменяются стабильными плейсхолдерами, окружающий текст переводится, а оригинальные имена переменных восстанавливаются в выходных данных. Модель перевода никогда не видит имена переменных как переводимый контент.
Что происходит с нестроковыми значениями — числами, булевыми, null?
Нестроговые значения проходят полностью без изменений. PolyLingo переводит только строковые значения, содержащие естественный язык. Числа, булевы значения, null и массивы нестроковых значений сохраняются точно так, как в исходнике.
Может ли PolyLingo обрабатывать глубоко вложенные структуры JSON?
Да. PolyLingo рекурсивно обходит объекты любой глубины вложенности. Перевод применяется ко всем строковым значениям по всей структуре, независимо от глубины вложения.
Что если некоторые ключи содержат непереводимый контент, например слаги или коды?
PolyLingo по умолчанию переводит все строковые значения. Если у вас есть строковые поля, которые не должны переводиться — слаги, языковые коды, технические идентификаторы — рекомендуется либо исключить их из JSON, который вы отправляете, либо использовать явный параметр формата и указать поля для пропуска (скоро будет). Для большинства файлов локализации все строковые значения предназначены для перевода.
Работает ли с JSON5 или JSONC (JSON с комментариями)?
В настоящее время PolyLingo обрабатывает стандартный JSON. JSON5 и JSONC (с комментариями) должны быть предварительно обработаны для удаления комментариев и преобразованы в стандартный JSON перед отправкой. Это обычный шаг в сборочных процессах и добавляет минимальные накладные расходы.
Сколько языков можно указать в одном запросе?
До всех 36 поддерживаемых языков в одном запросе. Ответ содержит один переведённый JSON-объект на каждый код языка. Ограничения по скорости зависят от плана — бесплатный уровень позволяет 10 запросов в минуту, планы Growth и Scale — 200–600 запросов в минуту.
Связанные руководства
Переводите файлы локализации за секунды.
Вставьте JSON, выберите языки, получите валидные файлы локализации для каждого языка.
Начать бесплатный переводВставьте ваш JSON локализации и посмотрите результат — бесплатно, без регистрации.