mirror of
https://github.com/EGroupware/egroupware.git
synced 2024-11-23 00:13:35 +01:00
5f45b54f92
Added docs on the DB based lang() function, and the standard return codes. Ran the whole thing through aspell to clean up typos.
137 lines
5.2 KiB
HTML
137 lines
5.2 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||
<HTML>
|
||
<HEAD>
|
||
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
|
||
<TITLE> phpGroupWare Application Development: Using Language Support</TITLE>
|
||
<LINK HREF="phpGW_Developers-HOWTO-8.html" REL=next>
|
||
<LINK HREF="phpGW_Developers-HOWTO-6.html" REL=previous>
|
||
<LINK HREF="phpGW_Developers-HOWTO.html#toc7" REL=contents>
|
||
</HEAD>
|
||
<BODY>
|
||
<A HREF="phpGW_Developers-HOWTO-8.html">Next</A>
|
||
<A HREF="phpGW_Developers-HOWTO-6.html">Previous</A>
|
||
<A HREF="phpGW_Developers-HOWTO.html#toc7">Contents</A>
|
||
<HR>
|
||
<H2><A NAME="s7">7. Using Language Support</A></H2>
|
||
|
||
<H2><A NAME="ss7.1">7.1 Overview</A>
|
||
</H2>
|
||
|
||
<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.
|
||
<H2><A NAME="ss7.2">7.2 How to use lang support</A>
|
||
</H2>
|
||
|
||
<P>The <CODE>lang()</CODE> function is your application's interface to phpGroupWare's
|
||
internationalization support.
|
||
<P>While developing your application, just wrap all your text output with calls to
|
||
lang(), as in the following code:
|
||
<HR>
|
||
<PRE>
|
||
$x = 42;
|
||
echo lang("The counter is %1",$x)."<br>";
|
||
</PRE>
|
||
<HR>
|
||
|
||
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
|
||
<CODE>$x</CODE> will end up is controlled by the format string, <B>not</B> 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.
|
||
<P>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.
|
||
<P>Without a specific translation in the lang table, the above code will print:
|
||
<PRE>
|
||
The counter is 42*<br>
|
||
</PRE>
|
||
|
||
If the current user speaks Italian, they string returned may instead be:
|
||
<PRE>
|
||
il contatore <20> 42<br>
|
||
</PRE>
|
||
<H3>The lang function</H3>
|
||
|
||
<P>
|
||
<PRE>
|
||
lang($key, $m1="", $m2="", $m3="", $m4="", $m5="",
|
||
$m6="", $m7="", $m8="", $m9="", $m10="")
|
||
</PRE>
|
||
|
||
<DL>
|
||
<DT><B>$key</B><DD><P>is the string to translate and may contain replacement directives of the form <CODE>%n</CODE>.<BR>
|
||
<DT><B>$m1</B><DD><P>is the first replacement value or may be an array of replacement values
|
||
(in which case $m2 and above are ignored).
|
||
<DT><B>$m2 - $m10</B><DD><P>the 2nd through 10th replacement values if $m1 is not an array.
|
||
</DL>
|
||
|
||
The database is searched for rows with a <CODE>lang.message_id</CODE> that matches <CODE>$key</CODE>.
|
||
If a translation is not found, the original <CODE>$key</CODE> is used. The translation engine then replaces
|
||
all tokens of the form <CODE>%N</CODE> with the Nth parameter (either <CODE>$m1[N]</CODE> or <CODE>$mN</CODE>).
|
||
<H3>Adding translation data</H3>
|
||
|
||
<P>An application called <B>Transy</B> is being developed to make this easier, until then you can create
|
||
the translation data manually.
|
||
<P>
|
||
<H3>The lang table</H3>
|
||
|
||
<P>The translation class uses the lang table for all translations.
|
||
We are concerned with 4 of the columns to create a translation:
|
||
<DL>
|
||
<DT><B>message_id</B><DD><P>The key to identify the message (the <CODE>$key</CODE> passed
|
||
to the <CODE>lang()</CODE> function). This is written in English.
|
||
<DT><B>app_name</B><DD><P>The application the translation applies to, or
|
||
<CODE>common</CODE> if it is common across multiple applications.
|
||
<DT><B>lang</B><DD><P>The code for the language the translation is in.
|
||
<DT><B>content</B><DD><P>The translated string.
|
||
</DL>
|
||
<H3>lang.sql</H3>
|
||
|
||
<P>Currently all applications, and the core phpGroupWare source tree
|
||
have a <CODE>lang.sql</CODE> file. This is the place to add translation
|
||
data. Just add lines of the form:
|
||
<HR>
|
||
<PRE>
|
||
REPLACE INTO lang (message_id, app_name, lang, content)
|
||
VALUES( 'account has been deleted','common','en','Account has been deleted');
|
||
</PRE>
|
||
<HR>
|
||
|
||
translating the <CODE>content</CODE> to reflect the <CODE>message_id</CODE> string in the <CODE>lang</CODE> language.
|
||
If the string is specific to your application, put your application name in for <CODE>app_name</CODE>
|
||
otherwise use the name <CODE>common</CODE>. The <CODE>message_id</CODE> should be in lower case for a small
|
||
increase in speed.
|
||
<H2><A NAME="ss7.3">7.3 Common return codes</A>
|
||
</H2>
|
||
|
||
<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 <CODE>doc/developers/CODES</CODE>
|
||
file.
|
||
<P>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
|
||
<CODE>check_code()</CODE> function, which passes the strings through
|
||
<CODE>lang()</CODE> before returning.
|
||
<P>For example, calling
|
||
<HR>
|
||
<PRE>
|
||
echo check_code(13);
|
||
</PRE>
|
||
<HR>
|
||
|
||
Would print
|
||
<PRE>
|
||
Your message has been sent
|
||
</PRE>
|
||
|
||
translated into the current language.
|
||
<P>
|
||
<HR>
|
||
<A HREF="phpGW_Developers-HOWTO-8.html">Next</A>
|
||
<A HREF="phpGW_Developers-HOWTO-6.html">Previous</A>
|
||
<A HREF="phpGW_Developers-HOWTO.html#toc7">Contents</A>
|
||
</BODY>
|
||
</HTML>
|