\documentclass[10pt,a4paper]{article}
\usepackage{float, hyperref}

% Load code highlighter color scheme
\input{colors}

\title{Telematica assignment 2: Google Translate}
\author{Tadde\"us Kroes (6054129) \and Sander van Veen (6167969)}

\begin{document}

\maketitle

\section{Assignment} % {{{
\label{sec:Assignment}

The assignment is to create a command-line interface that uses the Google
Translate Webservice API to translate data entered by the user. The source and
target language must be entered in the command line, and there should be an option
\texttt{--help} available.

% }}}

\section{Protocol} % {{{
\label{sec:Protocol}

The Google Translate API can be called with an HTTP GET request. To be able to
use the API, we need an ``API key'', which we have obtained from the Google API
Console website. The request parameters should at least contain the API key, the
target language and one or more texts that are to be translated. If no source
language is specified in the parameters, the server will try to detect and
return the source language from the entered text values. Since our program
requires the source language to be specified, we will not use this
functionality. The request URL thus always has the following format:

\begin{verbatim}
https://www.googleapis.com/language/translate/v2?key={KEY}
    &source={SOURCE_LANGUAGE}&target={TARGET_LANGUAGE}&q={TEXT}
\end{verbatim}

The server's response to the request is in JSON (JavaScript Object Notation)
format which basically returns a structure containing all data in objects
or arrays. For more information on JSON, see
\url{http://en.wikipedia.org/wiki/JSON}.

Since the request format is consistent, a response will always be of the
following form:

\begin{verbatim}
{
    "data": {
        "translations": [
            {
                "translatedText": {TRANSLATED_TEXT}
            }
        ]
    }
}
\end{verbatim}

Of course, the response can also be a ``bad request'', we'll discuss this in
section \ref{sec:Implementation}.

% }}}

\section{Implementation} % {{{
\label{sec:Implementation}

The programming language that we used is PHP. The reason for this is the fact
that PHP has built in support for sending HTTP requests and parsing
JSON-formatted text. The program is located in the executable ``translate''.
Call the program with the argument '--help' to see documentation on how the
program should be called.

The program reads input from the user from \texttt{stdin}. When a newline
character is entered, the function \texttt{translate} is called with the entered
text. This function uses the built in PHP function \texttt{file\_get\_contents}
(\url{http://nl3.php.net/file_get_contents}) to call the Google Translate API using
the URL mentioned in section \ref{sec:Protocol}. This function returns
\texttt{false} on failure, which is handled by the program. To suppress any
warnings that are generated by a ``bad request''-error, we use \texttt{@} in
front of the function call. We can safely do this because we handle any
failures manually. The two most probable reasons for a ``bad request'' to occur,
are the lack of an internet connection and the invalidness of a specified
source/target language. Since both are critical for the program's ability to
function correctly, we have chosen to end the program after a bad request. If
the request is succesful, we use the built in PHP function \texttt{json\_decode}
to parse the response. The converts the JSON object into an associative array,
from which we can easily extract the translation:

\begin{verbatim}
return $response["data"]["translations"][0]["translatedText"];
\end{verbatim}

% }}}

\appendix

\section{Code} % {{{
\input{translate}

% }}}

\end{document}
