PolyLingo now supports regional language codes: fr-CA, pt-BR, es-MX and more

You can now pass regional dialect codes directly as translation targets in PolyLingo. fr-CA, pt-BR, es-MX, en-GB, and several others are now valid values in your targets array, alongside or instead of their generic counterparts.

Nothing changes in how you call the API. The same endpoint, the same request shape. You just have more valid codes to choose from.

What was added

Seven new regional codes following the BCP-47 standard:

Code	Language
`en-GB`	English (UK)
`fr-CA`	French (Canada)
`es-ES`	Spanish (Spain)
`es-MX`	Spanish (Mexico)
`pt-PT`	Portuguese (Portugal)
`pt-BR`	Portuguese (Brazil)
`zh-HK`	Chinese (Hong Kong)

These sit alongside the existing zh-TW (Chinese Traditional), which was already using the same BCP-47 convention. The target cap has also been raised from 36 to 50 to accommodate teams hitting multiple regional variants in a single call.

Why regional codes matter

Generic language codes (fr, pt, es) are fine when your audience is broad or mixed. But when you are shipping a product to a specific country, generic is often not good enough.

Brazilian Portuguese and European Portuguese differ in vocabulary, spelling, and register in ways that matter to native speakers. Mexican Spanish and Castilian Spanish are similar enough that a generic translation reads as foreign to neither but perfectly natural to neither either. Canadian French has its own conventions that differ from Parisian French in ways that are immediately obvious to a Quebecer.

If you are selling to a specific market, that market deserves a translation written for them. Regional codes make that possible without needing a separate API call or a separate workflow.

Same call, multiple variants

Generic and regional codes can coexist in the same request. Each gets its own key in the response:

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

You get four keys back, one per code. If fr and fr-CA produce the same output for a given string, that is expected — they will diverge on vocabulary and register where the difference is meaningful.

Targeting a specific market only

If you are building for a known market and have no use for the generic variant, just pass the regional code:

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

Building a market-specific target list in 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']) // Mexican Spanish
console.log(result.translations['pt-BR']) // Brazilian Portuguese

One request covers both Latin American and Iberian markets. No loops, no batching by region.

Translating JSON files per market 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": "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}")

Discovering supported codes at runtime

If you are building a language picker or a dynamic target list, you do not need to hardcode anything. GET /languages returns the full list including all regional variants. Filter by codes that contain a hyphen to get dialects specifically:

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

When to use generic vs regional

Use the generic code (pt, fr, es) when your audience is geographically mixed or unknown, when you are just getting started with a market and want broad coverage, or when the content is technical enough that regional differences are unlikely to matter.

Use the regional code (pt-BR, fr-CA, es-MX) when you are shipping to a specific country, when the product experience is localised in other ways (pricing, currency, date formats), when your content is conversational or marketing-led and register matters, or when you know your users will notice the difference.

The two approaches can coexist in the same request. A common pattern is to use the generic code as a fallback and the regional code for a specific market's experience, both returned in one response.

Nothing breaks for existing users

All existing language codes continue to work exactly as before. The new codes are additive. If you are currently passing fr you will keep getting the same output. If you want Canadian French specifically, add fr-CA to your targets. The two can coexist in the same call with no conflicts.

Get your API key at usepolylingo.com — the free tier includes 50,000 tokens per month.