웹 서비스나 글로벌 애플리케이션을 개발하면서 기존 번역 서비스보다 훨씬 자연스럽고 정확한 번역 결과물이 필요했던 적이 있으신가요?
다만 DeepL API를 실무 PHP 환경에 어떻게 안전하게 연동하고 최적의 HTTP 요청을 보내야 하는지 모르는 경우가 많습니다.
이번에는 DeepL API v2가 정확히 무엇이고 왜 필요한지, 그리고 PHP cURL을 이용해 다국어 텍스트 번역을 처리하는 방법을 완벽하게 정리해서 소개하겠습니다.

DeepL은 인공신경망 기반의 고성능 AI 번역 엔진으로, 문장의 맥락과 어조를 기존 번역기 대비 한층 매끄럽게 파악하는 것으로 잘 알려져 있습니다.
글로벌 서비스 개발 시 단순 단어 직역이 아닌 완성도 높은 다국어 지원을 구현할 때 필수로 검토되는 API입니다.

DeepL API는 계정 유형에 따라 **Free 플랜**과 **Pro 플랜**으로 나뉘며, 연동 시 호스트 도메인(Endpoint)이 서로 완전히 다르므로 주의해야 합니다.

DeepL 연동을 위해서는 먼저 공식 웹사이트 개발자 익스플로러에서 회원가입 후 계정을 생성해야 합니다.
Free 플랜의 경우에도 신용카드 등록이 필요하지만, 월 50만 자까지는 비용이 전혀 청구되지 않습니다.

계정 생성 후 [Account] -> [API Keys] 메뉴에 들어가면 다음과 같은 형태의 인증 키를 확인할 수 있습니다.

• Free 계정 키 형태 예시: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:fx (끝에 :fx가 붙음)
• Pro 계정 키 형태 예시: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

인증 키 접미사에 :fx가 붙어있다면 반드시 API 요청 시 api-free.deepl.com 주소를 사용해야 에러가 발생하지 않습니다.

DeepL API v2의 /v2/translate 엔드포인트를 호출하여 한국어 텍스트를 영어(EN-US)로 번역하는 클래스 형태의 예제 코드입니다.

<?php
class DeepLTranslator {
    private string $apiKey;
    private string $baseUrl;

    public function __construct(string $apiKey, bool $isFreePlan = true) {
        $this->apiKey = $apiKey;
        // 플랜 유형에 따른 엔드포인트 분기
        $this->baseUrl = $isFreePlan 
            ? 'https://api-free.deepl.com/v2' 
            : 'https://api.deepl.com/v2';
    }

    public function translate(string $text, string $targetLang, string $sourceLang = ''): ?array {
        $url = $this->baseUrl . '/translate';

        $payload = [
            'text' => [$text],
            'target_lang' => strtoupper($targetLang),
        ];

        if (!empty($sourceLang)) {
            $payload['source_lang'] = strtoupper($sourceLang);
        }

        $headers = [
            'Authorization: DeepL-Auth-Key ' . $this->apiKey,
            'Content-Type: application/json'
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 10);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $error = curl_error($ch);
        curl_close($ch);

        if ($error) {
            throw new Exception("cURL 오류: " . $error);
        }

        if ($httpCode !== 200) {
            throw new Exception("DeepL API 오류 [HTTP {$httpCode}]: " . $response);
        }

        return json_decode($response, true);
    }
}

// 사용 예시
try {
    $apiKey = "YOUR_DEEPL_API_KEY_HERE"; // 발급받은 API 키 입력
    $translator = new DeepLTranslator($apiKey, true);

    $result = $translator->translate("안녕하세요. 오늘 시스템 점검이 진행될 예정입니다.", "EN-US");
    
    echo "번역 결과: " . $result['translations'][0]['text'];
} catch (Exception $e) {
    echo "에러 발생: " . $e->getMessage();
}
?>

위 코드를 실행하면 DeepL API 서버가 JSON 응답을 반환하며, translations 배열 객체 안에서 번역된 텍스트 데이터를 추출할 수 있습니다.

대부분의 개발자들이 DeepL API 연동 중 발생하는 오류는 URL 엔드포인트 오지정 또는 잘못된 HTTP 전송 방식에서 비롯됩니다.

✗ 잘못된 코드 (GET 요청 + URL에 인증 키 노출 + 엔드포인트 미치치):

// 403 Forbidden 또는 404 Not Found 에러 발생 원인
$apiKey = "12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx:fx";
// Free 키를 사용하면서 Pro 엔드포인트를 호출한 경우
$url = "https://api.deepl.com/v2/translate?auth_key=" . $apiKey . "&text=안녕&target_lang=EN";
$response = file_get_contents($url);

✓ 올바른 코드 (POST JSON + Authorization 헤더 + 정합 엔드포인트):

// API 키 종류(:fx 유무)에 상응하는 api-free.deepl.com 엔드포인트 지정
$url = "https://api-free.deepl.com/v2/translate";
$headers = [
    "Authorization: DeepL-Auth-Key " . $apiKey,
    "Content-Type: application/json"
];
// cURL을 통한 POST 전송 처리

출력/결과 예시:

{
  "translations": [
    {
      "detected_source_language": "KO",
      "text": "Hello. System maintenance is scheduled for today."
    }
  ]
}

DeepL API 연동은 서비스의 글로벌 확장과 고품질 다국어 처리를 위한 핵심 요소다. 정확한 엔드포인트 구분과 안전한 인증 헤더 적용이라는 작은 최적화가 모여서 안정적이고 완성도 높은 다국어 서비스를 만든다는 점을 잊지 말자. 이 글의 실전 cURL 예제 코드를 참고해 바로 프로젝트에 적용하면, 손쉽게 뛰어난 품질의 자동 번역 시스템을 구축할 수 있을 것이다.