====== Internalization of Reason Phrases ======
**Contact:** [[jan@iptel.org|Jan Janak]]

If you ever looked at any SIP reply, you probably noticed that the first line
of the reply contains a number code followed by a reason phrase. The purpose
of the reason phrase is to provide a human readable text, this is a fact
that is little known today, when most SIP user agents are hardware devices
which often resemble traditional phones with limited display capabilities.

The situation can be, however, different for software user agents, running
on user's computer. Such user agents have access to the screen and thus they
can provide the user with more information than traditional HW phones, for
example, with the text from the reason phrase.

So, when the sip-router server sends back "Trying--your call is important to us" 
while it is working hard on routing the user's request towards its destination, 
wouldn't it be nice if the user was told that his/her call is important to the
nice people operating the server? We think so. And it would be even better if
such nice and informative messages were translated into the user's mother tongue,
so that he/she could enjoy them even more.

The goal of this work topic is to develop a sip-router module which can translate
reason phrases in replies passing through the server on the fly. The module shall
load a set of plain-text configuration files with text translations at server
startup and translate the text based on user's language preferences and the
contents of those configuration files.

The initial version of the translation module should only translate reason phrases
in replies that the server receives from other hosts, i.e. other servers or user
agents. The second version of the module shall also translate reason phrases in
locally generate SIP replies (this is slightly more difficult).

The format of language files is not yet decided. Here is one suggestion:
<code>
# Format:
#    [Language]
#    <code>:<reason_regex>:<new_reason>
#
[en_US.ascii]
100::Trying
180::Ringing
181::Call Is Being Forwarded
182::Queued
183::Session Progress
200::OK
202::Pending
300::Multiple Choices

[cs_CZ.iso-8859-2]
100::Navazuji spojeni
100:.*important to us.*:Vytacim - vas hovor je pro nas nejdulezitejsi
180::Vyzvani
181::Hovor byl presmerovan
182::Jste v poradi
183::Probiha navazovani spojeni
200::Uspesne zpracovano
202::Bude vyrizeno pozdeji
300::Vice moznosti
</code>

Translations are arranged into sections according to the language. Each line
contains three elements delimited by ':'. The first element is the reason
code. This reason code must match the reason code in the reply in order for
the line to take effect.

The second line is an optional regular expression. If the regular expression
is not empty then it will be matched against the incoming reason text and the
line will be applied if and only if both the reason code and the regular
expression match. 

The third element is the new reason phrase text (in the destination language).