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

Google's Highly Open Participation Program tries to get young students into Open Source and Joomla! specifically. Everyone is welcome, there are not limits. You can be a coder, documenter, tester, translator to help out. Jump in and start helping!
User avatar
milosz.lewandowski
Joomla! Apprentice
Joomla! Apprentice
Posts: 19
Joined: Sat Dec 01, 2007 2:50 pm
Location: Lesko, Poland

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

Postby milosz.lewandowski » Sat Dec 01, 2007 2:59 pm

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]
Last edited by AmyStephen on Mon Dec 17, 2007 7:58 pm, edited 1 time in total.

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7056
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 091 - Write a document on how to create a language definition file for a Joo

Postby AmyStephen » Sun Dec 02, 2007 6:40 am

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 :)


User avatar
Roman Blanty
Joomla! Explorer
Joomla! Explorer
Posts: 372
Joined: Thu Aug 25, 2005 5:32 pm
Location: Internet
Contact:

Re: 091 - Write a document on how to create a language definition file for a Joo

Postby Roman Blanty » Sun Dec 09, 2007 4:50 pm

Powodzenia Miłoszu!
Jeśli będziesz potrzebował pomocy daj znać.
Pozdrawiam,
Viking
Polskie Centrum Joomla!
Proud Polish Joomla! Team Member > http://www.joomla.pl
Hardcore Translator ;)
Joomla! Translation Coordination Team
Jobs in IT: http://www.workita.com

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7056
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 091 - Write a document on how to create a language definition file for a Joo

Postby AmyStephen » Mon Dec 10, 2007 6:28 am

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 :)

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1382
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: 091 - Write a document on how to create a language definition file for a Joo

Postby Chris Davenport » Mon Dec 10, 2007 5:57 pm

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.
Chris Davenport - Joomla Production Leadership Team

Lion Coppice http://www.lioncoppice.org/
Davenport Technology Services http://www.davenporttechnology.com/

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7056
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 091 - Write a document on how to create a language definition file for a Joo

Postby AmyStephen » Fri Dec 14, 2007 2:35 am

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 :)

User avatar
milosz.lewandowski
Joomla! Apprentice
Joomla! Apprentice
Posts: 19
Joined: Sat Dec 01, 2007 2:50 pm
Location: Lesko, Poland

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

Postby milosz.lewandowski » Fri Dec 14, 2007 5:48 pm

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

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1382
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: 091 - Write a document on how to create a language definition file for a Joo

Postby Chris Davenport » Sun Dec 16, 2007 5:01 pm

Hi Milosz,

milosz.lewandowski wrote: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.
Chris Davenport - Joomla Production Leadership Team

Lion Coppice http://www.lioncoppice.org/
Davenport Technology Services http://www.davenporttechnology.com/

User avatar
milosz.lewandowski
Joomla! Apprentice
Joomla! Apprentice
Posts: 19
Joined: Sat Dec 01, 2007 2:50 pm
Location: Lesko, Poland

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

Postby milosz.lewandowski » Mon Dec 17, 2007 7:26 pm

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

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


Milosz

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7056
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 091 - Write a document on how to create a language definition file for a Joo

Postby AmyStephen » Mon Dec 17, 2007 7:52 pm

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 :)

User avatar
milosz.lewandowski
Joomla! Apprentice
Joomla! Apprentice
Posts: 19
Joined: Sat Dec 01, 2007 2:50 pm
Location: Lesko, Poland

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

Postby milosz.lewandowski » Mon Dec 17, 2007 8:41 pm

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


Return to “Google's Highly Open Participation Contest”

Who is online

Users browsing this forum: No registered users and 0 guests