← 블로그로 돌아가기
Four regional language code badges — fr-CA, pt-BR, es-MX, en-GB — connecting to a single API endpoint.

PolyLingo가 이제 지역 언어 코드(fr-CA, pt-BR, es-MX 등)를 지원합니다

By Robert M

PolyLingo가 지역 언어 코드 지원 시작: fr-CA, pt-BR, es-MX 등

이제 PolyLingo에서 지역 방언 코드를 번역 대상(targets)으로 직접 지정할 수 있습니다. fr-CA, pt-BR, es-MX, en-GB 등 여러 코드가 기존의 일반 코드와 함께 또는 대신에 targets 배열에서 유효한 값으로 사용 가능합니다.

API 호출 방식은 변하지 않습니다. 동일한 엔드포인트, 동일한 요청 형식입니다. 단지 선택할 수 있는 유효 코드가 더 많아졌을 뿐입니다.

추가된 내용

BCP-47 표준을 따른 7개의 새로운 지역 코드:

코드언어
en-GB영어 (영국)
fr-CA프랑스어 (캐나다)
es-ES스페인어 (스페인)
es-MX스페인어 (멕시코)
pt-PT포르투갈어 (포르투갈)
pt-BR포르투갈어 (브라질)
zh-HK중국어 (홍콩)

이들은 기존의 zh-TW (중국어 번체)와 함께 존재하며, 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": "주문이 확인되었습니다.",
    "targets": ["fr", "fr-CA", "pt", "pt-BR"]
  }'

{
  "translations": {
    "fr":    "Votre commande a été confirmée.",
    "fr-CA": "Votre commande a été confirmée.",
    "pt":    "주문이 확인되었습니다.",
    "pt-BR": "주문이 확인되었습니다."
  }
}

코드별로 4개의 키가 반환됩니다. 특정 문자열에 대해 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": "계정에 로그인하세요.",
    "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: '$50 이상 주문 시 무료 배송.',
  targets: ['es', 'es-MX', 'es-ES', 'pt', 'pt-BR', 'pt-PT'],
})
 
console.log(result.translations['es-MX']) // 멕시코 스페인어
console.log(result.translations['pt-BR']) // 브라질 포르투갈어

한 번의 요청으로 라틴 아메리카와 이베리아 시장을 모두 커버합니다. 루프나 지역별 배치 처리 불필요.

Python으로 시장별 JSON 파일 번역하기

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": "무료 체험 시작하기"}'
 
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: '영어 (영국)',           rtl: false },
//   { code: 'fr-CA', name: '프랑스어 (캐나다)',         rtl: false },
//   { code: 'es-ES', name: '스페인어 (스페인)',         rtl: false },
//   { code: 'es-MX', name: '스페인어 (멕시코)',        rtl: false },
//   { code: 'pt-PT', name: '포르투갈어 (포르투갈)',   rtl: false },
//   { code: 'pt-BR', name: '포르투갈어 (브라질)',     rtl: false },
//   { code: 'zh-TW', name: '중국어 (번체)',  rtl: false },
//   { code: 'zh-HK', name: '중국어 (홍콩)',     rtl: false },
// ]

일반 코드와 지역 코드 사용 시기

일반 코드를 사용하세요 (pt, fr, es) 대상이 지리적으로 혼합되어 있거나 알 수 없을 때, 시장 진입 초기로 광범위한 커버리지가 필요할 때, 또는 콘텐츠가 기술적이어서 지역 차이가 중요하지 않을 때.

지역 코드를 사용하세요 (pt-BR, fr-CA, es-MX) 특정 국가에 배포할 때, 제품 경험이 가격, 통화, 날짜 형식 등 다른 방식으로 현지화되어 있을 때, 콘텐츠가 대화체나 마케팅 중심이고 문체가 중요할 때, 또는 사용자가 차이를 인지할 때.

두 가지 접근법은 같은 요청 내에서 공존할 수 있습니다. 일반 코드를 폴백으로, 지역 코드를 특정 시장 경험용으로 사용하며, 둘 다 한 응답에 포함하는 것이 일반적입니다.

기존 사용자에게는 영향 없음

기존 언어 코드는 모두 이전과 동일하게 작동합니다. 새 코드는 추가된 것입니다. 현재 fr을 사용 중이라면 같은 결과를 계속 받습니다. 캐나다 프랑스어가 필요하면 fr-CA를 타겟에 추가하세요. 둘 다 같은 호출에서 충돌 없이 공존할 수 있습니다.

usepolylingo.com에서 API 키 받기 — 무료 플랜은 월 50,000 토큰을 포함합니다.