REST 사용하기

이 문서는 구글 번역 API v2를 RESTful 방식을 사용했을 때의 일반적인 특성을 서술하였습니다.

소개

이 문서는 구글 번역 API를 사용하여 어플리케이션을 만들고자 하는 개발자에게 맞춰져 있습니다. 구글 번역은 웹페이지나 앱 내의 텍스트를 번역해 줍니다.

만약 구글 번역 컨셉에 익숙하지 않다면 구글 번역 API 시작하기를 먼저 봐주세요.

번역 API에 대한 요청 결과는 심플 JSON 객체입니다.

어플리케이션을 구글에게 식별하는 방법

아직 식별 작업을 완료하지 않았다면 다음 스텝을 따라 여러분 프로젝트의 API를 생성하세요.

  1. Credentials 페이지를 엽니다.
  2. 번역 API는 크리덴셜에 관한 두 가지 타입을 지원합니다. 여러분의 프로젝트에 적합한 것으로 생성하세요.
    • OAuth: 프라이빗 유저 데이터에 접근하기 위한 요청을 하려면 반드시 어플리케이션에서 OAuth 2.0 토큰을 보내야 합니다. 여러분의 어플리케이션은 클라이언트 ID와 (가능하다면) 토큰을 얻기 위한 ‘client secret’을 보내야 합니다. 여러분은 웹어플리케이션, 서비스 계정 또는 앱에서 쓰이는 OAuth 2.0 크리덴셜을 생성할 수 있습니다.OAuth 2.0 토큰을 만드려면, [사용자 인증 정보 만들기] 드롭다운 메뉴를 누른 후 [OAuth 클라이언트 ID]를 클릭합니다.

      주의: 이 API부터 OAuth 2.0 인증을 필요로 하는 어떠한 메서드도 가지고 있지 않습니다. 여러분은 오직 다음 목록에서 설명하고 있는 API 키만 얻으면 됩니다. 그러나 만약 여러분의 어플리케이션이 사용자 인증을 필요로 하는 다른 API를 호출한다면 여전히 OAuth 2.0 크리덴셜은 필요합니다. OAuth 2.0 문서는 여러분의 크리덴셜을 API 요청을 인증하기 위해 어떻게 사용하는지 설명하고 있습니다.

      인스톨되는 어플리케이션

      인스톨되는 어플리케이션이란 PC나 소형 디바이스에서 실행되는 어플리케이션을 말합니다. 안드로이드, 크롬, iOS와 기타 등등에서 동작하는 앱을 위해 OAuth 2.0 크리덴셜을 생성할 수 있습니다.

      Android

      원문을 참조하세요.

      크롬 어플리케이션

      크롬 앱 또는 크롬 확장프로그램을 위해 특정한 어플리케이션 ID가 필요합니다. ID를 얻으려면 Google Chrome Identity API 페이지를 참조하세요.

      iOS

      원문을 참조하세요.

      Other

      원문을 참조하세요.

    • Public API access: OAuth 2.0 토큰을 제공하지 않는 요청은 반드시 API 키를 보내야 합니다. 키가 여러분의 프로젝트를 식별하고 API 접근, API 콜 수, 리포트를 제공합니다.
      API는 몇 가지 타입을 지원합니다. 만약 필요로 하는 키 타입이 존재하지 않는다면, Create New Key를 선택해 API 키를 생성하고 적당한 키 타입을 선택합니다. 키 타입에 맞는 추가 정보를 입력하고 [Create]를 클릭합니다.

      Server keys

      원문을 참조하세요.

      Browser keys

      원문을 참조하세요.

      iOS keys

      원문을 참조하세요.

      Android keys

      원문을 참조하세요.

