PolyLingo agora suporta códigos de idiomas regionais: fr-CA, pt-BR, es-MX e mais

Você agora pode passar códigos de dialetos regionais diretamente como alvos de tradução no PolyLingo. fr-CA, pt-BR, es-MX, en-GB e vários outros são agora valores válidos no seu array targets, junto com ou em vez de seus equivalentes genéricos.

Nada muda na forma como você chama a API. O mesmo endpoint, o mesmo formato de requisição. Você apenas tem mais códigos válidos para escolher.

O que foi adicionado

Sete novos códigos regionais seguindo o padrão BCP-47:

Código	Idioma
`en-GB`	Inglês (Reino Unido)
`fr-CA`	Francês (Canadá)
`es-ES`	Espanhol (Espanha)
`es-MX`	Espanhol (México)
`pt-PT`	Português (Portugal)
`pt-BR`	Português (Brasil)
`zh-HK`	Chinês (Hong Kong)

Eles ficam ao lado do existente zh-TW (Chinês Tradicional), que já usava a mesma convenção BCP-47. O limite de alvos também foi aumentado de 36 para 50 para acomodar equipes que precisam de múltiplas variantes regionais em uma única chamada.

Por que os códigos regionais importam

Códigos genéricos de idioma (fr, pt, es) são adequados quando seu público é amplo ou misto. Mas quando você está lançando um produto para um país específico, o genérico muitas vezes não é suficiente.

O português brasileiro e o português europeu diferem em vocabulário, ortografia e registro de formas que importam para falantes nativos. O espanhol mexicano e o espanhol castelhano são semelhantes o suficiente para que uma tradução genérica não soe estrangeira nem perfeitamente natural para nenhum dos dois. O francês canadense tem suas próprias convenções que diferem do francês parisiense de maneiras imediatamente óbvias para um quebequense.

Se você está vendendo para um mercado específico, esse mercado merece uma tradução feita para ele. Códigos regionais tornam isso possível sem precisar de uma chamada API separada ou um fluxo de trabalho diferente.

Mesma chamada, múltiplas variantes

Códigos genéricos e regionais podem coexistir na mesma requisição. Cada um recebe sua própria chave na resposta:

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."
  }
}

Você recebe quatro chaves de volta, uma por código. Se fr e fr-CA produzirem a mesma saída para uma dada string, isso é esperado — eles divergem em vocabulário e registro onde a diferença é significativa.

Direcionando para um mercado específico apenas

Se você está construindo para um mercado conhecido e não precisa da variante genérica, basta passar o código regional:

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"]
  }'

Construindo uma lista de alvos específica de mercado em 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']) // Espanhol Mexicano
console.log(result.translations['pt-BR']) // Português Brasileiro

Uma requisição cobre tanto os mercados da América Latina quanto da Península Ibérica. Sem loops, sem agrupamento por região.

Traduzindo arquivos JSON por mercado em 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}")

Descobrindo códigos suportados em tempo de execução

Se você está construindo um seletor de idioma ou uma lista dinâmica de alvos, não precisa codificar nada manualmente. GET /languages retorna a lista completa incluindo todas as variantes regionais. Filtre por códigos que contenham um hífen para obter dialetos especificamente:

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 },
// ]

Quando usar genérico vs regional

Use o código genérico (pt, fr, es) quando seu público for geograficamente misto ou desconhecido, quando você está começando em um mercado e quer cobertura ampla, ou quando o conteúdo for técnico o suficiente para que diferenças regionais provavelmente não importem.

Use o código regional (pt-BR, fr-CA, es-MX) quando estiver lançando para um país específico, quando a experiência do produto for localizada de outras formas (preços, moeda, formatos de data), quando seu conteúdo for conversacional ou voltado para marketing e o registro importar, ou quando souber que seus usuários notarão a diferença.

As duas abordagens podem coexistir na mesma requisição. Um padrão comum é usar o código genérico como fallback e o código regional para a experiência de um mercado específico, ambos retornados em uma única resposta.

Nada muda para usuários existentes

Todos os códigos de idioma existentes continuam funcionando exatamente como antes. Os novos códigos são aditivos. Se você está passando fr atualmente, continuará recebendo a mesma saída. Se quiser francês canadense especificamente, adicione fr-CA aos seus alvos. Os dois podem coexistir na mesma chamada sem conflitos.

Obtenha sua chave API em usepolylingo.com — o plano gratuito inclui 50.000 tokens por mês.