PolyLingo теперь поддерживает региональные языковые коды: fr-CA, pt-BR, es-MX и другие

Теперь вы можете передавать коды региональных диалектов напрямую в качестве целей перевода в PolyLingo. fr-CA, pt-BR, es-MX, en-GB и несколько других теперь являются допустимыми значениями в вашем массиве targets, наряду с их общими аналогами или вместо них.

Ничего не меняется в том, как вы вызываете API. Тот же конечный пункт, та же структура запроса. Просто у вас теперь больше допустимых кодов на выбор.

Что было добавлено

Семь новых региональных кодов, соответствующих стандарту BCP-47:

Код	Язык
`en-GB`	Английский (Великобритания)
`fr-CA`	Французский (Канада)
`es-ES`	Испанский (Испания)
`es-MX`	Испанский (Мексика)
`pt-PT`	Португальский (Португалия)
`pt-BR`	Португальский (Бразилия)
`zh-HK`	Китайский (Гонконг)

Они дополняют существующий zh-TW (традиционный китайский), который уже использовал ту же конвенцию BCP-47. Лимит целей также был увеличен с 36 до 50, чтобы учесть команды, которые используют несколько региональных вариантов в одном вызове.

Почему важны региональные коды

Общие языковые коды (fr, pt, es) подходят, когда ваша аудитория широкая или смешанная. Но когда вы выпускаете продукт для конкретной страны, общий код часто недостаточен.

Бразильский португальский и европейский португальский отличаются лексикой, орфографией и стилем, что важно для носителей языка. Мексиканский и кастильский испанский достаточно похожи, чтобы общий перевод не казался чужим ни одному из них, но и не был полностью естественным для обоих. Канадский французский имеет свои собственные нормы, которые отличаются от парижского французского и сразу заметны квебекцам.

Если вы продаёте на конкретный рынок, этот рынок заслуживает перевода, написанного специально для него. Региональные коды делают это возможным без необходимости отдельного вызова API или отдельного рабочего процесса.

Один вызов, несколько вариантов

Общие и региональные коды могут сосуществовать в одном запросе. Каждый получает свой ключ в ответе:

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Your order has been confirmed.",
    "targets": ["fr", "fr-CA", "pt", "pt-BR"]
  }'

{
  "translations": {
    "fr":    "Votre commande a été confirmée.",
    "fr-CA": "Votre commande a été confirmée.",
    "pt":    "O seu pedido foi confirmado.",
    "pt-BR": "O seu pedido foi confirmado."
  }
}

Вы получаете четыре ключа в ответе, по одному на каждый код. Если fr и fr-CA дают одинаковый результат для данной строки, это ожидаемо — они будут различаться в лексике и стиле там, где разница важна.

Целевое использование только для конкретного рынка

Если вы создаёте для известного рынка и не нуждаетесь в общей версии, просто передайте региональный код:

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Sign in to your account.",
    "targets": ["en-GB", "es-MX", "pt-BR", "zh-HK"]
  }'

Создание списка целевых рынков в Node.js

import { PolyLingo } from '@polylingo/node'

const client = new PolyLingo(process.env.POLYLINGO_API_KEY)

const result = await client.translate({
  content: 'Free shipping on orders over $50.',
  targets: ['es', 'es-MX', 'es-ES', 'pt', 'pt-BR', 'pt-PT'],
})

console.log(result.translations['es-MX']) // Мексиканский испанский
console.log(result.translations['pt-BR']) // Бразильский португальский

Один запрос охватывает как латиноамериканский, так и иберийский рынки. Без циклов и группировки по регионам.

Перевод JSON-файлов по рынкам на Python

import os, requests

client = requests.Session()
client.headers['Authorization'] = f"Bearer {os.environ['POLYLINGO_API_KEY']}"

markets = {
    'latam':  ['es-MX', 'pt-BR'],
    'europe': ['en-GB', 'fr', 'es-ES', 'pt-PT', 'de', 'it'],
    'asia':   ['zh-HK', 'zh-TW', 'zh', 'ja', 'ko'],
}

content = '{"cta": "Start your free trial"}'

for region, targets in markets.items():
    r = client.post(
        'https://api.usepolylingo.com/v1/translate',
        json={'content': content, 'format': 'json', 'targets': targets},
        timeout=120,
    )
    r.raise_for_status()
    print(f"\n{region.upper()}")
    for code, text in r.json()['translations'].items():
        print(f"  {code}: {text}")

Получение поддерживаемых кодов во время выполнения

Если вы создаёте выбор языка или динамический список целей, вам не нужно ничего жестко кодировать. GET /languages возвращает полный список, включая все региональные варианты. Отфильтруйте коды, содержащие дефис, чтобы получить именно диалекты:

const res = await fetch('https://api.usepolylingo.com/v1/languages')
const { languages } = await res.json()

const dialects = languages.filter(l => l.code.includes('-'))
console.log(dialects)
// [
//   { code: 'en-GB', name: 'English (UK)',           rtl: false },
//   { code: 'fr-CA', name: 'French (Canada)',         rtl: false },
//   { code: 'es-ES', name: 'Spanish (Spain)',         rtl: false },
//   { code: 'es-MX', name: 'Spanish (Mexico)',        rtl: false },
//   { code: 'pt-PT', name: 'Portuguese (Portugal)',   rtl: false },
//   { code: 'pt-BR', name: 'Portuguese (Brazil)',     rtl: false },
//   { code: 'zh-TW', name: 'Chinese (Traditional)',  rtl: false },
//   { code: 'zh-HK', name: 'Chinese (Hong Kong)',     rtl: false },
// ]

Когда использовать общий и когда региональный код

Используйте общий код (pt, fr, es), когда ваша аудитория географически смешанная или неизвестна, когда вы только начинаете работать на рынке и хотите широкого охвата, или когда контент достаточно технический, и региональные различия вряд ли будут важны.

Используйте региональный код (pt-BR, fr-CA, es-MX), когда вы ориентируетесь на конкретную страну, когда опыт продукта локализован иными способами (цены, валюта, форматы дат), когда ваш контент разговорный или маркетинговый и важен стиль, или когда вы знаете, что пользователи заметят разницу.

Оба подхода могут сосуществовать в одном запросе. Распространённый шаблон — использовать общий код как запасной вариант и региональный код для опыта конкретного рынка, оба возвращаются в одном ответе.

Для существующих пользователей ничего не меняется

Все существующие языковые коды продолжают работать точно так же, как раньше. Новые коды добавляются. Если вы сейчас передаёте fr, вы продолжите получать тот же результат. Если хотите именно канадский французский, добавьте fr-CA в ваши цели. Они могут сосуществовать в одном вызове без конфликтов.

Получите ваш API-ключ на usepolylingo.com — бесплатный тариф включает 50 000 токенов в месяц.