KnowledgeTree Internationalisation (i18n)
-----------------------------------------

Overview
--------
Support for i18n has been added to the KnowledgeTree (except for images), and
KnowledgeTree is ready to accept translations.  This is a mammoth task that
will require the support and aid of the KnowledgeTree community :)

Jam Warehouse can assist organisations in getting or keeping KnowledgeTree
translated into a language, please contact them at
kt-questions@jamwarehouse.com if that is of interest.

Requirements
------------

i18n requires gettext (http://www.gnu.org/software/gettext) and the gettext php module to work
(see http://php.net/gettext for installation instructions).

Completed Tasks and Implementation Details
------------------------------------------

- i18n/<locale>/LC_MESSAGES/knowledgeTree.mo
							knowledgeTree.po
			   /graphics
			   
- gettext support loaded if php module available

- all active (ie, not disabled) content in documents marked up

- checks the browser's Accept-Language header and uses that language (if there is a translation for it)

The TODO List
-------------

Images have not yet been done.


Guidelines
----------

Here are some guidelines for adding gettext support to the KnowledgeTree.

- find translatable strings and wrap literals with _() eg. 
	original:
    $sToRender .= "\t\t\t\t<th class=\"sectionHeading\" colspan=\"2\"><font color=\"ffffff\">Pending Web Documents</font></th>\n";		
	i18n'd:
    $sToRender .= "\t\t\t\t<th class=\"sectionHeading\" colspan=\"2\"><font color=\"ffffff\">" . _("Pending Web Documents") . "</font></th>\n";			

- if strings are concatenated with dynamic content use sprintf eg.
	original:	
    $sToRender .= "\t\t<td>Hi " . $sUserName . ", welcome back to the " . lookupField($default->organisations_table, "name", "id", $default->organisationID) . 
    			  "DMS, part of the Knowledge Tree</td>\n";	
	i18n'd:
    $sToRender .= "\t\t<td>" . sprintf(_('Hi %s, welcome back to the %s DMS, part of the Knowledge Tree'), 
    									$sUserName, 
    									lookupField($default->organisations_table, "name", "id", $default->organisationID)) . 
    			   "</td>\n";

- images- use the imgSrc function to dynamically use the images in the i18n directory (if they exist) eg.
	original:
    $sToRender .= "\t\t<td><img src=\"$default->graphicsUrl/welcome.gif\" border=\"0\"/></td>\n";		
	i18n'd:
    $sToRender .= "\t\t<td><img src=\"" . imgSrc("welcome.gif") . "\" border=\"0\"/></td>\n";	

Images to translate
-------------------
heading.gif: Document Management System
welcome.gif: Welcome to the Knowledge Tree
search.gif: SEARCH
tree.gif: KnowledgeTree (no translate?)

widgets/add.gif: Add
widgets/cancel.gif: Cancel
widgets/next.gif: Next
widgets/back.gif: Back
widgets/addcomment.gif: Add Comment
widgets/subscribe.gif: Subscribe
widgets/unsubscribe.gif: Unsubscribe
widgets/reject.gif: Reject
widgets/updatePassword.gif: Update Password
widgets/delete.gif: Delete
widgets/select.gif: Select
widgets/update.gif: Update
widgets/assign.gif: Assign
widgets/search.gif: Search
widgets/edit.gif: Edit
widgets/approve.gif: Approve
widgets/done.gif: Done
widgets/publish.gif: Publish
widgets/move.gif: Move
widgets/remove.gif: Remove
widgets/restore.gif: Restore
widgets/submit.gif: Submit
widgets/expunge.gif: Expunge
widgets/restorehere.gif: Restore Here
widgets/reply.gif: Reply
widgets/new.gif: New
widgets/reset.gif: Reset
widgets/archive.gif: Archive
widgets/browse.gif: Browse
widgets/checkin.gif: Check In
widgets/checkout.gif: Check Out
widgets/download.gif: Download
widgets/email.gif: Email
widgets/movehere.gif: Move Here
widgets/begin.gif: Begin
	
Testing
-------
- install gettext command line utilities
- run xgettext to generate .po files eg.
Neil quite likes:
  $ find . -type f | xgettext --no-wrap -d knowledgeTree -L PHP -s -f - -o i18n/knowledgeTree.po

Michael was using:
  xgettext --files-from=i18n/file-list -LPHP --keyword=_ --no-wrap --msgid-bugs-address="kt-i18n@jamwarehouse.com" -o knowledgeTree.po

- write a test translation by editing the po file appropriately.  if you have problems with the order of parameters, because your language's
  ordering is different then in english. You can use the $ to change order eg: 
        msgid "Upgrading item %d of %d"
        msgstr "... %2$d ... %1$d ..."
- construct the right directory structure inside i18n eg.
  $ mkdir -p i18n/es/LC_MESSAGES/	        
- upgrade the existing .po files in each translation using:
  $ mv knowledgeTree.po old.po
  $ msgmerge --no-wrap old.po ../knowledgeTree.po --output-file=knowledgeTree.po
  $ rm old.po
- use msgfmt to compile your translated .po file to a .mo
  $ msgfmt --check $knowldgeTree.po --output-file=i18n/$es/LC_MESSAGES/knowledgeTree.mo
- change $default->defaultLanguage in config/environment.php and verify your translation.

$Id$