API 키의 보안유지는 Best practices for securely using API keys 문서를 참조하세요.한번 생성된 API키는 크리덴셜 페이지API keys 섹션에서 찾을 수 있습니다.
만약 여러분의 키가 제대로 동작하지 않는다면—예를 들어 여러분이 구글 콘솔의 트래픽 리포트를 통해 의심스러운 행위가 있다는 것을 알아차린 경우—구글은 [Generate new key] 버튼을 사용해 새 키를 생성할 것을 권장합니다. 이렇게 하면 두 키가 모두 활성화 되어 있는 동안  여러분은 최대 24시간내에 예전 키를 정지 시킬것인지에 대한 결정을 할 수 있습니다. 단계적인 비활성화를 하면 새 키가 배포되는 충분한 시간을 가질 수 있습니다. 그 대신에 만약 예전 키를 즉시 유효하지 않도록 만들고 싶으면 [Delete Key] 버튼을 클릭합니다.

Traslate Text

Working with results

URI를 통한 HTTP GET 요청으로 텍스트를 특정 언어로 번역할 수 있습니다. 요청 URI는 다음 포맷을 가집니다:

각각의 번역 request는 3가지 쿼리 파라미터를 필요로 합니다.

API key
파라미터 ‘key’는 여러분의 어플리케이션을 식별하는데 사용합니다.
Target language
파라미터 ‘target’은 번역하고 싶은 언어를 지정하기 위해 사용합니다.
Source text string
파라미터 ‘q’는 원문을 식별하기 위해 사용합니다.

다른 모든 쿼리 파라미터들은 옵션입니다. GET 방식을 사용하고 파라미터들을 포함했을 때 2000자를 넘지 않아야 합니다.

주의: 하나의 요청에 좀 더 많은 데이터를 보내고 싶다면 POST 방식으로 API를 호출할 수 있습니다. POST 바디의 ‘q’ 파라미터를 5000자 이하로 합니다. POST 방식을 사용하기 위해서는 번역 API가 마치 GET 요청처럼 다루도록 하기 위해 반드시 X-HTTP-Method-Override 헤더를 사용합니다. (사용방법 X-HTTP-Method-Override: GET)

쿼리에 파라미터 ‘source’를 사용해서 소스 언어를 지정하는 예제가 있습니다:

만약 요청이 성공하면 서버는 200 OK 라는 HTTP 상태 코드와 데이터 프로퍼티들을 내려줍니다:

JSON

이 예제에서 ‘translatedText’ 필드에 번역이 된 결과가 있습니다.

하나가 아닌 여러 소스 텍스트를 번역하는 다른 예제도 보겠습니다:

만약 요청이 성공하면 서버는 200 OK 라는 HTTP 상태 코드와 데이터 프로퍼티들을 내려줍니다:

JSON

‘translatedText’를 포함하는 ‘translations’ 객체가 있습니다. 각각은 사용자가 제공한 쿼리 순서대로 보입니다.

다음 예제는 소스 텍스트의 언어를 자동으로 감지하는 예제입니다:

만약 요청이 성공하면 서버는 200 OK 라는 HTTP 상태 코드와 데이터 프로퍼티들을 내려줍니다:

JSON

위의 예제처럼 ‘translatedText’를 포함하고 있는 ‘translations’는 배열입니다. ‘detectedSourceLanguage’는 아래 ‘Language reference’ 섹션에서 정의하고 있는 랭귀지 코드입니다. 주의할 것은 아래 목록에 없는 다른 랭귀지 코드가 리턴될 수도 있습니다. 그것들은 ‘iso639-1’에 있는 랭귀지 코드입니다.

Query parameter reference

번역 API에서 사용 가능한 쿼리 파라미터들이 아래 표에 정리되어 있습니다. 모든 파라미터 값은 URL로 인코딩 되어야 합니다.

파라미터부가설명
callback응답이 왔을 때 호출될 자바스크립트 콜백 함수
  • 이 옵션 파라미터는 쿼리 결과를 처리할 수 있는 자바스크립트 함수를 지정할 수 있도록 합니다. 순수 클라이언트-사이드를 구현할 때 사용합니다.
  • <script> 태그안에 API 쿼리를 넣으세요.
  • <script> 태그안에 콜백 함수를 정의하세요.
  • 시작하기 문서에 있는 REST from JavaScript 예제를 살펴보세요.
