091 - Write a document on how to create a language definition file for a Joomla!

[milosz.lewandowski]

Hi everybody,
My name's Milosz, I'm from Poland.  I claimed Issue 91, so I will write part of Joomla 1.5 Template Tutorial. I like Joomla! and writing documentation, so I suppose it will be great fun.

Good luck everybody!
Milosz

Claimed: Dec 1 Due Dec 8


Google Task
[me=AmyStephen]Changed subject slightly for sorting all threads to match against Google resource  [/me]

[AmyStephen]

Welcome to Joomla! Milosz -

So pleased that you joined the GHOP contest and I appreciate your contributions to our community. I am going to include the entire task description so that community members understand the task you are performing. Please, feel free to ask questions and for assistance. We are here to help you be successful with Joomla!

One line summary
Write a document on how to create a language definition file for a Joomla!
1.5 template.

Description
This task involves writing documentation to be incorporated into the
Joomla! 1.5 Template Tutorials on creating a language definition (INI) file
for a Joomla! 1.5 template. This document should cover where the INI file
should be located, the syntax of its entries and how to add a reference to
it in the templateDetails.xml file. It should include appropriately
annotated screenshots.

The document should comply with current Joomla! Editorial Style Guidelines
and guidelines for the Template Tutorials Project.

Documentation written for this task must be made available under the
Joomla! Electronic Documentation License.

Skills Needed

Difficulty
Basic.

Work Product
Appropriately illustrated document as specified.

Extra Credit (optional)
Extend the document to include details on how to embed translatable strings
into a template file.

Amy

[AmyStephen]

GHOP Contestants Please Read: Task Process Start to Finish for important updates on the contest.

[Roman Blanty]

Powodzenia Miłoszu!
Jeśli będziesz potrzebował pomocy daj znać.
Pozdrawiam,
Viking
Polskie Centrum Joomla!

[AmyStephen]

COMMUNITY REVIEW: Please review the final copy posted on Google.

That looks very, very good. We will try to quickly get some review going.

Thanks for your contributions to the Joomla! community,
Amy

[Chris Davenport]

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: Select all

<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.

[AmyStephen]

Milosz -

Please respond to Chris's comments, including his ideas for revisions into your final copy. Technically, your task was due several days ago, so we do need you to respond as qucikly as possible.

Thanks,
Amy

[milosz.lewandowski]

Hi All ,

I've uploaded updated file on GHOP Joomla Issue 91 site. Sorry for being behind with it.

Dear Chris,
I haven't found any informations about translating description from templateDetails.xml file.
I've tried to check JFilterInput, but it didn't work. Maybe I was doing something wrong? I haven't found many informations about it too, but I read and analyzed the suitable file in the /libraries/ directory and haven't found something helpful.

Best wishes,
Milosz

[Chris Davenport]

Hi Milosz,

I haven't found any informations about translating description from templateDetails.xml file.
I've tried to check JFilterInput, but it didn't work. Maybe I was doing something wrong? I haven't found many informations about it too, but I read and analyzed the suitable file in the /libraries/ directory and haven't found something helpful.

Okay, don't worry about it.  They were minor points anyway.

Well done on the latest version.  The only small amendment I would suggest is that the difference between printf and sprintf is not clear.  Perhaps a sentence to explain that?  The examples you use to show printf and sprintf in operation involve strings (%s) which are unlikely to be used in practice.  I would think that one of the numeric formats, such as %d, would make for better examples.

With these small amendments I would be happy to say "It's done!". 

Well done,
Chris.

[milosz.lewandowski]

OK, I've uploaded the file with these small changes.

http://code.google.com/p/google-highly- ... %20Summary


Milosz

[AmyStephen]

Thank you very, very much, Milosz, for this excellent work!

I marked the Google task as complete. You are free to choose another task, if desired.

Amy

[milosz.lewandowski]

Thank you very much too We will meet at the next issue soon