← Torna al blog
Four regional language code badges — fr-CA, pt-BR, es-MX, en-GB — connecting to a single API endpoint.

PolyLingo ora supporta i codici delle lingue regionali: fr-CA, pt-BR, es-MX e altro

By Robert M

PolyLingo ora supporta ora i codici linguistici regionali: fr-CA, pt-BR, es-MX e altri

Ora puoi passare direttamente i codici di dialetto regionale come destinazioni di traduzione in PolyLingo. fr-CA, pt-BR, es-MX, en-GB e altri sono ora valori validi nel tuo array targets, accanto o al posto delle loro controparti generiche.

Non cambia nulla nel modo in cui chiami l'API. Lo stesso endpoint, la stessa forma di richiesta. Hai solo più codici validi tra cui scegliere.

Cosa è stato aggiunto

Sette nuovi codici regionali secondo lo standard BCP-47:

CodiceLingua
en-GBInglese (UK)
fr-CAFrancese (Canada)
es-ESSpagnolo (Spagna)
es-MXSpagnolo (Messico)
pt-PTPortoghese (Portogallo)
pt-BRPortoghese (Brasile)
zh-HKCinese (Hong Kong)

Questi si affiancano all'esistente zh-TW (Cinese Tradizionale), che già utilizzava la stessa convenzione BCP-47. Il limite di destinazioni è stato aumentato da 36 a 50 per accogliere team che usano più varianti regionali in una singola chiamata.

Perché i codici regionali sono importanti

I codici linguistici generici (fr, pt, es) vanno bene quando il tuo pubblico è ampio o misto. Ma quando distribuisci un prodotto in un paese specifico, il generico spesso non basta.

Il portoghese brasiliano e quello europeo differiscono nel vocabolario, ortografia e registro in modi che contano per i madrelingua. Lo spagnolo messicano e quello castigliano sono abbastanza simili che una traduzione generica non suona straniera né per l'uno né per l'altro, ma neanche perfettamente naturale. Il francese canadese ha le sue convenzioni che differiscono dal francese parigino in modi immediatamente evidenti a un abitante del Quebec.

Se vendi in un mercato specifico, quel mercato merita una traduzione scritta per loro. I codici regionali lo rendono possibile senza bisogno di una chiamata API separata o di un flusso di lavoro separato.

Stessa chiamata, più varianti

I codici generici e regionali possono coesistere nella stessa richiesta. Ognuno ha la sua chiave nella risposta:

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Il tuo ordine è stato confermato.",
    "targets": ["fr", "fr-CA", "pt", "pt-BR"]
  }'

{
  "translations": {
    "fr":    "Votre commande a été confirmée.",
    "fr-CA": "Votre commande a été confirmée.",
    "pt":    "Il tuo ordine è stato confermato.",
    "pt-BR": "Il tuo ordine è stato confermato."
  }
}

Ricevi quattro chiavi, una per codice. Se fr e fr-CA producono lo stesso output per una data stringa, è previsto — divergeranno nel vocabolario e nel registro dove la differenza è significativa.

Mirare a un mercato specifico soltanto

Se stai costruendo per un mercato noto e non ti serve la variante generica, passa semplicemente il codice regionale:

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

Costruire una lista di target specifici per mercato in Node.js

import { PolyLingo } from '@polylingo/node'
 
const client = new PolyLingo(process.env.POLYLINGO_API_KEY)
 
const result = await client.translate({
  content: 'Spedizione gratuita per ordini superiori a $50.',
  targets: ['es', 'es-MX', 'es-ES', 'pt', 'pt-BR', 'pt-PT'],
})
 
console.log(result.translations['es-MX']) // Spagnolo messicano
console.log(result.translations['pt-BR']) // Portoghese brasiliano

Una richiesta copre sia i mercati latinoamericani che iberici. Niente loop, niente batching per regione.

Tradurre file JSON per mercato in 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": "Inizia la tua prova gratuita"}'
 
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}")

Scoprire i codici supportati a runtime

Se stai costruendo un selettore di lingua o una lista di target dinamica, non devi hardcodare nulla. GET /languages restituisce la lista completa inclusi tutti i varianti regionali. Filtra per codici che contengono un trattino per ottenere i dialetti specificamente:

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: 'Inglese (UK)',           rtl: false },
//   { code: 'fr-CA', name: 'Francese (Canada)',         rtl: false },
//   { code: 'es-ES', name: 'Spagnolo (Spagna)',         rtl: false },
//   { code: 'es-MX', name: 'Spagnolo (Messico)',        rtl: false },
//   { code: 'pt-PT', name: 'Portoghese (Portogallo)',   rtl: false },
//   { code: 'pt-BR', name: 'Portoghese (Brasile)',     rtl: false },
//   { code: 'zh-TW', name: 'Cinese (Tradizionale)',  rtl: false },
//   { code: 'zh-HK', name: 'Cinese (Hong Kong)',     rtl: false },
// ]

Quando usare generico vs regionale

Usa il codice generico (pt, fr, es) quando il tuo pubblico è geograficamente misto o sconosciuto, quando stai iniziando con un mercato e vuoi una copertura ampia, o quando il contenuto è abbastanza tecnico da rendere improbabili differenze regionali.

Usa il codice regionale (pt-BR, fr-CA, es-MX) quando distribuisci in un paese specifico, quando l'esperienza del prodotto è localizzata in altri modi (prezzi, valuta, formati di data), quando il tuo contenuto è conversazionale o di marketing e il registro conta, o quando sai che i tuoi utenti noteranno la differenza.

I due approcci possono coesistere nella stessa richiesta. Un modello comune è usare il codice generico come fallback e il codice regionale per l'esperienza di un mercato specifico, entrambi restituiti in una risposta.

Nulla cambia per gli utenti esistenti

Tutti i codici linguistici esistenti continuano a funzionare esattamente come prima. I nuovi codici sono aggiuntivi. Se stai passando fr continuerai a ricevere lo stesso output. Se vuoi il francese canadese specificamente, aggiungi fr-CA ai tuoi target. I due possono coesistere nella stessa chiamata senza conflitti.

Prendi la tua chiave API su usepolylingo.com — il piano gratuito include 50.000 token al mese.

PolyLingo ora supporta i codici delle lingue regionali: fr-CA, pt-BR, es-MX e altro | PolyLingo