format형식
  • 이 옵션 파라미터는 텍스트를 플레인텍스트나 HTML로 번역되도록 지정합니다. 'html' 값은 HTML을, 'test' 값은 플레인텍스트를 지정합니다.
  • 기본값: format=html.
key여러분이 받은 API 키
  • 이 API는 모든 요청에 대한 유효한 키를 요구합니다.
  • 어플리케이션의 API 키를 찾으려면 Credentials page를 열어 확인합니다.
prettyprint들여쓰기와 라인 브레이크가 있는 응답을 리턴
  • 만약 prettyprint=true 이면, 사람이 읽기 편한 결과값이 서버에 의해 리턴됩니다.(pretty printed)
  • 기본값: prettyprint=true.
q소스 텍스트
  • 번역이 될 원문입니다.
  • 파라미터를 반복적으로 사용하여 한번의 요청으로 여러 문장을 번역할 수 있습니다.
source소스 언어
  • 원문이 작성된 언어입니다. Language 레퍼런스의 목록에 있는 코드 중 하나를 값으로 지정해야 합니다.
  • 만약 코드가 지정되지 않으면 시스템은 자동적으로 원문의 언어를 알아내기 위한 시도를 합니다.
target타겟 언어
  • 원문이 변환이 될 문장의 언어입니다. Language 레퍼런스의 목록에 있는 값 중 하나가 지정되어야 합니다.

Language reference

다음은 지원되는 언어와 그에 해당하는 코드의 일부 목록입니다:

언어코드
Afrikaans 아프리칸어af
Albanian 알바니아어sq
Arabic 아라비아어ar
Armenian 아르메니아어hy
Azerbaijani 아제르바이잔어az
Basque 바스크어eu
Belarusian 벨로루시어be
Bengali 벵골어bn
Bosnian 보스니아어bs
Bulgarian 불가리아어bg
Catalan 카탈로니아어ca
Cebuano 필리핀어(세부)ceb
Chichewa 치체와어ny
Chinese Simplified 중국어 간체zh-CN
Chinese Traditional 중국어 번체zh-TW
Croatian 크로아티아어hr
Czech 체코어cs
Danish 덴마크어da
Dutch 네덜란드어nl
English 영어en
Esperanto 에스페란토어eo
Estonian 에스토니아어et
Filipino 필리핀어tl
Finnish 핀란드어fi
French 프랑스어fr
Galician 갈라시아어gl
Georgian 그루지아어ka
German 독일어de
Greek 그리스어el
Gujarati 구자라트어gu
Haitian Creole 아이티어ht
Hausa 하우사어ha
Hebrew 히브리어iw
Hindi 힌디어hi
Hmong '몽'족의 언어hmn
Hungarian 헝가리어hu
Icelandic 아이슬란드어is
Igbo 이보어ig
Indonesian 인도네시아어id
Irish 아일랜드어ga
Italian 이탈리아어it
Japanese 일본어ja
Javanese 자바어jw
Kannada 카나라어kn
Kazakh 카자흐어kk
Khmer 크메르어km
Korean 한국어ko
Lao 라오어lo
Latin 라틴어la
Latvian 라트비아어lv
Lithuanian 리투아니아어lt
Macedonian 마케도니아어mk
Malagasy 마다가스카르어mg
Malay 말레이어ms
Malayalam 말라얄람어ml
Maltese 몰타어mt
Maori 마오리어mi
Marathi 마라티어mr
Mongolian 몽골어mn
Myanmar (Burmese) 버마어my
Nepali 네팔어ne
Norwegian 노르웨이어no
Persian 페르시아어fa
Polish 폴란드어pl
Portuguese 포르투갈어pt
Punjabi 펀자브어ma
Romanian 루마니아어ro
Russian 러시아어ru
Serbian 세르비아어sr
Sesotho 세소토어st
Sinhala 싱할라어si
Slovak 슬로바키아어sk
Slovenian 슬로베니아어sl
Somali 소말리어so
Spanish 스페인어es
Sudanese (수단)su
Swahili 스와힐리어sw
Swedish 스웨덴어sv
Tajik 타지크어tg
Tamil 타밀어ta
Telugu 텔루구어te
Thai 타이어th
Turkish 터키어tr
Ukrainian 우크라이나어uk
Urdu 우르두어ur
Uzbek 우즈베크어uz
Vietnamese 베트남어vi
Welsh 웨일스어cy
Yiddish 이디시어yi
Yoruba 요루바어yo
Zulu 줄루어zu

