Xataface 0.6 adds i18n support (internationalization) via the Dataface_LanguageTool class which allows you to transform all interface text into the language of the user.  This version also adds support for multi-lingual database content (i.e., the ability to store records in multiple languages), but this how-to deals only with the translation of "static" text - i.e., text that is not drawn from the database.

Procedure for Internationalizing Your Interface

1. Create a directory named 'lang' in your application directory.  Inside this directory create a file for each translation in the form <languagename>.ini where <languagename> is the 2-digit ISO 639.2 language codes (found at http://www.loc.gov/standards/iso639-2/langcodes.html) . E.g., the English translation file will be called 'en.ini', and the French translation would be called 'fr.ini'.
   Your application directory structure would look something like this:
   
   
   
2. Make sure that Xataface has been initialized at some point in your code.  In a typical Xataface application this happens in the first couple of lines of your index.php file.:
   

   require_once '/path/to/dataface/dataface-public-api.php';
   df_init(__FILE__, 'http://www.yoursite.com/url/to/dataface');
   

3. From here on out, it is just a matter of "find and replace" - "Find" all places where text is generated to be displayed on the page, and replace this text with a call to df_translate() which translates the text to the appropriate language.  E.g.:
   

   echo "Welcome to my site";

   becomes
   

   echo df_translate(
         "Welcome",  // i18n id to reference text in your language files
         "Welcome to my site"  // Fallback text in case the selected language doesn't have the "Welcome" text defined
        );

4. Add entries in your language files for the translations.  E.g:
   The English language file (en.ini) would contain:
   

   Welcome = "Welcome to my site"

   and the French language file (fr.ini) would contain:
   

   Welcome = "Bienvenue à mon emplacement"
   

   *Note that this is a babelfish translation so it may not be accurate.

Caveats: Encoding

Xataface 0.6 uses UTF-8 to encode its web pages.  What this means is that you will need to use UTF-8 encoding for all of your language files (e.g., en.ini, fr.ini).  If you do not, some special characters such as "à" may be displayed as gibberish.  If your text editor supports UTF-8 encoding then there will likely  be a menu option to select the encoding of the document.  If it does not support UTF-8, you will need to download one that does.  A non-comprehensive list of editors supporting UTF-8 can be found at http://www.alanwood.net/unicode/utilities_editors_unix.html

Using Parameters

The "Welcome" example above is a very basic case.  There will, however, be many cases where you need to use parameters inside your translation.  For example, the text "Found 23 records in table 'Profiles'" should not need to have a separate translation for each possible number of records and each table.  For this, you can use parameters in your translation as follows.

Likely the PHP code that generates this text looks like:

echo "Found $found records in table '$table'";

Change it to:

echo df_translate(
      "Found records in table",  // i18n id
      "Found $found records in table '$table'", // fallback text
      array('found'=>$found, 'table'=>$table)  // Parameters for translation
     );

Then your en.ini file would look like:

Found records in table = "Found $found records in table $table"

and your fr.ini file would look like:

Found records in table = "A trouvé $found disques dans des '$table' de table"

Translating Smarty Templates

The best and easiest way to do Xataface development is by using Smarty templates with the Xataface SkinTool.  Most of Xataface's default UI uses teh Xataface SkinTool and templates.  Xataface SkinTool provides a number of additional tags that you can use in your templates.  The 'translate' is a wrapper for the df_translate() function that allows you to translate text in templates.  For example, in the template:

<h1>Welcome to my site</h1>

You would change it to:

<h1>{translate id="Welcome"}Welcome to my site{/translate}</h1>

The text between the {translate} tags is the fall-back text that will be displayed if no text with id "Welcome" can be found for the current language.
Your language file would be the same as the language files listed in corresponding example (with df_translate()).

Using Parameters in smarty templates

Suppose you wanted to translate the following text in your template:

<p>Found {$found} records in table {$table}</p>

Our translation will want to have parameters for $found and $table, so our internationalized template would look like:

<p>
   {translate id="Found records in table" found=$found table=$table}
          Found {$found} records in table {$table}
   {/translate}
</p>