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

PolyLingo hiện hỗ trợ mã ngôn ngữ khu vực: fr-CA, pt-BR, es-MX và nhiều hơn nữa

By Robert M

PolyLingo hiện hỗ trợ mã ngôn ngữ vùng miền: fr-CA, pt-BR, es-MX và nhiều hơn nữa

Bạn giờ đây có thể truyền mã phương ngữ vùng miền trực tiếp làm mục tiêu dịch trong PolyLingo. fr-CA, pt-BR, es-MX, en-GB và một số mã khác giờ đây là giá trị hợp lệ trong mảng targets của bạn, cùng với hoặc thay thế cho các mã chung.

Cách bạn gọi API không thay đổi. Cùng một điểm cuối, cùng một định dạng yêu cầu. Bạn chỉ có thêm nhiều mã hợp lệ để lựa chọn.

Những gì đã được thêm vào

Bảy mã vùng miền mới theo tiêu chuẩn BCP-47:

MãNgôn ngữ
en-GBTiếng Anh (Anh)
fr-CATiếng Pháp (Canada)
es-ESTiếng Tây Ban Nha (Tây Ban Nha)
es-MXTiếng Tây Ban Nha (Mexico)
pt-PTTiếng Bồ Đào Nha (Bồ Đào Nha)
pt-BRTiếng Bồ Đào Nha (Brazil)
zh-HKTiếng Trung (Hồng Kông)

Chúng nằm bên cạnh mã zh-TW (Trung Quốc truyền thống) hiện có, vốn đã sử dụng cùng quy ước BCP-47. Giới hạn mục tiêu cũng được nâng từ 36 lên 50 để đáp ứng các nhóm cần nhiều biến thể vùng miền trong một lần gọi.

Tại sao mã vùng miền lại quan trọng

Mã ngôn ngữ chung (fr, pt, es) phù hợp khi khán giả của bạn rộng hoặc hỗn hợp. Nhưng khi bạn phát hành sản phẩm đến một quốc gia cụ thể, mã chung thường không đủ.

Tiếng Bồ Đào Nha Brazil và Bồ Đào Nha châu Âu khác nhau về từ vựng, chính tả và cách dùng mà người bản ngữ quan tâm. Tiếng Tây Ban Nha Mexico và Tây Ban Nha Castilian đủ giống nhau để bản dịch chung không nghe như ngoại quốc với ai, nhưng cũng không hoàn toàn tự nhiên với ai. Tiếng Pháp Canada có quy ước riêng khác với tiếng Pháp Paris mà người Quebec nhận ra ngay lập tức.

Nếu bạn bán cho một thị trường cụ thể, thị trường đó xứng đáng có bản dịch viết riêng cho họ. Mã vùng miền làm điều đó trở nên khả thi mà không cần gọi API riêng hoặc quy trình làm việc riêng.

Gọi một lần, nhiều biến thể

Mã chung và mã vùng miền có thể cùng tồn tại trong một yêu cầu. Mỗi mã có một khóa riêng trong phản hồi:

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

Bạn nhận được bốn khóa trả về, mỗi khóa cho một mã. Nếu fr và fr-CA cho cùng một kết quả với một chuỗi, điều đó là bình thường — chúng sẽ khác nhau về từ vựng và cách dùng khi sự khác biệt có ý nghĩa.

Chỉ nhắm mục tiêu một thị trường cụ thể

Nếu bạn xây dựng cho một thị trường đã biết và không cần biến thể chung, chỉ cần truyền mã vùng miền:

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

Xây dựng danh sách mục tiêu theo thị trường trong 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']) // Tiếng Tây Ban Nha Mexico
console.log(result.translations['pt-BR']) // Tiếng Bồ Đào Nha Brazil

Một yêu cầu bao phủ cả thị trường Mỹ Latinh và Iberia. Không cần vòng lặp, không cần nhóm theo vùng.

Dịch file JSON theo thị trường trong 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}")

Khám phá các mã được hỗ trợ khi chạy

Nếu bạn xây dựng bộ chọn ngôn ngữ hoặc danh sách mục tiêu động, bạn không cần mã hóa cứng gì cả. GET /languages trả về danh sách đầy đủ bao gồm tất cả các biến thể vùng miền. Lọc theo mã có dấu gạch ngang để lấy riêng các phương ngữ:

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

Khi nào dùng mã chung và khi nào dùng mã vùng miền

Dùng mã chung (pt, fr, es) khi khán giả của bạn phân bố địa lý rộng hoặc không rõ, khi bạn mới bắt đầu với một thị trường và muốn bao phủ rộng, hoặc khi nội dung mang tính kỹ thuật và sự khác biệt vùng miền không quan trọng.

Dùng mã vùng miền (pt-BR, fr-CA, es-MX) khi bạn phát hành cho một quốc gia cụ thể, khi trải nghiệm sản phẩm được địa phương hóa theo cách khác (giá cả, tiền tệ, định dạng ngày tháng), khi nội dung của bạn mang tính hội thoại hoặc marketing và cách dùng ngôn ngữ quan trọng, hoặc khi bạn biết người dùng sẽ nhận ra sự khác biệt.

Hai cách tiếp cận có thể cùng tồn tại trong một yêu cầu. Mẫu phổ biến là dùng mã chung làm dự phòng và mã vùng miền cho trải nghiệm thị trường cụ thể, cả hai được trả về trong một phản hồi.

Không có gì bị hỏng cho người dùng hiện tại

Tất cả mã ngôn ngữ hiện có vẫn hoạt động như trước. Mã mới là bổ sung thêm. Nếu bạn đang truyền fr, bạn sẽ tiếp tục nhận được cùng một kết quả. Nếu bạn muốn tiếng Pháp Canada cụ thể, hãy thêm fr-CA vào mục tiêu. Hai mã có thể cùng tồn tại trong một lần gọi mà không gây xung đột.

Nhận khóa API của bạn tại usepolylingo.com — gói miễn phí bao gồm 50.000 token mỗi tháng.