Discover Supported Languages

Working with results

HTTP GET 요청을 보내 지원되는 언어를 알 수 있습니다. 요청 URI의 포맷은 다음과 같습니다:

각 요청마다 하나의 쿼리 파라미터를 필요로 합니다.

API key
key 쿼리 파라미터는 어플리케이션을 식별하는데 사용합니다.

다른 모든 파라미터들은 옵션입니다.

번역 API에 의해 지원되는 언어 코드 목록을 받을 수 있는 예제입니다:

만약 요청이 성공하면 서버는 200 OK 라는 HTTP 상태 코드와 데이터 프로퍼티들을 응답값으로 줍니다.

JSON

이 쿼리는 번역을 위해 지원되는 언어의 iso639-1 코드를 반환합니다. zh-CN 또는 zh-TW 같은 일부 언어 코드는 또한 국가 코드를 포함하고 있습니다. 이 리스트는 언어 코드의 알파벳 순서로 정렬되어 있습니다.

타겟 언어가 주어진 상태에서 지원되는 언어 목록을 반환하는 다른 예제가 이있습니다. 반환된 리스트는 타겟 언어의 알파벳순으로 정렬되어 있습니다.

만약 요청이 성공하면 서버는 200 OK 라는 HTTP 상태 코드와 데이터 프로퍼티들을 응답값으로 줍니다.

JSON

이 경우 위와 같이 코드 언어가 동일하게 리턴되지만 각각의 언어를 타겟 언어로 적은 ‘name’ 이라는 스트링을 추가한다는 점이 다릅니다.

Query parameter reference

번역 API에서 사용 가능한 쿼리 파라미터들이 아래 표에 정리되어 있습니다. 모든 파라미터 값은 URL로 인코딩 되어야 합니다.

파라미터부가설명
callback응답이 왔을 때 호출될 자바스크립트 콜백 함수
  • 이 옵션 파라미터는 쿼리 결과를 처리할 수 있는 자바스크립트 함수를 지정할 수 있도록 합니다. 순수 클라이언트-사이드를 구현할 때 사용합니다.
  • <script> 태그안에 API 쿼리를 넣으세요.
  • <script> 태그안에 콜백 함수를 정의하세요.
  • 시작하기 문서에 있는 REST from JavaScript 예제를 살펴보세요.
key여러분이 받은 API 키
  • 이 API는 모든 요청에 대한 유효한 키를 요구합니다.
  • 어플리케이션의 API 키를 찾으려면 Credentials page를 열어 확인합니다.
prettyprint들여쓰기와 라인 브레이크가 있는 응답을 리턴
  • 만약 prettyprint=true 이면, 사람이 읽기 편한 결과값이 서버에 의해 리턴됩니다.(pretty printed)
  • 기본값: prettyprint=true.
target타겟 언어
  • 언어들을 특정 타겟언어로 변환하여 표기하고, 정렬순서는 표기된 타겟언어에 따릅니다.
  • 만약 언어가 지정되지 않으면, 시스템은 언어들을 타겟언어로 변환하지 않을 것이고, 정렬은 기존과 같이 언어코드를 기반으로 정렬될 것입니다.

Detect Language

Working with results

URI에 HTTP GET 요청을 보내 텍스트의 언어를 탐지할 수 있습니다. 요청 URI의 포맷은 다음과 같습니다:

