forked from extern/egroupware
491 lines
8.1 KiB
HTML
491 lines
8.1 KiB
HTML
<HTML
|
||
><HEAD
|
||
><TITLE
|
||
>Using Language Support</TITLE
|
||
><META
|
||
NAME="GENERATOR"
|
||
CONTENT="Modular DocBook HTML Stylesheet Version 1.52"><LINK
|
||
REL="HOME"
|
||
TITLE="phpGroupWare Docs V0.05"
|
||
HREF="book1.html"><LINK
|
||
REL="UP"
|
||
TITLE="Developers Documentation"
|
||
HREF="p261.html"><LINK
|
||
REL="PREVIOUS"
|
||
TITLE="Configuration Variables"
|
||
HREF="devconfvar.html"><LINK
|
||
REL="NEXT"
|
||
TITLE="Using Templates"
|
||
HREF="devtemp.html"></HEAD
|
||
><BODY
|
||
CLASS="CHAPTER"
|
||
><DIV
|
||
CLASS="NAVHEADER"
|
||
><TABLE
|
||
WIDTH="100%"
|
||
BORDER="0"
|
||
CELLPADDING="0"
|
||
CELLSPACING="0"
|
||
><TR
|
||
><TH
|
||
COLSPAN="3"
|
||
ALIGN="center"
|
||
>phpGroupWare Docs V0.05</TH
|
||
></TR
|
||
><TR
|
||
><TD
|
||
WIDTH="10%"
|
||
ALIGN="left"
|
||
VALIGN="bottom"
|
||
><A
|
||
HREF="devconfvar.html"
|
||
>Prev</A
|
||
></TD
|
||
><TD
|
||
WIDTH="80%"
|
||
ALIGN="center"
|
||
VALIGN="bottom"
|
||
></TD
|
||
><TD
|
||
WIDTH="10%"
|
||
ALIGN="right"
|
||
VALIGN="bottom"
|
||
><A
|
||
HREF="devtemp.html"
|
||
>Next</A
|
||
></TD
|
||
></TR
|
||
></TABLE
|
||
><HR
|
||
ALIGN="LEFT"
|
||
WIDTH="100%"></DIV
|
||
><DIV
|
||
CLASS="CHAPTER"
|
||
><H1
|
||
><A
|
||
NAME="DEVLANGSUP"
|
||
>Chapter 27. Using Language Support</A
|
||
></H1
|
||
><DIV
|
||
CLASS="TOC"
|
||
><DL
|
||
><DT
|
||
><B
|
||
>Table of Contents</B
|
||
></DT
|
||
><DT
|
||
><A
|
||
HREF="devlangsup.html#AEN632"
|
||
>Overview</A
|
||
></DT
|
||
><DT
|
||
><A
|
||
HREF="devlangsup.html#AEN635"
|
||
>How to use lang support</A
|
||
></DT
|
||
><DT
|
||
><A
|
||
HREF="devlangsup.html#AEN644"
|
||
>The lang function</A
|
||
></DT
|
||
><DT
|
||
><A
|
||
HREF="devlangsup.html#AEN668"
|
||
>Adding translation data</A
|
||
></DT
|
||
><DT
|
||
><A
|
||
HREF="devlangsup.html#AEN672"
|
||
>The lang table</A
|
||
></DT
|
||
><DT
|
||
><A
|
||
HREF="devlangsup.html#AEN695"
|
||
>lang.sql</A
|
||
></DT
|
||
><DT
|
||
><A
|
||
HREF="devlangsup.html#AEN706"
|
||
>Common return codes</A
|
||
></DT
|
||
></DL
|
||
></DIV
|
||
><DIV
|
||
CLASS="SIMPLESECT"
|
||
><H4
|
||
CLASS="SIMPLESECT"
|
||
><A
|
||
NAME="AEN632"
|
||
>Overview</A
|
||
></H4
|
||
><P
|
||
> phpGroupWare is built using a multi-language support scheme. This means the pages can be
|
||
translated to other languages very easily. Translations of text strings are
|
||
stored in the phpGroupWare database, and can be modified by the phpGroupWare
|
||
administrator.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="SIMPLESECT"
|
||
><H4
|
||
CLASS="SIMPLESECT"
|
||
><A
|
||
NAME="AEN635"
|
||
>How to use lang support</A
|
||
></H4
|
||
><P
|
||
> The <TT
|
||
CLASS="CLASSNAME"
|
||
>lang()</TT
|
||
> function is your application's interface to phpGroupWare's
|
||
internationalization support.
|
||
|
||
While developing your application, just wrap all your text output with calls to
|
||
lang(), as in the following code:
|
||
<TABLE
|
||
BORDER="0"
|
||
BGCOLOR="#E0E0E0"
|
||
WIDTH="100%"
|
||
><TR
|
||
><TD
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
> $x = 42;
|
||
echo lang("The counter is %1",$x)."<br>";</PRE
|
||
></TD
|
||
></TR
|
||
></TABLE
|
||
>
|
||
This will attempt to translate "The counter is %1", and return a translated version
|
||
based on the current application and language in use. Note how the position that
|
||
<TT
|
||
CLASS="CLASSNAME"
|
||
>$x</TT
|
||
> will end up is controlled by the format string, <I
|
||
CLASS="EMPHASIS"
|
||
>not</I
|
||
> by
|
||
building up the string in your code. This allows your application to be translated
|
||
to languages where the actual number is not placed at the end of the string.
|
||
|
||
When a translation is not found, the original text will be returned with a * after
|
||
the string. This makes it easy to develop your application, then go back and
|
||
add missing translations (identified by the *) later.
|
||
|
||
Without a specific translation in the lang table, the above code will print:
|
||
<TT
|
||
CLASS="CLASSNAME"
|
||
>The counter is 42*<br></TT
|
||
>
|
||
If the current user speaks Italian, they string returned may instead be:
|
||
<TT
|
||
CLASS="CLASSNAME"
|
||
>il contatore <20> 42<br></TT
|
||
>
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="SIMPLESECT"
|
||
><H4
|
||
CLASS="SIMPLESECT"
|
||
><A
|
||
NAME="AEN644"
|
||
>The lang function</A
|
||
></H4
|
||
><P
|
||
> <TT
|
||
CLASS="CLASSNAME"
|
||
>lang($key, $m1="", $m2="", $m3="", $m4="", $m5="",
|
||
$m6="", $m7="", $m8="", $m9="", $m10="")
|
||
</TT
|
||
>
|
||
<P
|
||
></P
|
||
><DIV
|
||
CLASS="VARIABLELIST"
|
||
><DL
|
||
><DT
|
||
>$key</DT
|
||
><DD
|
||
><P
|
||
>is the string to translate and may contain replacement directives of the form <TT
|
||
CLASS="CLASSNAME"
|
||
>%n</TT
|
||
>. </P
|
||
></DD
|
||
><DT
|
||
>$m1</DT
|
||
><DD
|
||
><P
|
||
> is the first replacement value or may be an array of replacement values (in which case $m2 and above are ignored). </P
|
||
></DD
|
||
><DT
|
||
>$m2</DT
|
||
><DD
|
||
><P
|
||
>- $m10/ the 2nd through 10th replacement values if $m1 is not an array. </P
|
||
></DD
|
||
></DL
|
||
></DIV
|
||
>
|
||
The database is searched for rows with a <TT
|
||
CLASS="CLASSNAME"
|
||
>lang.message_id</TT
|
||
> that matches <TT
|
||
CLASS="CLASSNAME"
|
||
>$key</TT
|
||
>.
|
||
If a translation is not found, the original <TT
|
||
CLASS="CLASSNAME"
|
||
>$key</TT
|
||
> is used. The translation engine then replaces
|
||
all tokens of the form <TT
|
||
CLASS="CLASSNAME"
|
||
>%N</TT
|
||
> with the Nth parameter (either <TT
|
||
CLASS="CLASSNAME"
|
||
>$m1[N]</TT
|
||
> or <TT
|
||
CLASS="CLASSNAME"
|
||
>$mN</TT
|
||
>).
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="SIMPLESECT"
|
||
><H4
|
||
CLASS="SIMPLESECT"
|
||
><A
|
||
NAME="AEN668"
|
||
>Adding translation data</A
|
||
></H4
|
||
><P
|
||
> An application called <I
|
||
CLASS="EMPHASIS"
|
||
>Transy</I
|
||
> is being developed to make this easier, until then you can create
|
||
the translation data manually.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="SIMPLESECT"
|
||
><H4
|
||
CLASS="SIMPLESECT"
|
||
><A
|
||
NAME="AEN672"
|
||
>The lang table</A
|
||
></H4
|
||
><P
|
||
> The translation class uses the lang table for all translations.
|
||
We are concerned with 4 of the columns to create a translation:
|
||
<P
|
||
></P
|
||
><DIV
|
||
CLASS="VARIABLELIST"
|
||
><DL
|
||
><DT
|
||
>message_id</DT
|
||
><DD
|
||
><P
|
||
> The key to identify the message (the <TT
|
||
CLASS="CLASSNAME"
|
||
>$key</TT
|
||
> passed
|
||
to the <TT
|
||
CLASS="CLASSNAME"
|
||
>lang()</TT
|
||
> function). This is written in English.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>app_name</DT
|
||
><DD
|
||
><P
|
||
> The application the translation applies to, or
|
||
<TT
|
||
CLASS="CLASSNAME"
|
||
>common</TT
|
||
> if it is common across multiple applications.
|
||
</P
|
||
></DD
|
||
><DT
|
||
>lang</DT
|
||
><DD
|
||
><P
|
||
>The code for the language the translation is in. </P
|
||
></DD
|
||
><DT
|
||
>content</DT
|
||
><DD
|
||
><P
|
||
>The translated string. </P
|
||
></DD
|
||
></DL
|
||
></DIV
|
||
>
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="SIMPLESECT"
|
||
><H4
|
||
CLASS="SIMPLESECT"
|
||
><A
|
||
NAME="AEN695"
|
||
>lang.sql</A
|
||
></H4
|
||
><P
|
||
> Currently all applications, and the core phpGroupWare source tree
|
||
have a <TT
|
||
CLASS="CLASSNAME"
|
||
>lang.sql</TT
|
||
> file. This is the place to add translation
|
||
data. Just add lines of the form:
|
||
<TABLE
|
||
BORDER="0"
|
||
BGCOLOR="#E0E0E0"
|
||
WIDTH="100%"
|
||
><TR
|
||
><TD
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
>REPLACE INTO lang (message_id, app_name, lang, content)
|
||
VALUES( 'account has been deleted','common','en','Account has been deleted');</PRE
|
||
></TD
|
||
></TR
|
||
></TABLE
|
||
>
|
||
translating the <TT
|
||
CLASS="CLASSNAME"
|
||
>content</TT
|
||
> to reflect the <TT
|
||
CLASS="CLASSNAME"
|
||
>message_id</TT
|
||
> string in the <TT
|
||
CLASS="CLASSNAME"
|
||
>lang</TT
|
||
> language.
|
||
If the string is specific to your application, put your application name in for <TT
|
||
CLASS="CLASSNAME"
|
||
>app_name</TT
|
||
>
|
||
otherwise use the name <TT
|
||
CLASS="CLASSNAME"
|
||
>common</TT
|
||
>. The <TT
|
||
CLASS="CLASSNAME"
|
||
>message_id</TT
|
||
> should be in lower case for a small
|
||
increase in speed.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="SIMPLESECT"
|
||
><H4
|
||
CLASS="SIMPLESECT"
|
||
><A
|
||
NAME="AEN706"
|
||
>Common return codes</A
|
||
></H4
|
||
><P
|
||
> If you browse through the phpGroupWare sources, you may notice
|
||
a pattern to the return codes used in the higher-level functions.
|
||
The codes used are partially documented in the <TT
|
||
CLASS="CLASSNAME"
|
||
>doc/developers/CODES</TT
|
||
>
|
||
file.
|
||
|
||
Codes are used as a simple way to communicate common error and progress
|
||
conditions back to the user. They are mapped to a text string through the
|
||
<TT
|
||
CLASS="CLASSNAME"
|
||
>check_code()</TT
|
||
> function, which passes the strings through
|
||
<TT
|
||
CLASS="CLASSNAME"
|
||
>lang()</TT
|
||
> before returning.
|
||
|
||
For example, calling
|
||
<TABLE
|
||
BORDER="0"
|
||
BGCOLOR="#E0E0E0"
|
||
WIDTH="100%"
|
||
><TR
|
||
><TD
|
||
><PRE
|
||
CLASS="PROGRAMLISTING"
|
||
>echo check_code(13);</PRE
|
||
></TD
|
||
></TR
|
||
></TABLE
|
||
>
|
||
Would print
|
||
<TT
|
||
CLASS="CLASSNAME"
|
||
>Your message has been sent</TT
|
||
>
|
||
translated into the current language.
|
||
</P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="NAVFOOTER"
|
||
><HR
|
||
ALIGN="LEFT"
|
||
WIDTH="100%"><TABLE
|
||
WIDTH="100%"
|
||
BORDER="0"
|
||
CELLPADDING="0"
|
||
CELLSPACING="0"
|
||
><TR
|
||
><TD
|
||
WIDTH="33%"
|
||
ALIGN="left"
|
||
VALIGN="top"
|
||
><A
|
||
HREF="devconfvar.html"
|
||
>Prev</A
|
||
></TD
|
||
><TD
|
||
WIDTH="34%"
|
||
ALIGN="center"
|
||
VALIGN="top"
|
||
><A
|
||
HREF="book1.html"
|
||
>Home</A
|
||
></TD
|
||
><TD
|
||
WIDTH="33%"
|
||
ALIGN="right"
|
||
VALIGN="top"
|
||
><A
|
||
HREF="devtemp.html"
|
||
>Next</A
|
||
></TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
WIDTH="33%"
|
||
ALIGN="left"
|
||
VALIGN="top"
|
||
>Configuration Variables</TD
|
||
><TD
|
||
WIDTH="34%"
|
||
ALIGN="center"
|
||
VALIGN="top"
|
||
><A
|
||
HREF="p261.html"
|
||
>Up</A
|
||
></TD
|
||
><TD
|
||
WIDTH="33%"
|
||
ALIGN="right"
|
||
VALIGN="top"
|
||
>Using Templates</TD
|
||
></TR
|
||
></TABLE
|
||
></DIV
|
||
></BODY
|
||
></HTML
|
||
> |