Hi Milosz,
Some good work here.
You state that "Character encoding of Joomla! INI files is always UTF-8". I think you should say "UTF-8 without Byte Order Mark (BOM)". Perhaps you could also include a URL for further information:
http://unicode.org/faq/utf_bom.html#BOM.
You should also mention that there is a separate language INI file for the administrator back-end of a site template:
Code:
<administration>
<languages folder="admin">
<language tag="en-GB">en-GB.tpl_beez.ini</language>
</languages>
</administration>
which will place the file in the /administrator/languages/ln-LN/ directory. The source directory for the file is given by the "folder" parameter.
At the end of the document you have included an example of translating a couple of strings into Polish. This is good, but I would also include the appropriate lines from the INI file too, so as to emphasize how the INI file lookup works (ie, the string on the left of the "=" is the key, on the right is the value that will replace the key string.
I'm not particularly keen on using images to illustrate something which is not inherently visual. Images create problems for the Doc Team as we generally have to host and maintain them separately from the textual material. They also cause problems for translators! I feel that the first three images could actually be replaced by text, suitably formatted so that it is clearly separated from the surrounding text.
You have described the use of the JText::_() method, but don't forget to describe how to use the JText::printf() and JText::sprintf() methods too.
Could be worth mentioning how to enable language debugging in Global Configuration and what effect that has.
You might like to include a note about what happens when duplicate keys are included in or between INI files. Basically, the last one encountered is the one that is used, but I'm not sure of the order in which the INI files are processed without looking at the code.
Perhaps you should mention that the right-hand side of an INI entry is passed through JFilterInput and so certain character sequences will be removed or replaced (I'm not sure of the details without further investigation).
Not sure what the status is on this one: I think it is/was possible to translate the
element in the templateDetails.xml file. This might not be working at the moment, in which case I wouldn't bother documenting it, but if it has been fixed, then it should be mentioned.
Good work!
Chris._________________
Joomla Leadership Team - Production Working Group
Joomla Web Services
http://www.kickstarter.com/projects/964120480/joomla-web-servicesLion Coppice
http://www.lioncoppice.org