각 요청마다 쿼리 파라미터는 2개가 필요합니다.

API key
파라미터 ‘key’는 여러분의 어플리케이션을 식별하는데 사용합니다.
Source text string
파라미터 ‘q’는 원문을 식별하기 위해 사용합니다.

다른 모든 쿼리 파라미터들은 옵션입니다. GET 방식을 사용하고 파라미터들을 포함했을 때 2000자를 넘지 않아야 합니다.

주의: 하나의 요청에 좀 더 많은 데이터를 보내고 싶다면 POST 방식으로 API를 호출할 수 있습니다. POST 바디의 ‘q’ 파라미터를 5000자 이하로 합니다. POST 방식을 사용하기 위해서는 번역 API가 마치 GET 요청처럼 다루도록 하기 위해 반드시 X-HTTP-Method-Override 헤더를 사용합니다. (사용방법 X-HTTP-Method-Override: GET)

‘q’ 쿼리 파라미터를 사용해 “Google Translate Rocks”라는 텍스트를 지정하는 예제가 아래 있습니다.

요청이 성공하면 서버는 HTTP 상태코드인 200 OK 와 데이터 프로퍼티들을 내려줍니다.

JSON

이 예제에서 ‘language’는 위의 예제에서 지정한 언어와 동일한 포맷의 언어코드입니다.

‘isReliable’은 DEPRECATED 되었습니다. 탐지(detection) 결과를 신뢰할 수 있는지에 대한 시그널을 우리가 받았을 때 리턴될 수 있는 옵션 파라미터였습니다. 실제론 이것이 그렇게 신뢰할 수 있는 파라미터가 아니었습니다. 그래서 우리는 곧 삭제할 계획에 있습니다.

‘confidence’는 0과 1사이의 부동소수점 값을 가지는 옵션 파라미터입니다. 1에 가까울수록 언어탐지에 대한 신뢰도가 높다고 할 수 있습니다. 이 파라미터가 항상 존재하는 것은 아니니 주의하세요.

다음 예제는 여러개의 소스 텍스트를 탐지하는 코드입니다.

요청이 성공하면 서버는 HTTP 상태코드인 200 OK 와 데이터 프로퍼티들을 내려줍니다.

JSON

‘language’와 ‘confidence’는 앞에 설명했던 것과 동일합니다. 단, 소스 텍스트가 여러개 포함되어 있기 때문에 ‘data’ 필드가 그만큼 반복됩니다.

‘isReliable’은 앞에 설명했던 것과 같이 동일한 이유로 DEPRECATED 되었습니다.

Query parameter reference

Detect Language API에서 사용할 수 있는 쿼리 파라미터를 표로 정리하였습니다. 모든 파라미터는 URL로 인코딩 되어야 합니다.

파라미터부가설명
callback응답이 왔을 때 호출될 자바스크립트 콜백 함수
  • 이 옵션 파라미터는 쿼리 결과를 처리할 수 있는 자바스크립트 함수를 지정할 수 있도록 합니다. 순수 클라이언트-사이드를 구현할 때 사용합니다.
  • <script> 태그안에 API 쿼리를 넣으세요.
  • <script> 태그안에 콜백 함수를 정의하세요.
  • 시작하기 문서에 있는 REST from JavaScript 예제를 살펴보세요.
key여러분이 받은 API 키
  • 이 API는 모든 요청에 대한 유효한 키를 요구합니다.
  • 어플리케이션의 API 키를 찾으려면 Credentials page를 열어 확인합니다.
prettyprint들여쓰기와 라인 브레이크가 있는 응답을 리턴
  • 만약 prettyprint=true 이면, 사람이 읽기 편한 결과값이 서버에 의해 리턴됩니다.(pretty printed)
  • 기본값: prettyprint=true.
q소스 텍스트
  • 탐지될 원문입니다.
  • 파라미터를 반복적으로 사용하여 한번의 요청으로 여러 문장을 번역할 수 있습니다.